docs: spec-level sync with the single-publish fix + port-debt repair

The spec docs had not caught up with the stub-sweep fix commits
(4eae18f..3317ea0), and the ported docs still carried alknet
numbering that now collides with alkcall's own ADR range.

Spec sync with the landed code:
- call-protocol.md: register_imported/register_imported_all return
  Result and refuse marked specs; marked-spec registration refusal
  contract spelled out (ADR-047 am. 4 §4.8, ADR-022 am. 2026-10-13)
- client-and-adapters.md: from_call flow gains the Pub sink-forwarding
  branch and the marked-op refusal (resolves OQ-37 — no from_call
  relay wrapper; sanctioned compositions are
  ChannelRelay::register_relay_openable / ChannelClient)
- ADR-051: "channel/control is not implemented" stale sentence
  replaced with the ADR-052 per-leg control contract
- OQ-37 resolved; OQ-22 split (primitive resolved; broker placement
  out of scope) with new OQ-42 for the downstream hub broker
  (deferred(scope), concretely blocked); OQ-24 resolved by the shipped
  add/strip surface; OQ-41 → deferred(scope) with blocking condition
- README: OQ bullets renumbered to tracker IDs; alknet-collision note
  rewritten (range 001..053, alknet prefix convention); new principle
  11 (implement-or-stop-advertising); AGENTS.md ADR range 001..053

Port-debt repair:
- 149 broken decision links across 17 docs — ported with alknet
  numbers/paths, most now remapped to alkcall files by slug; the
  rest link the alknet repo per the README convention
- stale OQ numbering rewritten to tracker IDs in call-protocol.md,
  call-README.md, operation-registry.md, client-and-adapters.md,
  ADR-025, channels-overview/README/wire, channel-client
- unambiguous "alknet ADR-NNN" labels where an alknet number collides
  with an alkcall ADR (052 TTY vs channel/control, 033 storage vs
  rust-canonical, 025/026/027+020 vault vs PeerEntry/auth ADRs)

Verified: cargo test (697 + guard), fmt, clippy --all-targets -D
warnings; full markdown link scan clean.
This commit is contained in:
glm-5.3-flash committed 2026-10-13 09:34:37 +00:00
1 parent 3317ea0963
commit 7b8a3e7558
26 files changed
+432 -332

No files matched your search

+34 -16
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-08-12
last_updated: 2026-10-13
---
# alkcall
@@ -112,16 +112,22 @@ are wire-stable and unchanged — see ADR-004.
See [open-questions.md](open-questions.md) for the full tracker. Key
questions affecting this crate:
- **OQ-01**: Call protocol pub/sub primitive (partially resolved) —
ADR-046 adds the `Pub` primitive (producer→consumer streaming). The
fan-out/broker is deferred to channels (Gap B in ADR-047 is named
out-of-scope for alkcall; the hub composes the broker on top).
- **OQ-02**: Full channel-level flow-control windowing (deferred(scope))
- **OQ-22** (resolved) / **OQ-42** (deferred(scope)): The call-protocol
pub/sub primitive is delivered (ADR-046); the fan-out/message broker
is placed out of scope for alkcall — the hub composes it on the
`Pub`/`Sub` primitives — and its design remains deferred downstream,
blocked on a concrete producing-crate consumer (Gap B in ADR-047).
- **OQ-23** (deferred(scope)): Full channel-level flow-control windowing
— bounded-buffer is decided (ADR-040); full windowing blocked on a real
HOL-blocking deployment observation.
- **OQ-03**: Channels add/strip API shape (open) — whether the 8-byte
header add/strip is built into the read/write path or a standalone
utility.
- **OQ-24** (resolved): Channels add/strip API shape — integral to the
read/write path (handlers never see headers); low-level header
primitives stay in `channels::wire` for tooling.
- **OQ-37** (resolved): No `from_call` relay wrapper for marked ops —
marked announcements and marked-spec imports are refused (ADR-022
amendment 2026-10-13, ADR-047 amendment 4 §4.8); the sanctioned
compositions are `ChannelRelay::register_relay_openable` (ADR-051) and
`ChannelClient`.
## Key Design Principles
@@ -145,6 +151,14 @@ questions affecting this crate:
channel 0. See ADR-036, ADR-037.
10. **Wire formats are stable**: EventEnvelope shape and the 8-byte chunk
header are one-way doors. See ADR-014, ADR-034.
11. **Implement-or-stop-advertising**: every registration on a
discoverable surface must be capable of succeeding — no
advertised-always-failing bodies, no deferral buckets ("not this
session" is the only permitted deferral statement). Marked
(`channel_open`) specs refuse the generic registration paths
(ADR-047 amendment 4 §4.8); the `not_implemented` guard test is
release-blocking (`tests/stub_guard.rs`). See reviews 010/011 for
the incident that pinned this.
## Roles and Composition
@@ -288,10 +302,14 @@ feature flags) or in the downstream alknet crate.
> preserved here as the authoritative spec for alkcall; the alknet
> mono-repo will consume alkcall's versions when it is reworked.
>
> **Cross-references to non-ported ADRs**: Some spec docs and ADRs
> reference alknet ADRs by their original numbers (e.g., ADR-052 for
> TTY's wire format, ADR-082 for alknet-tls, ADR-086 for endpoint types).
> These are ADRs for sibling crates that are not part of alkcall. They
> retain their alknet numbering (052, 082, 086, etc.) — any ADR number
> outside the alkcall range 001..048 is an alknet source ADR, found at
> `/workspace/@alkdev/alknet/docs/architecture/decisions/`.
> **Cross-references to non-ported ADRs**: alkcall's own ADRs are
> `decisions/001..053` in this directory. Some ported docs also cite
> sibling-crate ADRs that were **not** ported (e.g., alknet ADR-052 for
> TTY's wire format, alknet ADR-034 for outgoing-only X.509, alknet
> ADR-082 for alknet-tls, alknet ADR-086 for endpoint types). The alknet
> number space collides with alkcall's (alknet ADR-052 has nothing to do
> with alkcall's `channel/control` ADR-052), so unambiguous references
> carry the `alknet` prefix (e.g., "alknet ADR-052") and link to the
> alknet repo: `/workspace/@alkdev/alknet/docs/architecture/decisions/`
> (a few legacy cites without the prefix still mean the alknet ADR —
> check the link target).