feat(review 006 Unit 2): additive OperationSpec.description disclosed via discovery (E-02)

- OperationSpec gains description: Option<String> (builder
  with_description, defaults None; no struct-literal construction
  sites exist, so additive by construction)
- spec_to_json_pub emits description when set; rebuild_spec_for
  parses it back — the field survives from_call discovery and
  op/register announcement (same round-trip pattern as
  resource_id_path / publish_schema)
- services/list and the local-ops half of services/list-peers emit
  description when set; output-schema docs on both listing specs and
  operation_spec_schema advertise the field
- Tests: builder/default, emit/omit, listing emission, schema
  disclosure, schema-doc presence, round-trip + absent-stays-absent
  (8 new; 616 total)
- Docs: review 006 Unit 2 marked IMPLEMENTED; ADR-047 §6 amendment
  records the E-02 discovery decision (listing enrichment lands, the
  channel/resources/subscribe half stays deferred); OQ-40 gains the
  load-bearing note; operation-registry.md struct + listing docs;
  CHANGELOG

Verification: cargo test (616 pass), clippy -D warnings (host +
wasm32), fmt --check, cargo doc --no-deps, wasm32 check — all clean

docs/architecture/decisions/047-openable-alpns-are-operations.md

@@ -8,7 +8,40 @@ Accepted (amends ADR-037; refines ADR-044, ADR-046; §4 amended
 registration, 2026-08-13)"; amendment #2 (2026-09-03) — the
 per-connection registration mechanism is the **per-session fork of the
 base registry installed as the session's dispatch registry**, not the
-connection overlay — see "Amendment (§4 mechanism, 2026-09-03)" below)
+connection overlay — see "Amendment (§4 mechanism, 2026-09-03)" below;
+§6 amended 2026-09-06 — the static half of discovery gains an additive
+per-op `description` on the listing, the dynamic half stays deferred
+— see "Amendment (§6 listing enrichment, 2026-09-06)" below)
+
+## Amendment (§6 listing enrichment, 2026-09-06)
+
+Review 006 E-02 (from the alktunnels Phase 0 sweep) made §6's dynamic
+half load-bearing for the first time and asked for a decision on the
+static half. Decision: **both halves of the "static per-op" split gain
+what is cheap today; the dynamic half stays deferred** (OQ-40, now
+with a "load-bearing for alktunnels discovery UI" note in
+`open-questions.md`; alktunnels v1 uses config-known op names):
+
+- `OperationSpec` gains `description: Option<String>` — a human-
+  readable op description, set via `with_description` at registration.
+  Additive (defaults `None`; no struct-literal construction sites
+  exist — all sites use `OperationSpec::new`).
+- `services/list` (and the local-ops half of `services/list-peers`)
+  emit `description` when set — one round-trip answers "which ops
+  exist and what are they for" without the N+1 `services/schema`
+  sweep. The output-schema docs on both listing specs and on
+  `services/schema`'s `operation_spec_schema` advertise the field.
+- `spec_to_json_pub` emits it when set; `rebuild_spec_for` parses it
+  back — the description survives discovery and peer announcement
+  (`from_call`, `op/register`) like every other additive spec field
+  (`resource_id_path`, `publish_schema` round-trip the same way).
+
+Scope note from E-02 stands: the listing field describes **the op**,
+not **the produced resource set** (a tunnel producer registers one op
+and N resources). "Which tunnel resources may I open, live" remains
+`channel/resources/subscribe`'s job (§6's dynamic half, ADR-037 §
+`channel/resources/subscribe`) — deferred until a consumer needs live
+resource discovery.
 
 ## Amendment (§4 mechanism, 2026-09-03)
 

docs/architecture/open-questions.md

