docs: align AGENTS.md with the alknet de-repo-pinning pass
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.
This commit is contained in:
1 parent
5f019c02f1
commit
f93ac3792d
1 file changed
+42
-24
@@ -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
|
||||
|
||||
Reference in new issue
Block a user