ADR-0109: Grouped ask-and-dispatch — N questions, one fire
Context and Problem Statement
Ask-and-dispatch (ADR-0021) pairs one question with one target run. An asking command that needs several answers from the operator before it can hand work over has only two ways out: register one dispatch per question, which starts the target once per answer and gives it each answer in isolation, or block on ask-and-wait per question, which pins a process slot and a workspace for the whole human-think time — the cost ADR-0021 exists to avoid. Neither expresses "ask these three things, then start the agent once with all three". We need the grouped form: N questions answered independently, one run started after the last answer, carrying every answer.
Decision Drivers
- The target must start exactly once, after the last answer — including when the final two answers land concurrently, and across a server restart.
- Each question must stay an ordinary question: independently answerable, independently visible in the operator inbox, and usable through the existing answer route with no new endpoint for the operator.
- The group is the unit of every lifecycle decision: TTL expiry, cancel, boot re-fire and the settled-row prune settle all members together, never partially.
- A group multiplies questions against a per-process cap and against the global PENDING cap, so both bounds must be checked before any row exists, and the group's size needs its own config bound.
- Crash safety must be the same two-step model as a single dispatch: a group left mid-fire settles FAILED rather than firing twice.
- No new secret surface: a group row holds no params its members' answers do not already hold, and answers must not reach logs, spans or argv beyond what a single dispatch already does (ADR-0052).
Considered Options
- One parent
dispatchesrow (kind = GROUP) plus an ordered child table — the ADR-0026 join shape: the group row carries the target, params, TTL, owner and status;dispatch_group_questionsowns the ordered member set. - N independent SINGLE dispatches sharing a group id, fired by the last one to settle.
- A new
dispatch_groupstable with its own lifecycle, besidedispatches. - Client-side sequencing — the asker registers a single dispatch per question and passes a correlation id it uses to rejoin the answers.
- One question whose answer is a multi-field payload the operator fills in through the console.
Decision Outcome
Chosen option: "One parent dispatches row plus an ordered child table".
The group is a dispatch, so everything ADR-0021 built around a dispatch row is reused unchanged: the claim CAS that makes a fire exactly-once, the PENDING cap, the TTL sweep, the boot re-fire, the settled-row prune, the owner and secret snapshots, the hop authorization, and the whole /api/v1/dispatches surface. kind = GROUP selects the two places where a group differs — how its question set is resolved and when it is allowed to fire — and nothing else branches.
The N independent dispatches were rejected because each one carries its own claim, TTL and status: "the target starts once after the last answer" would become a coordination problem between N rows, with N ways to half-succeed — one answer firing early, one row expiring while its siblings are alive, and the prune deleting a row another row's fire still needs. A separate table was rejected for the mirror-image reason: it duplicates the status machine, the caps, the sweep and the whole read API to gain nothing the kind column does not already give.
A GROUP row's own question_id is a synthetic sentinel (group: + a UUID), because dispatches.question_id is uniquely indexed and a group names no single question; the ordered set is the child table's, keyed by (dispatch_id, position) with question_id indexed for the member → group lookup. Every member question is an ordinary questions row with dispatch_bound = 1, so it survives its asker exactly as a single dispatch's question does (ADR-0021), and findByQuestionId resolving through the member table is what lets the existing answer route fire a group with no change to QuestionRoutes.kt: the member's answer is the trigger, the group's own gate decides whether it fires.
The fire gate is DispatchGroupService.aggregateAnswers: null while any member is still OPEN, otherwise the answers as a JSON array in position order, delivered under the dispatch's answerParam. DispatchService.fire claims the group only after that gate passes, and the claim CAS remains the gate — the gate read is a pre-check, so the last two answers landing concurrently, or a boot re-fire racing a live answer, still start exactly one run. An aggregate over MAX_ANSWER_BYTES (256 KiB, well above maxGroupSize × maxTextLength) settles the group FAILED rather than leaving it PENDING on answers no start can carry; that throw is caught inside the fire path because the same path runs at boot, where it would otherwise abort startup reconciliation.
server.dispatch.maxGroupSize (default 8) bounds a group's size, checked before anything else and before any row is written, so a refused group is never observably partial. The group counts against the global PENDING cap and against the origin process's open-question cap — the latter is the bound on this call's own multiplication, N questions at once. That open-question check counts only the origin process's dispatch_bound = 1 questions and only group registration runs it: ordinary asks count their dispatch_bound = 0 rows against the same key, and a single dispatch's creation checks nothing. Counting every open question of the process was rejected because unrelated inbox traffic could then deny a group registration, and extending the check to single-dispatch creation was rejected because it would tighten ADR-0021's existing behavior, which this change leaves unchanged.
Consequences
- Good: the operator answers N ordinary questions; the console inbox annotates each member with its group through the dispatch summary it already renders, so no console change is needed.
- Good: one row carries the lifecycle, so cancel, TTL, boot re-fire and prune settle a group as a whole by construction rather than by coordination.
- Good: crash safety, caps, authorization and redaction are inherited from ADR-0021 unchanged; the new code is one service, one child table and the
kindbranches. - Bad: a GROUP row's
question_idis a value no question has, so any future reader of that column must branch onkind— the sentinel is the price of keeping one table and one unique index. - Bad: member rows outlive their member questions (cancel, expire and orphan-fail delete the questions but keep the ordered set), so a settled group still reports the question ids it owned; the prune deletes them with the dispatch. A reader that assumes "member row ⇒ live question" is wrong.
- Neutral: the answers arrive as a JSON array under one param. A target that wants them separately must parse them; the alternative — N env vars — would make the target's input schema depend on the group's size.
Pros and Cons of the Options
N independent SINGLE dispatches sharing a group id
- Good: no schema change; each answer is a normal dispatch.
- Bad: "start once after the last answer" becomes cross-row coordination — the last answer must claim a group-wide flag that is not the row's own status.
- Bad: TTL, cancel and prune each have to treat the N rows as one unit anyway, reimplementing the group without the row to hang it on.
A separate dispatch_groups table
- Good: the
dispatchestable stays single-question. - Bad: a second status machine, second cap check, second sweep, second prune and a second read API, all parallel to the first.
Client-side sequencing
- Good: no server change.
- Bad: the client would hold the "did everyone answer" state that the server already owns durably, and a client crash loses the group.
One multi-field question
- Good: one operator interaction; no member rows to order.
- Bad: it replaces the per-question answer surface with a payload form the console inbox does not have, so the questions could no longer be answered independently through the existing route — the shape this change is built around.
More Information
- ADR-0021 — ask-and-dispatch, the row and lifecycle this extends.
- ADR-0026 — join continuations, the parent-row + ordered-child-table shape reused here.
- ADR-0052 — the secret snapshots a GROUP row carries like any other dispatch.
- ADR-0101 — input inheritance, which a group to the asking agent gets for free.