docs(review 011): downstream input on review 010's S-01 — the marked-pub open contract and the single-publish amendment requirements

From alkblobs (paused on S-01; its ADR-014 is the reviewed downstream
ruling):

- S-01's option-1 sketch (hand the OpenHandler the PublishStream) is
  the wrong shape for marked ops — it imports ADR-046's unmarked
  call.published semantics into the ADR-047 §2 marker case. The
  settled shape: initiator allocates (odd) and writes immediately;
  responder adopts (channel id crosses the open invocation, reserved
  input key + dispatch-layer strip recommended); wrapper as responder
  of record (await the handler's JoinHandle, merge establishment
  reply fields + handler result into the single response); zero
  call.published on marked ops (nonempty publish chunks rejected
  loudly); relay PubTypedOpen lifted.
- Seven items the amendment-4 publish must pin (incl.
  publish_schema refused at registration for marked ops; the put
  acks-in-result sentence; the client-side stream-then-open
  capability absent from ChannelClient today).
- Verification gates list; S-02/S-03/S-04 downstream
  non-requirements and remedy preferences; per-crate impact for the
  four published consumers (none register Pub-typed openables —
  S-01 is capability-additive; semver risk concentrates in any
  stop-advertising removals).

Docs-only change.

docs/reviews/011-pub-open-remediation-input-from-alkblobs.md

