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

# Review 011 — The marked-pub open contract: downstream input on review 010's S-01, and what the single-publish fix must pin

## Status

Closed — 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.

**Closed 2026-10-13:** all seven §2 pins are implemented and pinned in
ADR-047 amendment 4 / ADR-052 / ADR-053 / ADR-022's 2026-10-13
amendment, with the §3 verification gates landed as tests
(`channels::operations::pub_open_tests`,
`channels::hub_leg::gate2_tests::gate_pub_relay_put_end_to_end`, the
registration-invariant tests in `registry::registration` and
`registry::op_register`), the guard is `tests/stub_guard.rs`, and the
docs rewrites below are done. The §6 sequencing concluded.

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`)