alknet/docs/research/pivot/cleanup-plan.md

# Cleanup Plan: Pre-Pivot Housekeeping

> Status: Draft
> Created: 2026-06-15
> Purpose: Clean the workspace before starting the ALPN-as-service refactor so agents have a clear, bias-free starting point.

## Guiding Principles

1. **Delete noise, preserve signal.** If a document describes concepts that the pivot replaces or defers, it should be archived — not left in place where agents might pattern-match to the old model.
2. **Reference docs are a library, not a plan.** The `references/` directory (iroh, ssh, nats, etc.) is neutral research about external projects. Those stay. But gitserver is MPL — see below.
3. **ADRs that codify discarded abstractions become landmines.** An agent reading ADR-026 ("Transport/interface separation") will try to implement the three-layer model. These need to be marked superseded or archived.
4. **Code that stays should compile cleanly.** We're not rewriting yet — we're making the existing code a clean reference implementation to port from.
5. **Follow the SDD process.** This cleanup is preparation for Phase 0→1. After cleanup, the architect role will produce proper architecture specs following the format in `docs/sdd_process.md` — modular docs, ADRs, open questions, README index. No ad-hoc spec stubs.

---

## Phase 1: Archive Obsolete Architecture Docs

These documents describe concepts that the ALPN pivot **replaces entirely**. They're historical record, not guidance. Move to `docs/_archived/` (preserved in git history, out of sight for agents).

### Architecture docs to archive

| Document | Reason |
|----------|--------|
| `docs/architecture/interface.md` | Defines `StreamInterface` / `MessageInterface` — replaced by `ProtocolHandler` |
| `docs/architecture/services.md` | Defines irpc service layer, `OperationEnv` three dispatch paths — replaced by ALPN dispatch |
| `docs/architecture/call-protocol.md` | Describes `OperationEnv` composition model — will be rewritten for `alknet-call` |
| `docs/architecture/storage.md` | Metagraph/data model — deferred per pivot |
| `docs/architecture/flowgraph.md` | FlowGraph crate — deferred per pivot |
| `docs/architecture/credentials.md` | `CredentialProvider` phases A–D — simplifying per pivot |
| `docs/architecture/napi-and-pubsub.md` | Describes pubsub event target adapter through SSH control channel — old model |
| `docs/architecture/open-questions.md` | Most open questions are about the old model; will regenerate after pivot |
| `docs/architecture/tun-shim.md` | Already deprecated |

### ADRs to mark superseded

These ADRs codify abstractions that the pivot replaces. Don't delete — mark them with a clear `Superseded` status and a pointer to the pivot doc so agents don't treat them as current guidance.

| ADR | Title | Superseded by |
|-----|-------|---------------|
| 026 | Transport/interface separation (three-layer model) | ALPN dispatch — one trait, one dispatch point |
| 035 | StreamInterface / MessageInterface split | `ProtocolHandler` trait replaces both |
| 033 | OperationEnv as universal composition mechanism | Call protocol is one ALPN; no three dispatch paths |
| 027 | Crate decomposition (core, storage, flowgraph) | New crate decomposition per pivot |
| 028 | Auth as irpc service behind feature flag | Auth is shared in `alknet-core`, not an irpc service |
| 032 | Event boundary discipline (domain, irpc, call) | Simplified — each handler manages its own wire format |
| 018 | Control channel for pubsub over SSH | Pubsub is a handler concern, not a SSH control channel |
| 017 | Stealth mode — protocol multiplexing on port 443 | ALPN negotiation replaces byte-peek protocol detection |

### ADRs that remain valid

These capture decisions that carry forward regardless of the refactor:

