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: Greenfield Workspace

**Decision: Greenfield rather than in-place migration.** The old codebase is preserved at `/workspace/@alkdev/alknet-main/` as a reference implementation. The new workspace starts clean with only `alknet-secret` carried over (it's standalone with no alknet-core dependency).

### What was deleted

| What | Reason |
|------|--------|
| `crates/alknet-core/` | Replaced by new `alknet-core` v2 with ALPN router |
| `crates/alknet/` | CLI will be rebuilt for new model |
| `crates/alknet-napi/` | NAPI will be rebuilt as call protocol client |
| `docs/architecture/` | Old model specs — will be replaced by SDD process |
| `docs/research/core.md` | Three-layer model — superseded |
| `docs/research/services.md` | irpc service layer — superseded |
| `docs/research/storage.md` | Metagraph — deferred |
| `docs/research/flow.md` | FlowGraph — deferred |
| `docs/research/configuration.md` | Promoted to architecture already |
| `docs/research/integration-plan.md` | Old model integration — superseded |
| `docs/research/phase2/` | StreamInterface/MessageInterface, CredentialProvider — superseded |
| `docs/research/event-sourcing/` | Not currently needed |
| `docs/research/references/gitserver/` | MPL-2.0 licensed — licensing risk |
| `docs/research/references/gitlfs/` | MIT/Apache — kept as fork candidate, moved to references |
| `docs/research/references/honker/` | Biased toward old irpc model |
| `docs/research/references/nats.rs/` | Not directly used |
| `docs/research/references/distributed-identity/` | Deferred |
| `docs/research/references/openstack-keystone/` | Not directly used |
| `docs/research/references/polyglot/` | Not directly used |
| `docs/research/references/rustfs/` | Not directly used (may return for alknet-fs) |
| `docs/references/` | Stray duplicate directory |
| `tasks/` | Old task graph — will be regenerated by SDD process |

### What was kept

| What | Reason |
|------|--------|
| `crates/alknet-secret/` | Standalone crate, no alknet-core dependency, fully working |
| `docs/research/pivot/` | The pivot proposal and this cleanup plan |
| `docs/research/references/iroh/` | ALPN dispatch, QUIC endpoints — directly relevant |
| `docs/research/references/ssh/` | russh, russh-sftp — directly relevant for alknet-ssh |
| `docs/research/ops/` | fail2ban, certbot — production reference |
| `docs/sdd_process.md` | The development process we follow |
| `Cargo.toml` (workspace) | Updated to only include alknet-secret |
| `Cargo.lock` | Preserved for alknet-secret dependencies |
| `LICENSE-MIT`, `LICENSE-APACHE` | License files |
| `README.md` | Updated for greenfield state |

### Reference implementation

The previous codebase is preserved at `/workspace/@alkdev/alknet-main/`. When spec'ing and implementing new crates, the architect and implementation specialists can reference the old code to understand what worked and what didn't. Key modules to port:

| Old module | Lines | Port destination |
|------------|-------|-----------------|
| `src/interface/ssh.rs` | 982 | → `alknet-ssh` |
| `src/server/handler.rs` | 974 | → `alknet-ssh` |
| `src/server/channel_proxy.rs` | 555 | → `alknet-ssh` |
| `src/server/serve.rs` | 1526 | → reference for ALPN router rewrite |
| `src/call/*` | ~1200 | → `alknet-call` |
| `src/auth/*` | ~1450 | → `alknet-core` |
| `src/config/*` | ~950 | → `alknet-core` |
| `src/transport/*` | ~1500 | → `alknet-core` |
| `src/client/*` | ~1900 | → `alknet-ssh` |
| `src/socks5/*` | ~800 | → `alknet-ssh` |

**The old code is reference, not constraint.** Agents should understand what it did and why, then implement against the new ProtocolHandler trait and ALPN router — not copy-paste the old architecture.

---

## 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~~ → **Greenfield instead.** Old code preserved at `/workspace/@alkdev/alknet-main/`.
2. ~~Mark superseded ADRs~~ → **Deleted.** Old architecture docs removed entirely. New ADRs will be created by the architect per SDD process.
3. ~~Move obsolete research docs~~ → **Deleted.** Only kept directly relevant references (iroh, ssh, ops, pivot).
4. ~~Annotate stale-but-keeping architecture docs~~ → **Deleted.** No stale docs remain. Architect will produce fresh specs.
5. **Delete old source crates** (alknet-core, alknet, alknet-napi) — done
6. **Update workspace Cargo.toml** to only include alknet-secret — done
7. **Update README.md** for greenfield state — done
8. **Verify compilation** — `cargo check` and `cargo test -p alknet-secret` both pass — done
9. **Architect produces proper SDD architecture specs** per Phase 1 of the SDD process

After this cleanup, the repo:
- Compiles cleanly (alknet-secret passes all 14 tests)
- Has no old architecture docs, ADRs, or task graph
- Has only directly relevant reference material (iroh, ssh, ops)
- Has the pivot proposal and cleanup plan as the starting point
- Has a clean workspace ready for the architect to produce Phase 1 specs
- Has the reference implementation at `/workspace/@alkdev/alknet-main/`