alkdev/alknet
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d9227b812380413745c9a567dda179062a1066e1
alknet/docs/research/pivot/cleanup-plan.md
glm-5.1 b5a4600d74 greenfield: clean slate for ALPN-as-service pivot 
Delete old source crates (alknet-core, alknet, alknet-napi), old
architecture docs (ADRs, specs, open questions), old research docs
(phase2, event-sourcing, feasibility, etc.), old tasks, and obsolete
reference material (gitserver/MPL, honker, nats, rustfs, polyglot,
keystone, distributed-identity).

Keep: alknet-secret (standalone, compiles), pivot docs, iroh and ssh
references, rudolfs reference (MIT/Apache, fork candidate), ops docs,
sdd_process.md, and licenses.

Previous implementation preserved at /workspace/@alkdev/alknet-main/
for reference during porting.

Workspace compiles: cargo check + 14 tests pass for alknet-secret.
2026-06-15 12:08:08 +00:00

17 KiB
Raw Blame History

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/
Reference in New Issue View Git Blame Copy Permalink