**Note** from Bead: Orchestrator · [canonical source](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/2026-06-20/notes/04-response-dock-the-return-lane.md) · session 2026-06-20 · discussion: Talk: Orchestrator
**Bead:** `4c6470f9` (`bead-orchestrator`) · 2026-06-20 · for the Redfish–Simtable dev team **Trigger (verbatim):** *"beads should have a /response directory too. don't you think?"* A protocol proposal: the bead root layout should define a **return lane** for the async dock. This sits at Duty 1 (root-file conformance) × Duty 6 (threads/links). Exploratory; proposes a convention, poses open questions, does not ratify into `beads.md` (that is bead-remote `792ebed9`'s + `fe7fbaf5`'s call, co-designed).
## 1. The gap The async lane is **half-defined**: - `uploads/` — the **provenance dock** (immutable inbound; "hey you, it's me"; `PUT` → `202`). - `request/` — bead-remote (`792ebed9`) adds a **live-request ingress** "sibling to the provenance dock `uploads/`" that a bead's `step` watches. But `202 Accepted` means *accepted, not answered*. **Nowhere does the answer have a defined home.** The return lane is missing.
## 2. The counter-question: is `response/` even needed, or does `uploads/` already do it? Docks are **bidirectional by recipient**. A `PUT`s into `B/uploads/`; B can `PUT` the answer back into `A/uploads/`. So for any caller **that has its own dock**, `uploads/`-reflection already *is* the response channel — and a `response/` would be partly redundant. This must be addressed or `response/` is just symmetry for its own sake.
## 3. Where `response/` actually earns its place Two things `uploads/`-reflection cannot cover: 1. **Dock-less callers (decisive).** A browser / CB caller has **no URI you can `PUT` into** — it can only **poll**. The only way to return an answer to it is a **pullable** `<handler-bead>/response/<id>`. The response must live on the *handler*, read by the caller. Push-back is impossible to a node with no dock. 2. **Inbox hygiene.** Mixing unsolicited requests and solicited replies in one `uploads/` muddies the dock. `response/` separates "answers to what I asked" from "new demand" — the inbox-vs-replies distinction. So: **keep push-into-the-requester's-`uploads/` for callers that have a dock; add `response/` for dock-less callers and inbox separation.** Both, by caller capability — not one replacing the other.
## 4. Three constraints a naive `response/` would violate - **Correlation is mandatory.** Key the answer to the request: `request/<id>` → `response/<id>` (or `uploads/<env-id>` → `response/<env-id>`). A flat dir with no id cannot match answer to question. - **Lifecycle differs from `uploads/`.** `uploads/` is *immutable provenance* (`beads.md` treats it like `chats/`). Responses are *generated and ephemeral* → TTL + apoptosis (a response that is read + acked can be reaped; an unread one expires). Sync treatment: **regenerable, not provenance** — likely not synced raw, or synced with a short TTL. (project_apoptosis-vs-necrosis) - **It is the efferent half of a thread, not a new orphan dir.** With links first-class and thread-carrying (03-links-as-first-class-primitives), a request+response pair **is a thread riding a link**. `request/` + `response/` are that thread's two ends materialized as directories. This keeps the addition from being protocol sprawl: it is the dock corridor completed, afferent (`uploads/`/`request/`) ⊕ efferent (`response/`).
## 5. Proposed shape ``` <bead>/ uploads/ # provenance dock (immutable inbound) [existing] request/ # live-request ingress, step-watched [bead-remote 792ebed9, proposed] response/ # return lane: response/<req-id> answers a request [THIS proposal] ``` - `response/<id>` carries the answer + a sibling `<id>.meta.json` (status, ts, correlates-to, ttl, ack-uri). - **Pull**: dock-less caller polls `<bead>/response/<id>` until present, then acks (which permits reaping). **Push** remains available: a caller with a dock may instead ask for the answer in *its* `uploads/`. - **Status pattern**: mirrors the existing `process-latest-on-complete` (note 02 §7 Q5) — `pending` → `done`; an overrun coalesces to latest. - Lives at rung-0: writing/reading `response/<id>` is deterministic I/O; no model call.
## 6. Boundary / ownership This note is the **orchestrator's conformance view** (the root-file set it would validate) and its **thread view** (Duty 6). The convention itself should be **co-ratified** by bead-remote (`792ebed9`, which owns `request/`) and the handler contract (`fe7fbaf5`, which owns the sync/async lanes), then folded into `beads.md` — per the "pilot then ratify" rule (note 02 §7 Q6). The orchestrator does **not** create `response/` in any bead's tree; it would only flag its absence as a conformance finding once the convention is ratified, and *offer* a stub.
## 7. Open questions (Stephen binds) 1. **`response/` vs reflect-into-requester's-`uploads/`** — adopt both (by caller capability, as proposed), or standardize on one? 2. **Correlation key** — **Recommendation (pending Stephen): caller-generated GUID.** The caller mints the id (UUIDv7/ULID preferred over v4, for free time-ordering). Rationale: (a) it is the only scheme that works for **dock-less / opaque-write callers** — they know `response/<id>` *before sending*, no need to read a `202 Location` they can't see; (b) **idempotency under retry** — same id on retry → handler dedups → at-most-once, essential on flaky tunnels; (c) consistent with the ecology — beads/links are client-minted GUIDs with no central allocator, and a request is a transient bead-like resource (the thread handle). Refinements: **scope the id under the caller's identity** (`request/<caller>/<guid>`, `response/` partitioned per caller → no cross-caller clobber/spoof; capability-token gated); the caller GUID is the **correlation/thread key** and the handler may keep its own internal id but **must echo the caller's**. Rejected: content-hash (collapses legitimately-repeated commands; no nonce) and handler-assigned (breaks dock-less + retry-dedup). 3. **Ownership of the response** — always on the *handler* bead (pull), or may it be pushed to the *caller's* `response/`? (Pull is required for dock-less callers regardless.) 4. **TTL + ack + reaping policy** — when is a response reaped (read-and-acked? fixed TTL? both)? Bounded ring like `state.skipped`? 5. **Sync treatment** — exclude `response/` from `/bead-sync` (ephemeral), or sync with a TTL? (`uploads/` is synced as provenance; `response/` should not be.) 6. **Relationship to threads/links** — is `request/`+`response/` *the* canonical thread materialization (note 03), so a thread resource is just a view over the two dirs? Or is the thread the primitive and the dirs a projection? 7. **Ratification path** — fold into `beads.md` via `792ebed9`/`fe7fbaf5` after a pilot, or ship as a skill first?