0 Fork 0

Files

T

glm-5.2 bfb265e31b fix: Unit 6 — convention + doc cleanup (C-09, C-20-rem, C-22-rem, C-24, P-10, P-11)

Conventions satisfied, `cargo doc` clean, no actively-wrong comments,
producer/consumer naming consistent in the call/registry docs.

P-10 — `pump_sink` matched the string literals "call.published",
"call.completed", "call.aborted" (dispatch.rs) instead of the
EVENT_PUBLISHED / EVENT_COMPLETED / EVENT_ABORTED constants the rest
of the file imports. Replaced with the constants — pure refactor
hazard, no behavior change.

C-20 remainder — the wrong "SAFETY:" comment at from_call.rs:271
marked no `unsafe` block and was factually wrong (described a `'static`
return that isn't what `derive_alpn_from_op_name` does — it returns
`Option<String>`; the leak happens in `leak_alpn`). Reworded to a
plain note about the `'static` lifetime requirement. Also reworded
the abort-cancels claims in the `pump_sink` and `pump_stream` doc
comments (dispatch.rs): both claimed `call.aborted` "cancels the task
and drops the handler future" — the handler is actually `join!`-ed to
completion and not yet cancelled (the abort-cancels-Pub mechanism is
review 001 Unit 9). Trimmed step-numbered narration comments in
adapter.rs / client.rs that restated what the code does, keeping the
ordering-constraint and REQ-CH comments. The big reassembly.rs
deliberation landed with Unit 4; this finishes the remainder.

C-09 — fixed the 2 remaining `cargo doc` warnings (was 4; the
register_openable links were fixed in Unit 3):
- `unresolved link to default_policy` (operations.rs:50) — the
  [`default_policy`] intra-doc link resolves to
  super::policy::default_policy; used the full path.
- `env is both a module and a macro` (channels/mod.rs:30) — the
  [`env`] link collided with the std `env!` macro; qualified as
  [`self::env`].
`cargo doc --no-deps` now emits 0 warnings.

C-22 remainder — removed the filler `PhantomData` test at client.rs
(`let _ = std::marker::PhantomData::<ChannelClient>;` — asserts
nothing). The env.rs tautology was already removed in Unit 3.

C-24 — replaced "client→server streaming" with "producer→consumer
streaming" in call-protocol.md, operation-registry.md, README.md, and
open-questions.md (4 occurrences). Per AGENTS.md §8 the convention is
producer/consumer, not server/client. The remaining "client→server"
references in channels ADRs 034/037 are in stream_type table contexts
that Unit 10 (C-26) will handle as part of the spec-doc renumbering.

P-11 — amended ADR-046 §3's SinkHandler type so the stream item type
matches §6. §3 declared `Pin<Box<dyn Stream<Item = Value> + Send>>`;
§6 declared `Pin<Box<dyn Stream<Item = Result<Value, CallError>> +
Send>>`. The code uses §6's shape uniformly (registration.rs:32-40,
aliased as PublishStream). §3's text and the Door-type section are
amended to match §6; the Door-type section already marked the concrete
stream item type a two-way-door detail, so this is a text correction,
not a design change. Added an amendment note dated 2026-08-13.

Verification:
- cargo test --lib         → 449 passed, 0 failed (was 450; -1 removed filler test)
- cargo clippy --all-targets -- -D warnings → clean
- cargo fmt --check        → clean
- cargo doc --no-deps      → 0 warnings (was 2)

2026-08-13 08:47:20 +00:00

7.3 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-08-12

Open Questions

Open questions are tracked here, organized by theme. Each question has a status, priority, and (when resolved) a resolution citing the ADR.

Status values: open, resolved, deferred(scope), deferred(unclear), partially resolved, dissolved.

Call Protocol

OQ	Title	Status	Priority	Resolution
OQ-01	Call protocol scope within a connection	resolved	medium	ADR-015 — stream model, multiplexing
OQ-02	Operation path format and routing scope	resolved	medium	`/{service}/{op}` is the correct design
OQ-03	Batch operation semantics	resolved	low	Correlated call.requested events
OQ-04	Session-scoped operation registries	resolved	medium	ADR-019 — OperationEnv trait layering
OQ-05	Abort cascade semantics for nested calls	resolved	high	ADR-020
OQ-06	Privilege model and authority context	resolved	high	ADR-017
OQ-07	Handler identity registration path and composition authority	resolved	high	ADR-018
OQ-08	Operation error schemas	resolved	high	ADR-016
OQ-09	Safe vault operations for call protocol exposure	resolved	high	ADR-010 — none exposed
OQ-10	~~Remote-safe marking shape~~	dissolved	medium	ADR-024 — remote_safe/trusted_peer retired
OQ-11	OperationAdapter error type (AdapterError variants)	resolved	medium	DiscoveryFailed, SchemaParse, Transport, Unauthorized, SamePeerCollision
OQ-12	from_call re-import trigger	resolved	low	ADR-028 — manual free function
OQ-13	from_call namespace collision	resolved	low	Same-peer = error; cross-peer dissolved (ADR-024)
OQ-14	CallClient TLS client-auth	resolved	high	quinn client-auth; key-type-aware verification
OQ-15	PeerRef::Any routing policy	resolved	low	Insertion-order first-match
OQ-16	services/list-peers re-export semantics	resolved	low	Opt-in; services/list is own-ops-only
OQ-17	Multi-hop federation	deferred(scope)	low	One-hop model is the commitment; multi-hop is a feature extension
OQ-18	PeerId — crypto identity vs stable logical id	resolved	high	ADR-025 — PeerId = Identity.id (stable)
OQ-19	Persistent peer registry	resolved	medium	ADR-025 — core trait + in-memory default; persistence adapters separate
OQ-20	~~API key asymmetry~~	dissolved	medium	PeerEntry supports multiple credential paths
OQ-21	X.509 outgoing-only case	resolved	medium	Three remote roles; PeerEntry asymmetry correct

