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:
1 parent
3317ea0963
commit
7b8a3e7558
26 files changed
+432
-332
No files matched your search
+34
-16
@@ -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).
|
||||
Reference in new issue
Block a user