| ADR | Title | Why it stays |
|-----|-------|--------------|
| 001 | Pluggable transport via `AsyncRead+AsyncWrite` | Still true — `BiStream` implements these traits |
| 003 | iroh stream via `tokio::io::join` | Still relevant for iroh transport |
| 004 | SSH runs over transport, not alongside | Still true — SSH is one ALPN handler |
| 005 | SOCKS5 as primary client interface | Still true for `alknet-ssh` |
| 006 | No logging of tunnel destinations | Security principle, always valid |
| 008 | ACME/Let's Encrypt certificate provisioning | Still needed for TLS endpoints |
| 012 | Ed25519 keys + OpenSSH cert-authority | Auth model carries forward |
| 013 | Fail2ban-friendly logging | Still relevant |
| 023 | Unified auth with shared key material + token auth | Becomes `IdentityProvider` in core |
| 024 | Bidirectional call protocol (EventEnvelope) | EventEnvelope framing carries into `alknet-call` |
| 025 | Handler/spec separation | Still a good pattern — each ALPN handler has its own spec |
| 029 | Identity as core type in alknet-core | Still true |
| 030 | Static/dynamic config split with ArcSwap | Still true — `ArcSwap<DynamicConfig>` pattern continues |
| 031 | Forwarding policy with rule-based allow/deny | Still relevant for `alknet-ssh` |
| 037 | API keys as DynamicConfig auth | Carries forward |
| 038 | Seed lifecycle and memory security | `alknet-secret` is standalone, unchanged |

### ADRs to archive (deferred/irrelevant)

| ADR | Title | Reason |
|-----|-------|--------|
| 002 | TUN shim as separate process | Already superseded by ADR-014 |
| 007 | NAPI exposes single duplex stream | Needs rewrite — NAPI becomes call protocol client |
| 009 | Default iroh relay with override | Low-level transport detail, not an architecture decision |
| 010 | Transport chaining in CLI | CLI UX detail, revisit when building new CLI |
| 011 | Programmatic-first API, no file-based config | CLI detail, revisit |
| 014 | Defer TUN, recommend SOCKS5 + tun2proxy | Still valid direction but already noted as deferred |
| 015 | napi-rs for FFI bridge | Implementation detail, revisit |
| 016 | NAPI exposes both connect() and serve() | Needs rewrite for new model |
| 019 | Proxy dual semantics | CLI detail, revisit |
| 034 | Head/worker terminology | Terminology, not architecture; revisit |
| 036 | CredentialProvider as core type | Simplifying per pivot |

---

## Phase 2: Clean Up Research Docs

### Keep as-is (neutral external references)

- `docs/research/references/iroh/` — ALPN dispatch, QUIC endpoints, protocol handler pattern
- `docs/research/references/ssh/russh/` — SSH implementation reference for `alknet-ssh`
- `docs/research/references/ssh/russh-sftp/` — SFTP protocol reference for `alknet-sftp`
- `docs/research/references/ssh/sftp-rs/` — SFTP comparison reference
- `docs/research/references/nats.rs/` — Service/pattern reference (not directly used but neutral)
- `docs/research/references/honker/` — SQLite pub/sub, queues, streams — may be relevant for in-node event system
- `docs/research/references/polyglot/` — FFI patterns for NAPI/WASM
- `docs/research/references/openstack-keystone/` — Auth patterns reference
- `docs/research/references/rustfs/` — S3-compatible object storage reference
- `docs/research/references/gitlfs/rudolfs-reference.md` — Git LFS server reference (MIT/Apache-2.0, fork candidate)
- `docs/research/ops/` — fail2ban, certbot — production reference, still useful
- `docs/research/feasibility/` — Historical context, keep

### Handle MPL-licensed reference

**`docs/research/references/gitserver/gitserver-reference.md`** — This references an MPL-2.0 project. The reference doc itself is our analysis, not derived work. However, since the git adapter will use `gix` (Apache-2.0/MIT) directly — not gitserver — keeping this doc around creates risk of an agent copying structure or logic from the MPL codebase.

**Action:** Archive it. Replace with a `gix`-focused reference when we spec the git adapter. The research value is the git protocol knowledge, not the gitserver code structure.

### Archive (biased toward old model)