@@ -83,7 +83,7 @@ is the load-bearing piece the broker composes on.
 | 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 `alk/` prefix; ALPNs without that prefix use the full ALPN string (rare, two-way-door) |
 | OQ-39 | `channel/control` control-handle surface | open | medium | The `channel/control` handler currently returns `channel:control_not_implemented`. The control-handle surface (per-channel control callbacks registered by ALPN crates, routing `message` to the handler's control handle for `channel_id`) is real design work — each ALPN crate needs a way to register a control callback, and the channels layer needs a control-handle registry keyed by `channel_id`. Deferred until an ALPN crate (TTY, tunnel) needs out-of-band control. |
-| OQ-40 | `channel/resources/subscribe` live subscription | open | medium | The `channel/resources/subscribe` handler currently returns `channel:resources_not_implemented`. The live subscription aggregated from ALPN-crate resource enumerators (ADR-047 §6) requires each ALPN crate to provide a resource enumerator, and the channels layer to aggregate them into a live `Stream` that emits on any change. The current stub is a one-shot error; the real implementation is deferred until a consumer (hub, dashboard) needs live resource discovery. |
+| OQ-40 | `channel/resources/subscribe` live subscription | open | medium | The `channel/resources/subscribe` handler currently returns `channel:resources_not_implemented`. The live subscription aggregated from ALPN-crate resource enumerators (ADR-047 §6) requires each ALPN crate to provide a resource enumerator, and the channels layer to aggregate them into a live `Stream` that emits on any change. The current stub is a one-shot error; the real implementation is deferred until a consumer (hub, dashboard) needs live resource discovery. **Load-bearing for alktunnels' discovery UI** (review 006 E-02): a consumer cannot distinguish produced tunnel resources by op name alone. The static half is covered (0.5.0: `OperationSpec.description` on `services/list` — describes the op, not the live resource set); the dynamic half stays deferred — alktunnels v1 uses config-known op names. |
 | OQ-41 | QUIC-native multi-stream substrate | open | medium | Only the in-line substrate mode is implemented (single bidi stream, header-demuxed N channels). The QUIC-native multi-stream substrate (accept remaining bidi streams, read headers off each — ADR-034 §substrate modes) is deferred to the downstream alknet crate. The wire format and demux loop are correct for both substrates; only the outer `accept_bi()` loop is missing. The alknet crate owns the QUIC dial/accept loop and is the natural place for the multi-stream accept loop. This crate stays transport-agnostic (no QUIC dependency, WASM-compatible). |
 
 ## Core Types

docs/architecture/operation-registry.md

@@ -39,6 +39,9 @@ pub struct OperationSpec {
     pub output_schema: Value,     // JSON Schema for output
     pub error_schemas: Vec<ErrorDefinition>,  // Declared domain errors (ADR-016)
     pub access_control: AccessControl,
+    /// Human-readable op description (review 006 E-02). Disclosed by
+    /// `services/list` when set; `None` when the op declares none.
+    pub description: Option<String>,
     /// JSON pointer into the input for the resource ID, when
     /// `access_control.resource_type` is set and the operation targets a
     /// specific runtime-spawned resource (ADR-011). e.g., `"$.containerId"`
@@ -829,6 +832,12 @@ These are read-only — no admin operations are exposed through the call protoco
 }
 ```
 
+Each listing entry also carries `description` (review 006 E-02) when
+the op's spec declares one (`OperationSpec.description`, set via
+`with_description`) — the field is additive and absent otherwise. It
+describes the op, not the produced resource set: live resource
+discovery stays with `channel/resources/subscribe` (ADR-047 §6, OQ-40).
+
 `services/schema` accepts `{ "name": "fs/readFile" }` (no leading slash —
 registry form, same as `OperationSpec.name`) and returns the full
 `OperationSpec` including input/output JSON Schemas and declared

docs/reviews/006-channel-open-establishment-gap-review.md

@@ -27,7 +27,13 @@ gates landed as tests; two implementation-shape notes recorded in
 ADR-049's amendment: the establisher does not receive the channel
 `Connection` (yield-once BiStream belongs to the pump handler), and
 the bound is the earlier of dispatch deadline and per-registration
-timeout). The original remediation sketch below is superseded by the
+timeout). **Unit 2 (E-02) is implemented** in alkcall 0.5.0
+(`OperationSpec.description: Option<String>` +
+`with_description`, `spec_to_json_pub` emits it when set,
+`rebuild_spec_for` parses it (shared by `from_call` and `op/register`),
+`services/list` and `services/list-peers` local listings emit it when
+set; the ADR-047 §6 amendment below records the discovery decision).
+The original remediation sketch below is superseded by the
 "Remediation plan (post-verification)" section; the original sketch
 is retained for the record.
 
@@ -360,6 +366,10 @@ transports, two contracts). alkhttp unaffected (no openable ops).
 small ADR amendment: recommend (3) — subscribe for live resource sets
 (the decided shape, now load-bearing), plus an additive
 `description` field on the listing (cheap, immediately useful).
+**Implemented 2026-09-06 (alkcall 0.5.0):** the listing half landed
+(`OperationSpec.description`, four touchpoints as the appendix
+corrected); the subscribe half stays deferred (OQ-40, now with the
+load-bearing note).
 
 **Unit 3 — E-03/E-04.** E-03: log-or-comment; E-04: doc note. Trivial.
 
@@ -407,7 +417,9 @@ correction): struct field + `spec_to_json_pub` emit +
 `services/list` emits it when set. OQ-40 stays deferred but gains a
 "load-bearing for alktunnels discovery UI" note; the
 `channel/resources/subscribe` half stays deferred (alktunnels v1 uses
-config-known op names).
+config-known op names). **Status: IMPLEMENTED (2026-09-06)** — the
+discovery decision (3: enriched listing now, subscribe deferred) is
+recorded as an amendment to ADR-047 §6.
 
 **Unit 3 — E-03/E-04/N-2 (trivial batch, same PR series as Unit 1).**
 E-03: debug log (or pinning comment) on the discarded `UnknownChannel`