Call Protocol — Pub/Sub

OQ	Title	Status	Priority	Resolution
OQ-22	Call protocol pub/sub primitive — pub to go with sub	partially resolved	high	ADR-046 resolves the primitive: `OperationType::Pub` + `HandlerKind::Sink` + `call.published` wire event + `invoke_sink()` dispatch path. The fan-out/broker mechanism (one producer, N consumers, topic matching) is deferred to the channels session — the call protocol is point-to-point; the broker is a routing concern that sits above it. ADR-047 §1 names the broker (Gap B) as out-of-scope for alkcall; the hub composes it on top of the `Pub`/`Sub` primitives. See §"Pub/Sub Gap" below.

Pub/Sub Gap

The call protocol's StreamingHandler / invoke_streaming() path (ADR-021) is point-to-point: a call.requested arrives, the handler produces a stream of call.responded events back to that one caller. There was no mechanism for a producer to stream data to a responder (producer→consumer streaming), and no fan-out (one producer, N consumers).

ADR-046 resolves the directional gap: OperationType::Pub is the producer→consumer streaming complement to Sub (was Subscription, renamed for symmetry). HandlerKind::Sink is the consuming handler type. call.published is the wire event carrying stream chunks. invoke_sink() is the dispatch path. CallConnection::publish() is the client method. The Subscription variant is renamed to Sub (wire string "sub").

Fan-out deferred. The broker (topic registry, Pub↔Sub matching, N-consumer fan-out) is deferred to the channels session. The call protocol is point-to-point (one initiator, one responder, a stream between them); a topic registry that outlives individual calls is a different lifecycle and a different concern. The broker's first consumer is the channels channel/resources/subscribe operation (ADR-037) and the hub-as-broker pattern (ADR-042). The Pub primitive is the load-bearing piece the broker composes on.

Channels

OQ	Title	Status	Priority	Resolution
OQ-23	Full channel-level flow-control windowing	deferred(scope)	low	Bounded-buffer decided (ADR-040); full windowing blocked on HOL-blocking deployment observation
OQ-24	Channels add/strip API shape	open	low	Whether the 8-byte header add/strip is built into the read/write path or a standalone utility. The contract (ADR-035) is decided; the function surface is not
OQ-31	`channel/open` ACL granularity	resolved	high	ADR-047 — `channel/open` dissolves into per-ALPN ops; each op has its own `access_control`
OQ-32	Quota lifecycle (opener vs closer, transport drop)	resolved	high	ADR-047 §7 — the per-connection opener ledger; decrement on every teardown path, keyed by opener
OQ-33	Per-identity connection cap (endpoint layer)	deferred(scope)	low	Named as a separate layer (ADR-047 §"ALPN category reframe" references the findings); belongs at `alknet-endpoint`, not channels. Named to stop the re-tangle
OQ-34	`channel_open` marker wire format	resolved	medium	ADR-047 §2 — boolean `"channel_open": true` in `services/schema`; ALPN derivable from op name
OQ-35	`OperationEnv::channel_manager()` coupling	resolved	high	ADR-047 §4 — extension trait `ChannelOperationEnv` in `channels-call`; call crate stays free of channels types
OQ-36	`channel_id` allocation in Pub case	resolved	medium	ADR-047 §5 — "connection owner allocates" (the side that holds the `ChannelManager`); amends "responder allocates"
OQ-37	`from_call` relay wrapper for marked ops	open	medium	ADR-047 §1 names it as a consumer (hub) concern; alkcall's `from_call` reconstructs the marker (Gap F resolved) so the consumer can branch on it
OQ-38	ALPN→path-segment mapping	resolved	low	ADR-047 §"Negative" — strip the `alknet/` prefix; ALPNs without that prefix use the full ALPN string (rare, two-way-door)

Core Types

OQ	Title	Status	Priority	Resolution
OQ-25	BiStream type definition	resolved	high	ADR-005 — trait, Connection parameter
OQ-26	AuthContext resolution timing	resolved	high	ADR-003 — hybrid resolution
OQ-27	ALPN string naming convention	resolved	medium	ADR-004 — alknet/ prefix
OQ-28	Dynamic handler registration	resolved	low	ADR-019 — curated static, overlays dynamic
OQ-29	Handler-level auth resolution observability	resolved	medium	set_identity() on Connection for observability
OQ-30	Dynamic resource ownership	resolved	high	ADR-011 — OwnershipProvider, resource_id_path

7.3 KiB Raw Blame History