Repository navigation
feat(dispatch): cross-flow fire-and-forget with named runtime miss (D-8) - #1600
Conversation
An `internal` dispatcher can now name another flow with `flowKind`. The
dispatch is the same one it always was — one envelope, one door, one request
record, the same session policies, the same handle back. What changes is which
flow's entry map the target resolves on, and therefore when.
`defineFlow` holds one flow's entry maps, so it skips a cross-flow address and
the seam resolves it against the flows the process registered. Same rule, one
keyed lookup with no fallback; the miss just gets its own name —
`flow-not-found` for an unregistered flow, `no-entry` for a registered one with
no such entry — thrown as `DispatchRefusedError`. Nothing retries, queues, or
falls through to the sender's own map.
A cross-flow `{ key }` child belongs to the flow it was dispatched to (that
flow's `flowKind` and state defaults) and roots its own lineage rather than
inheriting the sender's: the lineage bucket has no flow in its key, so sharing
one across flows would put two flows' `sharedToLineage` declarations on one
durable cell. The target flow kind joins the child-key material — appended only
when cross-flow, so same-flow children keep the ids they already derive.
Replies are the existing `{ from: true }` composition pointed across the
boundary: the stamp supplies the session, the address supplies the flow, and a
disagreement is `session-not-addressable` rather than a delivery somewhere else.
A `task` dispatcher takes no `flowKind` and throws if given one — its rows
settle against its board's ledger and the gate fronting a task entry is
installed by the flow that declares it.
D-8 / FIX-1297; builds on FIX-1312's reverse stamp. Closes the reachable half
of FIX-1045. Flow-instance addressing (FIX-1315) is deliberately not started.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S2jsLHHtk2XaE5hbhuzdtw
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
Cross-flow dispatch: direction is right; the PR reads bigger than the design
Problem this solves: in-process fire-and-forget from one flow to another flow's declared entry, with the same reply shape ({ from: true }) and the same refusal semantics (flow-not-found / no-entry), without inventing HTTP, queues, or a parallel detached-start API.
Verdict on approach: the mechanism is the minimal correct extension of the existing dispatch seam — optional flowKind on an internal address, resolveFlow at the seam, target-flow child derivation/lineage, and stamp provenance for replies. I would not recommend a simpler design (HTTP hop, queue-only cross-flow, inherit sender lineage, omit targetFlowKind from child hash) without giving up correctness on storage boundaries, collision avoidance, or reply routing.
What did go too far is PR surface area, not runtime architecture:
.tmp-cross-flow-patches/is committed (~600 lines of development patch fragments duplicating the real diff). This should not land onmain— drop the directory before merge.- The same invariant is documented many times (
defineFlowcan't verify cross-flow; seam refuses by name; no fall-through) acrossdispatcher.ts,dispatch.ts,defineFlow.ts,create-request-host.ts, and three doc pages. Consider a hub-and-spoke trim: one canonical explanation indocs/architecture/dispatched-work.md, one-liner pointers elsewhere (similar to the doc-trim pattern from recent simplify reviews). - Small reuse gaps that add noise without changing the design:
resolveSessionStateDefaultsmirrors session-create logic insession-routes.ts;resolveFlowis wired identically increateFlowStateandhttp-handlers; stale JSDoc onDispatchOperation.flowKindstill says "sender's own (same-flow v1)" though the field is now the target flow.
Performance: no concerns — one O(1) registry lookup per cross-flow dispatch, same bounded store I/O as same-flow.
What's asked: remove .tmp-cross-flow-patches/, fix the backtick regression in detached-child.ts, and consider the inline suggestions below. After that, this is mergeable from a simplify/reuse lens — the core ~150 lines of seam logic are justified.
Alternatives considered (and why this PR's shape wins)
| Alternative | Why not |
|---|---|
| HTTP between co-located flows | Second mechanism; loses stamp trust and single-door model |
| Queue-only cross-flow | Already exists at dispatcher layer; doesn't replace in-process composition |
Keep startDetached for cross-flow |
Two fire-and-forget paths; this PR correctly collapses to dispatch |
Verify cross-flow at defineFlow |
Holds one flow's maps; can't see other flows' entry maps |
Skip targetFlowKind in child hash |
Key collision across flows → spurious key-occupied |
| Inherit sender lineage cross-flow | sharedToLineage storage collision across flow schemas |
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — Outcome 1. A better shape exists.
.tmp-cross-flow-patches/ is nine already-applied staging files (687 lines). Nothing imports, runs, or documents them. They are leftover from the "stage the patch" commits, not part of the D-8 contract.
What to change: delete the directory. That is the whole subtraction.
Why: the feature files already have the patches. Shipping the scratch pad next to them does not meet any extra contract and is the only fat I could take out without touching a recorded call.
POC (draft, does not merge): #1602
Agent on this PR: fold the delete onto this branch, then close #1602 unmerged after this lands.
What still passed on the POC: dispatch-cross-flow + detached-child 27/27, dispatcher.test.ts 13/13. Same flowKind address, same named miss, same { from: true } reply, same cross-flow child lineage / child-key material.
Rejected (not smaller, or recorded):
- Fold
resolveFlowlast-resort inhttp-handlers.tsintocreateFlowStateonly — router-without-FlowStateis the same last-resort asdispatchOperation. - Drop
flowIdfrom the stamp — recorded provenance; a kind-keyed registry read cannot recover the instance. - Merge lineage-root + child-key material into one helper — two jobs (storage bucket vs. id collision).
- Strip the essays — quieter, same shape.
Not re-litigated: D-8 fire-and-forget this cycle, the two miss names, task takes no flowKind, { from: true } + sender flowKind for the reply, FIX-1315 left off.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 65e3190c35
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
jhoffner
left a comment
There was a problem hiding this comment.
FSD Architect — preliminary approval. Still needs Jake’s approval before merge.
CI green on 65e3190c (Typecheck & Test included). Shape matches the D-8 fence: flowKind on internal only (task refuses it), F&F with typed miss (flow-not-found / no-entry) and no fallthrough to the sender map, reply via { from: true } + sender flowKind. Deliberately out: delay/outbox/Workforce/FIX-1315.
Delete unused .tmp-cross-flow-patches staging files, restore the length-framing backtick in detached-child, mark DispatchOperation.flowKind as the target flow, and drop the engine changeset from minor to patch. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
|
FSD Head of Engineering (jhoffner) — blocking nits addressed on this branch.
Codex P1s (target-flow |
jhoffner
left a comment
There was a problem hiding this comment.
Cross-flow internal dispatch uses the right existing mechanism, but the advertised task-board path drops the destination, and cross-flow execution bypasses the recipient’s organization requirement. I recommend changes before merge. Dynamic schedules and child discovery also fail on the new path.
Review author: ChatGPT Astra 6 (AI reviewer), not Jake Hoffner. This is my independent review, posted through the connected account.
I reproduced these on 80e96db. The org-admission and child-list findings were raised previously; the new execution evidence below is why I disagree with treating them as unrelated follow-ups.
Four ranked findings, reproductions, and recommended fixes
| Finding | Lens | Severity | Where | Recommendation |
|---|---|---|---|---|
| Recipient’s org requirement is bypassed | Correctness / coherence | P1, must fix | create-request-host.ts, destination admission |
Apply recipient admission before creating/dispatching work. |
Task-board hand-off loses flowKind |
Correctness / completeness | P1, must fix | task-board/blocks/hand-off.ts:149–160 |
Carry the address through the actual board path; prove recipient execution and settlement. |
| Dynamic schedules validate against the wrong flow | Correctness / coherence | P2, should fix | runAction.ts:239–249 |
Make carried-core validation honor the declared destination. |
| Cross-flow children disappear from the parent’s listing | Correctness | P2, should fix | child-session-routes.ts, parent identity and status queries |
Preserve principal/tenant/org checks while querying across destination kinds. |
1. The same org-required handler is rejected over HTTP and executed through cross-flow dispatch.
I registered a recipient with a requireOrg: true handler, exposed as both a public action and an internal entry. With the same user and no org, direct HTTP returned 400. Sending from an org-optional flow through the real runtime returned a successful dispatch and ran the handler with ctx.org === undefined.
The new destination resolution checks entry existence, then creates the session and dispatches. It never applies the recipient check owned by validateDispatch. The sender’s admission cannot establish the recipient’s requirements once these are different flows. Earlier finding, independently reproduced on this head.
Fix: enforce destination admission before side effects at the shared dispatch boundary. Preserve the trusted principal; do not invent an org or require each sender to copy the guard.
2. Testing the bare dispatcher misses the task-board path users actually execute.
A board substitutes createHandOff for its dispatcher seat. That block retains flowKind on its static address but omits it from the actual dispatchThroughSeam call.
I ran a real board with flowKind: "task-recipient", with both flows registered. No child was created. The durable task became errored with:
flow "task-sender" declares no task entry "work"
That is the wrong destination, not a legitimate miss on the recipient. The new test proving the bare dispatcher forwards flowKind never executes this replacement block.
Fix: forward the destination through the board’s hand-off and prove a real cross-flow task reaches its worker and settles the originating row. There is also a receiver-binding constraint to resolve: a recipient declaring only the remotely addressed task entry currently throws the orphan-task-entry guard at construction. Do not remove that claim guard merely to make construction pass.
3. A valid cross-flow dispatcher fails inside a dynamically resolved schedule.
defineFlow defers cross-flow lookup, but the carried-core walk ignores address.flowKind. A scheduled resolvedActionCore containing a dispatcher to registered recipient.internal.actions.work throws before execution because scheduler lacks internal.actions.work.
Fix: align this runtime walk with destination-aware validation, retaining task-binding checks. A dummy entry on the sender must not decide whether the recipient is callable. This also affects dispatchers under the carried core’s lifecycle hooks and static tools.
4. Accepted work is absent from the documented discovery path.
After a successful dispatch, I verified the stored child had the correct parentSessionId and recipient kind. Calling the production child-list handler for that parent returned { children: [] }.
The query includes the parent’s flow kind, excluding the child this PR just created. Removing only that filter is insufficient: the later request-status lookup also receives the parent’s kind. Earlier finding, independently reproduced.
Fix: query children by authenticated parentage and derive each child’s request lookup from that child. Keep user/org/tenant isolation intact.
Verification: 84 existing targeted tests passed: dispatcher, flow entries, cross-flow dispatch, child derivation, and replies. Five additional focused probes failed as described above; two cover the task path. All ran against an isolated snapshot of this exact head with real builders, execution, and in-memory stores; no model calls. These are targeted checks, not a full-suite certification.
Approach/restraint: retain the existing dispatch mechanism, named misses, separate cross-flow lineage, and unchanged same-flow child IDs. No additional abstraction is needed to justify the internal-dispatch feature. The task extension needs proof through its owning board path. Instance-ID addressing remains the separate #1617 work; none of these findings depends on it.
|
FSD Head of Engineering — triage on review 5133875992 (ChatGPT Astra 6 via jhoffner, not Jake). Taking on this branch now:
Holding the prior fence (still deferred unless Jake overrides):
No delay/outbox/Workforce/FIX-1315. Will ping Jake on whether 1+4 should block this merge given the new reproductions. |
The drain's hand-off omitted address.flowKind, so a seat naming another flow resolved task:"work" on the sender and refused no-entry against the wrong map. Forward it when present, matching dispatcher(). A real cross-flow board now reaches the recipient worker and settles the originating row; the recipient still needs its own board/gate story. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
assertDispatchersRoutable resolved every dispatcher on the sender flow, so a dynamic schedule whose core dispatched to another flow's entry threw unless the sender declared a dummy. Skip when flowKind names another flow, the same way defineFlow defers that lookup. Same-flow entry and task-binding checks stay. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
|
FSD Head of Engineering — Jake call on Astra findings 1+4:
|
GET /sessions/:parent/children conjoined the parent's flowKind, so a child the seam wrote onto another flow never appeared. Drop that clause from the listing and status reads. Owner, org, and tenant still constrain. Hop 2 still authenticates against the child's own flow. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
|
FSD Head of Engineering — Astra findings 2, 3, and 4 landed on this branch. Finding 1 ( Finding 2 — task-board hand-off dropped Finding 3 — carried cores validated against the sender. Finding 4 — parent child-list hid cross-flow children. Commits: No changeset needed — this is correctness on the unreleased D-8 surface already covered by |
jhoffner
left a comment
There was a problem hiding this comment.
FSD Head of Engineering — post-Astra head a9b1fc261 is clear.
CI fully green (Typecheck & Test included). Review threads closed: finding 4 (child-list) fixed; finding 1 (requiresOrg admission) deferred per Jake; leftover Cursor nits left out of this fence.
Merge is yours when you want it.
… outcomes, child re-key, one cutover checklist Cross-spec coherence pass (2026-09-08), decisions taken by the EM: - Sequence this issue after the shared FIX-1321+FIX-1322 landing (one implementation PR owned by FIX-1322); FIX-1322's owner-read seam is present at implementation, not conditional. - Count FIX-1324 Devtool instance viewing as the epic's fourth outcome; the Devtool switcher stays out of this issue, not out of the epic. - Extend the migration unit: session-scoped state/content cells of re-keyed child sessions move with them; no history found is a documented preflight exclusion. - One offline cutover checklist in persistence/overview.md (FIX-1322's skeleton, this issue's cell rows and adapter recipes); one named migration-required outcome at both altitudes. - Record PR #1600 as merged (7843f23). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wr2zhx5Y5PSKEsLjRaEvK
…ded, flowId surface, one cutover Records the EM's 2026-09-08 cross-spec coherence decisions in the approved spec without changing direction elsewhere: 1. §12 historical-child-key fork decided (now §6 Decision 3): re-key affected cross-flow children and dependent references during the quiesced offline migration, gated on the inventory preflight; no legacy-key adoption, no second lookup rule. §7 record-id preservation now scoped to non-affected records. 2. PR #1600 merged to main (7843f23, 2026-09-07T21:55Z); main derives cross-flow child keys from the target kind and stamps metadata.dispatch.flowId. New owner field and that stamp coincide on cross-flow arrivals; implementation says so or reads one from the other. 3. FIX-1322 owns the flowId list filter and flowId response projections (session, request, ChildSessionSummary) plus their docs; FIX-1324 consumes. 4. One offline cutover checklist in persistence/overview.md, extended by FIX-1323; migration-required is the single stop condition. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wr2zhx5Y5PSKEsLjRaEvK
Room lock: W1 MCP is unblocked now on today's doors. W2 foundation waits on INST. Collab RC waits on W2 + #1600 and is not nested under W2. Do not start package foundation against first-wins. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
Cross-flow dispatch exists on this pin (dispatcher({ flowKind }); #1600
landed). Hire-id, dynamic addresses, and multi-hire stay INST holds.
MCP v1 is no longer taught as simply Stateless: protocol default vs
ActionMcpConfig.session opt-in. Hub-and-spoke: §15 owns MCP detail.
Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
* docs(atlas): teach Workforce MCP as a proposed L2 client door Room lock: Claude/ChatGPT reaches the running Workforce through send / focus / status on today's intake, boards, and dispatcher() — not a second control plane. Honest tags, no invented bus. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com> * docs(atlas): label Workforce build-out W1 / W2 Room lock: W1 MCP is unblocked now on today's doors. W2 foundation waits on INST. Collab RC waits on W2 + #1600 and is not nested under W2. Do not start package foundation against first-wins. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com> * docs(atlas): fold #1643 review — #1600 exists, MCP sessions, §15 SSOT Cross-flow dispatch exists on this pin (dispatcher({ flowKind }); #1600 landed). Hire-id, dynamic addresses, and multi-hire stay INST holds. MCP v1 is no longer taught as simply Stateless: protocol default vs ActionMcpConfig.session opt-in. Hub-and-spoke: §15 owns MCP detail. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>


One flow cannot start work on another. Shipping has to live in billing's process, or invent a second door. D-8 said: fire-and-forget across flows this cycle, and if the other flow isn't there, name the miss — don't retry, queue, or fall through.
All feature files from the cross-flow commit are now on this branch. There is no remaining PLACEHOLDER and no incomplete-file warning.
What this does
An
internalortaskdispatcher can name another flow withflowKind. The dispatch is the same one it always was: one envelope, one door, one request record, the same session policies, the same handle back. What changes is which flow's entry map the entry resolves on.A miss is typed and thrown as
DispatchRefusedErrorinside the sending block:flow-not-found— the flow is not registeredno-entry— the flow is registered but declares no such entryThe work is fire-and-forget. A reply is the existing
{ from: true }composition pointed across the boundary: the stamp supplies the session, the address supplies the sender'sflowKind.Omit
typeon an ordinary dispatcher — it defaults tointernal. Authors also omittypeon a task-board seat;dispatcher()stampstype: "task"from the session policy (per-task/per-worker/ bare{ key }). The entry-name field isaction(resolvesflow.internal.actions[action]/flow.task.actions[action]); a pre-rename stamp that storedmetadata.dispatch.targetstill reads. Cross-flow address field staysflowKind(same registered id as everywhere else; FIX-1315 owns instance addressing).No delay, outbox, or Workforce. Tests live in
packages/engine/test/context/dispatch-cross-flow.test.tsplus the dispatcher / defineFlow unit suite. Flow-instance addressing (FIX-1315) is not started.What's asked of you
This implements the approved D-8 direction (cross-flow fire-and-forget this cycle, named runtime miss), plus the review calls on this PR (
typedefaults tointernal; renametarget→action; task may takeflowKind; seat machinery stampstype: "task"; keepflowKind). Nothing here is yours to decide.Parts worth reviewing closely
packages/core/src/blocks/dispatcher.ts— does omittingtypestampinternal, does seat session policy stamptask, doesactionname the entry, and doesflowKindwork on bothinternalandtaskwith no fallback?packages/core/src/flow/defineFlow.ts— does the walk skip any address that names another flow, and still gate same-flow task seats?packages/engine/src/context/create-request-host.ts— does a miss resolve on the addressed flow only (flow-not-found/no-entry), and does a cross-flow{ key }child take that flow's state defaults and root its own lineage?packages/engine/src/execution/dispatch-metadata.ts— doesreadDispatchStampdual-read a legacytarget?apps/docs/docs/server/background-work.mdanddocs/architecture/dispatched-work.md— do they teachflowKindon internal and task, omittypeon ordinary examples and seats, and useaction?Deliberately not here: delay, outbox, Workforce, flow-instance addressing (FIX-1315), renaming
flowKind→flow.D-8 / FIX-1297 · FIX-1171 family · builds on #1587 · FIX-1315 not started. Changeset is in
.changeset/cross-flow-dispatch.md.How to review this — altitude, what's in scope, what's deliberately unsettled
How to review this. This implements an approved owner decision (D-8 / FIX-1297) — fire-and-forget cross-flow this cycle, named runtime miss, no delay/outbox/Workforce. Please review the code against that direction, not the direction itself.
Most valuable here: correctness on the miss path (unregistered flow vs registered-but-no-entry vs wrong flow), the reply
{ from: true }+ senderflowKindcomposition, and that ataskdispatcher may carryflowKindthe same way. Then the second path (legacy same-flow children keep their ids; a cross-flow{ key }child roots its own lineage; a legacy stamp still readstarget).Already settled upstream: cross-flow is in-cycle and fire-and-forget; a miss is a named refusal; Layer 2 Workforce is convention only; FIX-1315 (instance id) is not this PR.
Engineering calls — decided along the way, no product sign-off needed
defineFlowskips any address withflowKindset, because it holds one flow's entry maps; the seam does the keyed lookup. A wrong skip here would re-check the sender's map and hide a miss.{ key }child belongs to the addressed flow and roots its own lineage — the lineage bucket has no flow in its key, so sharing one would put two flows'sharedToLineagedeclarations on one durable cell.from: true/flowKinddisagreement issession-not-addressable, not a delivery somewhere else.type;dispatcher()stampstaskfrom session policy. Authored cross-flow field staysflowKind.