| Document | Reason |
|----------|--------|
| `docs/research/core.md` | Describes the three-layer model in detail — superseded by pivot |
| `docs/research/services.md` | Describes irpc service layer, OperationEnv — superseded |
| `docs/research/storage.md` | Metagraph — deferred |
| `docs/research/flow.md` | FlowGraph — deferred |
| `docs/research/configuration.md` | Promoted to architecture docs already |
| `docs/research/integration-plan.md` | Phase-based integration plan for old model — superseded |
| `docs/research/phase2/interface-model.md` | StreamInterface/MessageInterface analysis — superseded |
| `docs/research/phase2/credential-provider.md` | CredentialProvider phases — simplifying |
| `docs/research/phase2/definitions.md` | Promoted to architecture already |
| `docs/research/phase2/tls-transport.md` | Describes stealth mode — ALPN replaces this |
| `docs/research/event-sourcing/` | Event sourcing patterns — not currently needed |

### Keep but annotate

| Document | Reason |
|----------|--------|
| `docs/research/pivot/alpn-service-architecture.md` | **The pivot proposal.** Current. |
| `docs/research/pivot/cleanup-plan.md` | **This doc.** Current. |

---

## Phase 3: Clean Up Architecture Docs That Stay

These docs describe concepts that carry forward but need updating to reflect the new model. We'll mark them as `needs-update` and add a note pointing to the pivot. Don't rewrite yet — just annotate so agents know they're partially stale.

| Document | What changes |
|----------|--------------|
| `docs/architecture/overview.md` | Crate structure, three-layer model references |
| `docs/architecture/transport.md` | Still valid but needs ALPN endpoint section |
| `docs/architecture/auth.md` | Auth per-handler table from pivot replaces credential presentation per interface |
| `docs/architecture/client.md` | Client connects to endpoint, opens stream on ALPN — simpler |
| `docs/architecture/server.md` | Server becomes ALPN router — fundamentally different |
| `docs/architecture/identity.md` | Mostly valid, needs `IdentityProvider` simplification |
| `docs/architecture/configuration.md` | ListenerConfig → ALPN advertisement config |
| `docs/architecture/secret-service.md` | Unchanged — `alknet-secret` is standalone |
| `docs/architecture/definitions.md` | Terminology needs update (interface, listener, handler → ALPN, handler) |

---

## Phase 4: Clean Up Code

Not a rewrite — just remove dead weight so agents don't pattern-match to it.

### Delete from `alknet-core`

These modules/files implement concepts that the pivot replaces entirely. They'll be re-implemented in new crates:

| What | Lines | Reason |
|------|-------|--------|
| `src/interface/mod.rs` | 140 | `StreamInterface` / `MessageInterface` — replaced by `ProtocolHandler` |
| `src/interface/pairs.rs` | 122 | Transport/interface validation — no longer needed |
| `src/interface/config.rs` | 270 | `ListenerConfig` variants — replaced by ALPN advertisement |
| `src/interface/session.rs` | 62 | `InterfaceSession` / `InterfaceEvent` — old model |
| `src/interface/http.rs` | 66 | Old HTTP interface — becomes `alknet-http` handler |
| `src/interface/dns.rs` | 47 | Old DNS interface — becomes `alknet-dns` handler |
| `src/interface/raw_framing.rs` | 399 | Stealth mode byte-peek — replaced by ALPN negotiation |
| `src/server/stealth.rs` | 316 | Stealth mode — replaced by ALPN negotiation |
| `src/server/control_channel.rs` | 196 | SSH control channel for pubsub — old model |

**Keep as-is (port later):**

| What | Lines | Destination |
|------|-------|-------------|
| `src/interface/ssh.rs` | 982 | → `alknet-ssh` (largest single extraction) |
| `src/server/handler.rs` | 974 | → `alknet-ssh` (SSH server handler) |
| `src/server/channel_proxy.rs` | 555 | → `alknet-ssh` (port forwarding proxy) |
| `src/server/serve.rs` | 1526 | → rewrite as ALPN router (keep for reference, rewrite later) |
| `src/call/*` | ~1200 | → `alknet-call` (relatively clean extraction) |
| `src/auth/*` | ~1450 | → `alknet-core` (shared auth/identity) |
| `src/config/*` | ~950 | → `alknet-core` (static/dynamic config) |
| `src/transport/*` | ~1500 | → `alknet-core` (endpoint acceptors) |
| `src/client/*` | ~1900 | → `alknet-ssh` (client session, SOCKS5, forwarding) |
| `src/socks5/*` | ~800 | → `alknet-ssh` (SOCKS5 server) |
| `src/credentials/*` | ~250 | → simplify into `alknet-core` auth |
| `src/http/*` | ~340 | → `alknet-http` |
| `src/error.rs` | ~240 | → `alknet-core` |
| `src/testutil.rs` | ~140 | → `alknet-core` test utilities |

