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.
This commit is contained in:
2026-06-15 12:08:08 +00:00
parent d003a4f4ec
commit b5a4600d74
261 changed files with 138 additions and 53794 deletions

View File

@@ -154,52 +154,70 @@ These docs describe concepts that carry forward but need updating to reflect the
---
## Phase 4: Clean Up Code
## Phase 4: Greenfield Workspace
Not a rewrite — just remove dead weight so agents don't pattern-match to it.
**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).
### Delete from `alknet-core`
### What was deleted
These modules/files implement concepts that the pivot replaces entirely. They'll be re-implemented in new crates:
| 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 | 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 |
### What was kept
**Keep as-is (port later):**
| 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 |
| 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 |
### Reference implementation
### Delete entire crate
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:
| Crate | Reason |
|-------|--------|
| (none yet — `alknet-storage` and `alknet-flowgraph` don't exist as crates) |
| 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 current workspace only has `alknet-core`, `alknet-secret`, `alknet-napi`, and `alknet` (CLI). No storage or flowgraph crates exist to delete.
**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.
---
@@ -243,17 +261,20 @@ Key architecture docs the architect will need to produce or rewrite:
## 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
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 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
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/`