@@ -0,0 +1,230 @@
+# Review 011 — The marked-pub open contract: downstream input on review 010's S-01, and what the single-publish fix must pin
+
+## Status
+
+Open — filed 2026-10-13. From alkblobs (the downstream crate paused on
+review 010 S-01; its ops-put task gates on this surface). Purpose:
+correct review 010's S-01 remediation sketch before the amendment is
+drafted, enumerate what the amendment must pin so one publish
+(0.9.0) fixes all four stubs right, and record the downstream
+requirements and non-requirements from the consumer seat.
+
+Input basis: alkblobs ADR-014
+(`/workspace/@alkdev/alkblobs/docs/architecture/decisions/
+014-marked-pub-put-contract-and-alkcall-gate.md`, committed 7ac0099)
+— the reviewed downstream ruling this review summarizes the
+requirements of.
+
+---
+
+## 1. S-01: the remediation is "implement", but the review's option-1 sketch is the wrong shape — amend the review text
+
+Review 010's S-01 poses two remedies. Option 2 (reject at
+registration) is honest but strands the downstream: alkblobs' put is
+the real consumer of the marked-pub shape, and its settlement was
+"implement, in the adoption shape". The one publish should take
+option 1. But **option 1's sketch is wrong for marked ops** and
+would, if implemented as sketched, ship a second incoherence this
+ADR cycle exists to end:
+
+> "hand the `OpenHandler` the `PublishStream` already produced by the
+> serving loop along with the channel's `Connection`"
+
+That reads ADR-046's **unmarked** Pub semantics (`call.published`
+JSON chunks through `publish_schema` validation) into the **marked**
+case. ADR-047 §2's marker sentence says the opposite: *"the
+`channel_open` marker that tells the channels layer 'this op's
+stream is binary, not JSON' — allocate a channel for it."* A marked
+Pub op whose bulk bytes rode `call.published` would be the worst of
+both stacks: bulk binary re-validated per-chunk as JSON against
+`publish_schema`, MB-scale payloads through the JSON event grammar,
+and no bounded-buffer backpressure (ADR-040's bounded buffer is
+precisely the mechanism that exists for this). Section 010's
+"tension" paragraph (stub comment vs ADR-047 §1's `call.published`
+prose) resolves the same way: §1/AAD-046's `call.published` prose
+describes *unmarked* Pub ops; the *marked* case's stream is the
+allocated channel's BiStream.
+
+The settled shape (agreed with the downstream's architecture
+session; recorded as alkblobs ADR-014 §1/§2/§3):
+
+1. **The initiator allocates and writes immediately.**
+   Connection-owner allocates the `channel_id` (ADR-047 §5; connect
+   side → odd per the implemented odd/even split,
+   `src/channels/manager.rs` `next_channel_id`), opens the write
+   half on it, and streams bytes before the open op resolves. The
+   existing early-arrival parking (`drain_early_arrivals`,
+   `src/channels/manager.rs`) is the established mechanism covering
+   the responder-adopts race — implemented, tested, no new
+   machinery.
+2. **The responder adopts.** The channel ID crosses the open
+   invocation as a wrapper-reserved field. The reserved-field
+   placement question — reserved input key vs envelope field — is
+   decided by schema-validation ordering: validation runs in
+   `invoke_*` before any handler, so a reserved *input* key must be
+   stripped in the dispatch sink branch (the layer that reads the
+   `channel_open` marker) before `input_schema` validation; an
+   envelope field would extend the call event grammar for one op
+   family. Recommendation: **reserved input key + dispatch-layer
+   strip**, symmetric with amendment 3's reply-side
+   `RESERVED_REPLY_KEY` reservation — the input side of the same
+   pattern. Either way, the exact key name and the reject-not-strip
+   posture for a *marked* op are wire-visible from the first
+   consumer (alkblobs' put; not yet shipped — it pends behind this
+   amendment, so this is the cheapest moment to pin).
+3. **The wrapper is the responder of record.** Flow:
+   `policy.check_open` → adopt → bounded establisher (offer
+   validation, establishment reply fields — ADR-049 amendment 3's
+   mechanism, unchanged) → spawn the `OpenHandler` on the channel's
+   `Connection` → **await the handler's `JoinHandle`** → respond
+   once: the `{channel_id}` output extended with the establisher's
+   reply fields and the handler-completion result merged (R-02's
+   lifetime contract is load-bearing here — the handle must track
+   the data plane). A failed establishment tears the channel down
+   and replies `channel:open_failed` (the only response); initiator
+   bytes racing the torn-down channel hit EOF and are discarded.
+4. **Zero `call.published` data on the call plane for marked pub
+   ops** — a nonempty publish-chunk stream on a marked op is
+   rejected loudly, never consumed. Two competing data paths is the
+   incoherence that must never exist.
+5. **Relay lifting:** `PubTypedOpen` rejection
+   (`src/channels/relay.rs`) is replaced with real relay
+   translation for pub openables (the hub's put-forwarding shape).
+
+The corollary this implies downstream (also pinned in alkblobs
+ADR-014 §2): **the put's establishment ack is informative-in-result,
+not a gating ack.** A sink op gets exactly one `call.responded`
+(ADR-046 §5), produced after the handler completes — so a putter
+cannot wait for the ack before streaming (a wait deadlocks: the
+response cannot exist until the stream completes). The fetch/put
+asymmetry is direction-inherent: fetch (`Sub`) acks at
+establishment before any byte; put (`Pub`) acks in the result. The
+amendment should state this sentence, not leave it for each
+consumer to derive — it is exactly the kind of half-stated
+implication that review 010 flagged as drift fuel.
+
+## 2. What amendment 4 must pin (the publish checklist)
+
+All of these are wire-visible or API-visible from the first
+consumer; none is safely deferrable to a later amendment while
+put-shaped consumers exist:
+
+1. **Marker semantics** — the marked Pub op's stream is the adopted
+   channel's `BiStream` (ADR-050 pump patterns, one direction);
+   zero `call.published` (§1.4 above; rejection is the wire
+   behavior).
+2. **`publish_schema` on a marked op is refused at registration** —
+   publish chunks never exist, so the field is dead machinery on a
+   marked spec; the same class review 010 outlaws (registered but
+   incapable of mattering). Registration-time loudness, per the
+   house pattern.
+3. **The reserved-field wire form** for the adopted channel id
+   (input-key + dispatch-strip recommended, §1.2) — key name and
+   strip-before-validation ordering pinned in the ADR; one-way from
+   the first consumer.
+4. **The wrapper-as-responder-of-record flow** (§1.3) — response
+   merge order (`channel_id` reserved → establisher reply fields →
+   handler result), single-response semantics, teardown-on-fail.
+5. **The ack-timing sentence** (§1 corollary) — put acks in-result;
+   consumers stream without waiting.
+6. **Relay translation for pub openables** (§1.5) — no
+   `PubTypedOpen` remains.
+7. **The client-side initiator-allocates put-open capability.**
+   Nothing in `ChannelClient` supports stream-then-open today:
+   `open_channel`/`open_channel_with_reply` await the open
+   *reply* before returning the halves — unusable when bytes flow
+   before the reply. The amendment supplies the putter-facing
+   shape (allocate odd id locally → write half streaming
+   immediately → send the open op carrying the reserved id → await
+   the single merged response). Without this the server-side
+   wrapper is untestable end-to-end in-crate.
+
+## 3. Verification gates for the S-01 implementation
+
+To be landed as tests in the same publish (deleting the pinned stub
+tests per review 010's action 3 —
+`make_open_handler_sink_returns_not_implemented`,
+`relay_tests.rs:113`, and the C-08/C-09 blocker-comment assertions
+they assert):
+
+- known-length put e2e: offer + adopt + bytes → one response,
+  `{channel_id, ack fields, handler result}` merge order verified;
+- unknown-length put e2e: the handler's digest rides the merged
+  response (the downstream putter's wire contract, ADR-012 §2's
+  `{token, digest}`);
+- publish-chunk rejection: a marked pub op carrying nonempty
+  publish chunks → loud rejection, no handler consumption;
+- establishment failure: `channel:open_failed`, channel torn down,
+  ledger un-incremented, racing bytes EOF-discarded;
+- `publish_schema` registration refusal on a marked op;
+- relay translation: a hub translating a pub openable end-to-end
+  (the ADR-051-§6 gap closed).
+
+## 4. S-02 / S-03 / S-04 from the downstream seat
+
+No alkblobs requirement rides any of the three — the ops module
+rides neither `channel/control` nor `channel/resources/subscribe`
+nor `op/register`-announced streaming. Each remedy is downstream-safe:
+
+- **S-02/S-03**: implement-or-stop-advertising per the ruling;
+  implementing both is preferred (the publish is one 0.x bump
+  either way, and re-advertising later would be a second bump).
+  What the downstream needs: nothing. Do not couple the S-01 shape
+  to these designs (the OQ-39 control-handle and OQ-40 enumerator
+  designs are independent machinery).
+- **S-04**: forwarding-through
+  (`make_streaming_forwarding_handler` /
+  `make_sink_forwarding_handler` already exist) over rejection —
+  the rejection leaves a discoverable-but-unusable service
+  announcement, which is the same consumer-visible failure mode
+  the ruling targets, one layer over.
+
+## 5. The four published crates' impact (the same-publish update)
+
+No published consumer registers a Pub-typed openable (alktunnels'
+four openables are Sub-type; alkhttp has no openables in its
+default surface; alkty rides Sub + control-JSON; alksocks rides
+Sub) — **the S-01 implementation is capability-additive in
+practice**. The semver-relevant risk concentrates in what the
+publish *removes*:
+
+- S-02/S-03 implemented → additive, zero removals, the four crates
+  re-verify and bump their floors only.
+- S-02/S-03 stop-advertised → two discoverable ops disappear;
+  acceptable per the ruling, but a 0.x removal worth a changelog
+  line for every consumer.
+- S-01/§2's wire pins (reserved key, reject-chunks) carry no
+  shipped consumer; the first consumer (alkblobs' put) pends
+  behind the amendment — ADR-014 §3's gate — and floors up to the
+  amendment release at task start.
+
+## 6. Sequencing for the one publish
+
+1. The four amendment documents (ADR-047 amendment 4; the
+   OQ-39/OQ-40 promotions; the S-04 pin) — drafted for review
+   before code, per the working agreement.
+2. Implementation + the §3 gates + the review-010 action-3 guard
+   (`not_implemented` source-tree grep wired into AGENTS.md's
+   release checklist; the four pinned stub tests deleted).
+3. Docs: OQ-39/40 resolved, C-08 closed, channel-operations.md's
+   hedge-era sentences rewritten, review 010's S-01 sketch
+   corrected to this review's shape (so the published record stops
+   carrying the wrong-graph reading).
+4. One publish, all downstream floors bump in it.
+
+## References
+
+- review 010 (the stub sweep this review amends the S-01 path of)
+- alkblobs ADR-014 (`014-marked-pub-put-contract-and-alkcall-gate.md`)
+  — the downstream ruling; its §2 pins the ack-timing asymmetry
+- alkblobs tasks/ops-put.md — the paused task; its Notes record the
+  gate and the two timing clarifications
+- ADR-040 (bounded buffer — the backpressure the data plane rides),
+  ADR-046 (the pub lifecycle's single response), ADR-047 §2/§5
+  (the marker; connection-owner allocates), ADR-049 + amendments
+  2/3 (establishment, plan, reply fields; the RESERVED_REPLY_KEY
+  pattern the input-side reservation mirrors), ADR-050 (pumps)
+- ADR-051 §6 (the relay-side documentation of the same gap)
+- `src/channels/manager.rs` (`next_channel_id` odd/even;
+  `drain_early_arrivals`), `src/channels/operations.rs` (the stub,
+  the wrapper), `src/channels/relay.rs` (`PubTypedOpen`)