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/