### Delete entire crate

| Crate | Reason |
|-------|--------|
| (none yet — `alknet-storage` and `alknet-flowgraph` don't exist as crates) |

The current workspace only has `alknet-core`, `alknet-secret`, `alknet-napi`, and `alknet` (CLI). No storage or flowgraph crates exist to delete.

---

## Phase 5: Architecture Specs (Follow SDD Process)

After cleanup, the architect role will produce proper architecture specs following the SDD process defined in `docs/sdd_process.md`. This means:

- **Modular docs** in `docs/architecture/` — one focused doc per component/area
- **ADRs** in `docs/architecture/decisions/` — new ADRs for pivot decisions (ALPN dispatch, ProtocolHandler trait, crate decomposition, etc.)
- **Open questions** centralized in `docs/architecture/open-questions.md`
- **README index** in `docs/architecture/README.md` with doc table, ADR table, lifecycle definitions
- **YAML frontmatter** with `status`, `last_updated` on every doc

The pivot proposal (`docs/research/pivot/alpn-service-architecture.md`) serves as Phase 0 research output. The architect will use it as input to produce Phase 1 architecture docs. No ad-hoc spec stubs — proper SDD specs from the start.

Key new ADRs the architect will need to produce:

| ADR | Title |
|-----|-------|
| 039 | ALPN-based protocol dispatch (replaces ADR-026, ADR-035) |
| 040 | ProtocolHandler trait (replaces StreamInterface/MessageInterface) |
| 041 | New crate decomposition (replaces ADR-027) |
| 042 | Auth as shared core (replaces ADR-028) |
| 043 | Event model per-handler (replaces ADR-032, ADR-018) |
| 044 | ALPN negotiation replaces stealth mode (replaces ADR-017) |

Key architecture docs the architect will need to produce or rewrite:

| Document | Scope |
|----------|-------|
| `overview.md` | Rewrite — crate structure, ALPN dispatch model, exports |
| `server.md` | Rewrite — ALPN router, handler registry, endpoint lifecycle |
| `client.md` | Rewrite — connect to endpoint, open stream on ALPN |
| `auth.md` | Update — IdentityProvider, per-handler credential table |
| `call-protocol.md` | Rewrite — alknet-call as one ALPN, EventEnvelope framing |
| `configuration.md` | Update — ALPN advertisement, handler config |
| `identity.md` | Update — IdentityProvider simplification |
| `definitions.md` | Update — new terminology |

---

## Execution Order

1. **Create `docs/_archived/` directory** and move files there (preserves git history)
2. **Mark superseded ADRs** with `Superseded` status and pivot reference
3. **Move obsolete research docs** to `docs/_archived/research/`
4. **Annotate stale-but-keeping architecture docs** with `status: needs-update` frontmatter and pivot reference note
5. **Delete replaced code modules** from `alknet-core` (interface layer, stealth, control channel)
6. **Fix compilation** — removing modules will break imports. Fix them minimally (comment out, stub, or remove call sites) so the project compiles. This is temporary scaffolding, not the refactor.
7. **Architect produces proper SDD architecture specs** per Phase 1 of the SDD process

After this cleanup, the repo should:
- Compile (possibly with reduced functionality)
- Have no references to `StreamInterface`, `MessageInterface`, `ListenerConfig`, or stealth mode in active docs
- Have superseded ADRs clearly marked so agents don't implement the old model
- Have all obsolete material in `docs/_archived/` where it won't bias agents
- Be ready for the architect role to produce proper Phase 1 architecture specs following the SDD process