From f93ac3792d6967686d43f38fd8beaa7d80d10fdc Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Tue, 13 Oct 2026 11:15:24 +0000 Subject: [PATCH] docs: align AGENTS.md with the alknet de-repo-pinning pass MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md is auto-loaded by every agent, so its framing had to match the re-keyed spec (5f019c0). Three alknet-era passages conflicted with it: - Intro: "unification of alknet-call / alknet-channels" → "extraction and unification of the former ... crates" (same provenance framing as the spec docs). - Convention 9: dropped "when the alknet mono-repo is reworked, it will consume alkcall's versions" — replaced with the current truth: the source-repo core crate is retired, the mono-repo is being replaced by thin glue (composition layer — OQ-43). - Architecture Context: ADR range 001..054, OQ range OQ-01..43 with OQ-43 named; the porting bullet now states mono-repo = provenance not a live dependency, names the sibling host crates (alkhttp/alktls/ alktty/alktunnels/alktrader) as the current homes of the alknet-era surfaces, and documents the citation convention ("alknet ADR-NNN (provenance)" / "alknet OQ-NN" — never in-crate authority). Also lists ADR-054 (re-owned X.509 verifier-selection rule) in the key ADR list so agents don't chase the demoted alknet ADR-034 as authority. Verification: residual alknet-mention sweep of AGENTS.md (only marked provenance/historical framing remains); section cross-check against docs/architecture/README.md's provenance note and OQ-43 wording. Docs-only change — no code paths touched. --- AGENTS.md | 66 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 918755c..bce26bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,14 +46,15 @@ change `git config`, skip hooks, or use `git commit -i`. ## Project Conventions (Rust / RPC protocol crate) -This is the call + channels RPC crate — the unification of -`alknet-call` (structured JSON RPC: operations, streaming subscriptions, -service discovery) and `alknet-channels` (multiplexing proxy: N logical -channels over one transport stream, channel 0 pre-negotiated as - `alk/call`). The conventions below apply to all work in `src/` and -`tests/`. They mirror `.opencode/agents/implementation-specialist.md` -§Project Conventions and are repeated here so they apply to every -session, not just spawned implementation agents. +This is the call + channels RPC crate — the extraction and unification of +the former `alknet-call` (structured JSON RPC: operations, streaming +subscriptions, service discovery) and `alknet-channels` (multiplexing +proxy: N logical channels over one transport stream, channel 0 +pre-negotiated as `alk/call`) crates. The conventions below apply to all +work in `src/` and `tests/`. They mirror +`.opencode/agents/implementation-specialist.md` §Project Conventions and +are repeated here so they apply to every session, not just spawned +implementation agents. 1. **No comments in code** unless the user explicitly asks. This is a project-wide convention. Doc comments (`///`, `//!`) are fine and @@ -130,11 +131,13 @@ session, not just spawned implementation agents. `AuthContext`, `IdentityProvider`, `Identity`, `AuthToken`, `Capabilities`, `OwnershipProvider`, `HandlerError`, `StreamError`) live in this crate. They are the home for these types going forward — - do not add a separate `alkcore` dependency. When the alknet mono-repo - is reworked, it will consume alkcall's versions. Keep these types - lean (no TLS, no transport coupling, no endpoint/accept-loop); the - dial and the TLS config are concerns of the consumer, not of this - crate. See ADR-007, ADR-008, ADR-009. + do not add a separate `alkcore` dependency; the source-repo core crate + is retired (the alknet mono-repo is being replaced by thin glue over + alkcall and its sibling host crates — see OQ-43 in + `docs/architecture/open-questions.md` for the composition layer). + Keep these types lean (no TLS, no transport coupling, no + endpoint/accept-loop); the dial and the TLS config are concerns of + the consumer, not of this crate. See ADR-007, ADR-008, ADR-009. 10. **BAST documents for wire formats** — every binary wire format in this crate carries a BAST (Binary Abstract Syntax Tree) document as @@ -238,17 +241,28 @@ directions: ## Architecture Context - `docs/architecture/` — the authoritative spec. Read it before - non-trivial changes. ADRs are numbered 001..053; OQs (open questions) - track resolved/deferred decisions. -- This crate unifies `alknet-call` and `alknet-channels` from the - alknet mono-repo (`/workspace/@alkdev/alknet`). The source - architecture docs were ported from - `/workspace/@alkdev/alknet/docs/architecture/` and renumbered as - alkcall ADRs (001..048; ADR-049 and later were authored in this - crate). The ALPN - strings (`alk/call`, - `alk/channels`) are wire-stable going forward (renamed from - `alknet/` to `alk/` in v0.1.1, before the first published consumer). + non-trivial changes. ADRs are numbered 001..054; OQs (open questions) + track resolved/deferred decisions (OQ-01..43; OQ-43 tracks the + composition layer's ownership and shape after the alknet replacement, + deferred(scope)). +- This crate is the extraction of the former `alknet-call` and + `alknet-channels` crates plus the vendored core types (provenance: + the alknet mono-repo at `/workspace/@alkdev/alknet`). The source + architecture docs were ported and renumbered as alkcall ADRs + (001..048; ADR-049 and later were authored in this crate). The + mono-repo is **provenance, not a live dependency** — it is being + replaced by thin glue over alkcall and its sibling host crates + (`alkhttp`, `alktls`, `alktty`, `alktunnels`, `alktrader`), which are + the current homes of the surfaces old docs call `alknet-http`, + `alknet-tls`, `alknet-tty`, `alknet-tunnels`, `alknet-trader`. Docs + and ADRs cite the source repo as "alknet ADR-NNN (provenance)" / + "alknet OQ-NN" — a separately-numbered upstream space, never an + in-crate authority; anything that constrains this crate's surface is + re-owned by an in-crate ADR (e.g. ADR-054). See the provenance note + at the end of `docs/architecture/README.md`. The ALPN strings + (`alk/call`, `alk/channels`) are wire-stable going forward (renamed + from `alknet/` to `alk/` in v0.1.1, before the first published + consumer). - Key ADRs that inform this crate's design: **Call protocol:** @@ -320,6 +334,10 @@ directions: point `ChannelBidiStreamSource` implements) - ADR-009 — `BiStream` as the handler leaf (`accept_bi` returns `BiStream`) + - ADR-054 — outgoing-only X.509 and the three remote roles + (verifier selection by `PeerEntry` presence; `RemoteIdentity` + `None` semantics — re-owned in-crate from the source repo's + alknet ADR-034; the dial/composition layer implements it) - If a TODO references a "Phase B" or a design direction that an ADR has since decided against, the TODO is stale — remove it and align