Repository navigation
spec(epic): keeping flows alive, one page from an outside event to work that keeps going (FIX-1637) - #2368
Conversation
…ent to work that keeps going Epic-spec set for the docs-only epic: SPEC, DECISIONS (D1 open: fold FIX-1638 and FIX-1640 into FIX-1639; D2 a new page, not a nav change; D3 the event row names only shipped doors), BUSINESS-RULES (incl. project rule PR-1), PLAN, DOCS (shared draft), EVOLUTION, and six figures. Closure issue FIX-1642. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GmvuVRtAQQvxJfj4fMVirA
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Filed while the spec was written; wired to block closure FIX-1642. Set table, graph, path, plan seams and ER-6 updated: its authoring shapes stay user-land in examples/wake-authoring and are never taught as framework features. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GmvuVRtAQQvxJfj4fMVirA
|
Process guards is red, but not because of this PR.
Generated by Claude Code |
There was a problem hiding this comment.
Problem
Builders still cannot get from “I want a flow alive 24/7” to shipped webhooks, schedules, dispatch, and the BullMQ { id } fence without stitching eight reference pages themselves. This epic correctly chooses one new guide (D2), honest export-only event rows (D3), and a closure run that proves the page—not a nav tweak or a runtime epic.
The risk is not direction; it is coordination surface: the set still reads like five parallel deliverables while D1 already argues for one writer, and several artifacts repeat the same prose (page draft, terms, fence) at epic altitude.
Verdict
Direction: keep. One page + ER-15-style proof is the right shape for Goal 4 and matches stronger docs epics (e.g. FIX-1553’s single guide child, FIX-1592-style closure).
Artifact: simplify before children spin up—not necessarily before epic direction approval, but resolve internal contradictions in this PR so epic-wake and implementers are not fighting dual-mode specs.
I am not approving yet; the inconsistencies below are cheap to fix and prevent wasted gates.
What went further than necessary
| Area | Observation | Lighter path (same outcome) |
|---|---|---|
| Issue fan-out | PRD’s three doc children (1638/1639/1640) plus POC plus closure, with D1 still open | Close D1 at the epic gate (fold into FIX-1639). Set table → 1639 + 1642 (+ optional 1641). Cancel or close 1638/1640 in Linear in the same motion; drop dashed “if re-split” columns from ER-2/3/5 and ownership once decided. |
| FIX-1641 | Narrative: “beside the page,” “nothing it must wait for”; table + DECISIONS: blocks FIX-1642 | Decouple closure from 1641. ER-15 proof is page-only; ER-6 already forbids teaching the example as API. Block 1642 on 1639 (and 1638/1640 only if re-split). Merge 1641 at wrap or link optionally from the page. |
Epic DOCS.md |
Near-publishable blockquotes (opening, id/key table, flow/host/ops, terms) | Epic doc = outline, sidebar placement, drift/link ops (FIX-1553 pattern). FIX-1639 issue spec owns the draft prose and export re-check at publish time—avoids two canonical copies and the 466143f pin going stale. |
| Rules | 16 ERs + PR-1; ER-7–11 largely duplicate SPEC “Not doing” | ~8 outcome rules + consolidated invent-kills in SPEC; move ER-12/13 to PLAN coordination one-liners. |
| Figures | 6 SVGs (3 template + 3 trade-off cards for D2/D3 already decided in prose) | Keep end-state, ownership, path (+ mermaid goal-check). Drop or mermaid-only settled D2/D3 trade-off SVGs; keep open-one-page.svg while D1 is open. |
| FIX-1641 packaging | examples/wake-authoring + blocks closure |
If retained: align with spec-poc retained tree under specs/epics/FIX-1637/poc/ or treat #2369 as non-blocking exploration—not a fifth child on the closure bar. |
What is already the best call
- D2 (new page vs nav-only): the missing table, fence on the reading path, and terms are real gaps on
main. - D3 (shipped doors only): ties the page to exports and FIX-441 cancelation—good kill switch against Architect drift.
- ER-9 (link, don’t rewrite eight reference pages) + kill line (nav-only escape if honest page is mostly “not yet”).
- Closure signal (nav → fixture wakes → exports → BullMQ refusal → planted false claim): heavy for docs-only but appropriate anti-game; tiering static export scans vs full Redis/BullMQ run on every typo is an optional cost knob, not a direction change.
Need your sign-off (unchanged in spirit)
D1 — one page / one writer vs PRD three-way split remains the right gate. Recommendation in the spec (fold) is sound; the spec should not carry full dual-mode graphs and ownership after you answer—pick one and delete the ghost children from the closure blocked-by set.
Skipped (larger / judgment)
- Collapsing the epic into a single FIX-1639 issue (loses project-programme tracking for PR-1 / FIX-1634 seams)—reasonable if you accept weaker cross-epic visibility.
- Dropping FIX-1641 entirely—judgment on whether three authoring shapes are worth any retained evidence; not a pattern violation alone.
Automation: /simplify review (read-only; no code changes).
Sent by Cursor Automation: Review For Best Approach
| | [FIX-1638](https://linear.app/fixpoint-labs/issue/FIX-1638) · config matrix | The flow / host / ops table | **Proposed: folded into FIX-1639** ([D1](DECISIONS.md#d1), open) | Backlog | | ||
| | [FIX-1640](https://linear.app/fixpoint-labs/issue/FIX-1640) · terms | Wake, dispatch, schedule tick; `epic-wake` moves to contributor docs | **Proposed: folded into FIX-1639** ([D1](DECISIONS.md#d1), open) | Backlog | | ||
| | [FIX-1641](https://linear.app/fixpoint-labs/issue/FIX-1641) · wake authoring POC | Three authoring shapes in an examples package, each compiling to today's bindings | Exploration the owner filed with the Architect; evidence, not surface. Nothing it adds ships as a framework API here ([ER-6](BUSINESS-RULES.md#what-no-child-may-do)) | Backlog · examples [#2369](https://github.com/fixpoint-labs/flow-state-dev/pull/2369) open | | ||
| | [FIX-1642](https://linear.app/fixpoint-labs/issue/FIX-1642) · closure · **required** | The QA plan: the page followed as written on one `main` commit | Proves the whole ([ER-15](BUSINESS-RULES.md#the-closure)) | Backlog · blocked by FIX-1638, 1639, 1640, 1641 | |
There was a problem hiding this comment.
Closure blocked-by vs narrative: This row blocks FIX-1642 on FIX-1641, but the flow section below says FIX-1641 hands the page nothing it must wait for, and ER-15’s proof is entirely page-scoped. For a docs epic, that extra edge will keep closure red in Linear/epic-wake while the published page is already provable.
Suggestion: Block 1642 on 1639 only (plus 1638/1640 if D1 re-splits). Treat 1641 as parallel to wrap—optional link from the page, findings filed to 1639 if they change copy.
There was a problem hiding this comment.
Folded as a clarification in c3e6aff, not as the suggested unblock. The closure rule (orchestration.md → "The closure issue") wires every child to block the closure, so FIX-1641 keeps its edge. The page never waits for it. The closure run waits for #2369 to merge, or for the owner to close FIX-1641 with its findings filed to FIX-1639. SPEC's graph caption, PLAN's path text and DECISIONS.md → Decided in review now all say this.
Generated by Claude Code
|
|
||
| Solid edges are blocked-by; dashed edges into FIX-1639 are the proposed fold, and the one from | ||
| FIX-1634 is an input from another epic. If D1 re-splits, FIX-1638 and FIX-1640 publish beside | ||
| FIX-1639 and all still block the closure. FIX-1641 hands the page nothing it must wait for. |
There was a problem hiding this comment.
Same tension as the set table: solid edge 1641 → 1642 contradicts this sentence. If 1641 is exploration (ER-6), the mermaid should show a dashed “findings only” edge into 1639 or epic wrap, not a blocked-by into closure.
There was a problem hiding this comment.
c3e6aff: the edge stays solid because it's a real blocked-by in Linear. Its label now reads "lands or closes first" instead of "examples, findings". The caption says the closure doesn't check FIX-1641 and the page doesn't wait on it.
Generated by Claude Code
| its examples PR (#2369) already open: a `WORKER.md` wake block, today's flow-level bindings, | ||
| and a `wakes:` alias, each compiled by user-land code in `examples/wake-authoring` to the | ||
| bindings that ship. No framework API changes, so ER-6 holds. The page may link the example | ||
| and teaches neither as a framework feature. It blocks the closure like any child. |
There was a problem hiding this comment.
“Blocks the closure like any child” conflicts with PLAN/path.svg (“off the critical path”) and with “No end-state POC” in this file—1641 is a wake-authoring POC, not proof the page works.
Worth picking one story before merge so coordinators do not inherit both.
There was a problem hiding this comment.
One story now (c3e6aff). FIX-1641 blocks the closure because every child does. The closure doesn't prove it, and the page doesn't wait on it. "No end-state POC" now says FIX-1641 explores authoring shapes for one child and doesn't test how the set is divided. PLAN says a late #2369 would put it on the critical path.
Generated by Claude Code
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** · [Evolution](EVOLUTION.md) | ||
|
|
||
| The shared narrative, drafted once. FIX-1639 reconciles it against `main` and publishes it |
There was a problem hiding this comment.
This file is effectively a full page draft (blockquotes + export strings). Other docs epics (e.g. FIX-1553) keep epic DOCS.md to placement + shared narrative outline; FIX-1639’s issue spec owns publishable prose and re-checks exports on main at publish time.
Trimming here avoids two canonical copies (and duplicate maintenance of the id/key “proposal” vs ER-4) without changing what ships.
There was a problem hiding this comment.
Not folded. The epic template's DOCS.md asks for concrete proposed prose. The fence, table and terms here are the shared parts, the ones a D1 re-split would divide across children. The Ownership table already hands the specific draft to FIX-1639's own DOCS.md, and the publisher re-checks exports on main. I've routed a note to FIX-1639 to reconcile this draft rather than keep a second copy.
Generated by Claude Code
|
|
||
| | # | Rule | Owner | Checked at | | ||
| |---|---|---|---| | ||
| | ER-1 | One page, reachable from the docs site nav, carries the path in order: webhooks → schedules → outliving a turn → `{ id }` vs `{ key }` with the queue-host fence → channels vs boards | FIX-1639 | The closure run starts from the nav | |
There was a problem hiding this comment.
While D1 is open, every ER with “(FIX-1638 if D1 re-splits)” forces cross-spec-review and child specs to reason about two worlds. If fold is the recommended gate answer, consider stating procedurally: closure planning assumes fold until the owner explicitly re-splits—so 1638/1640 are not phantom blockers on 1642 while waiting on D1.
There was a problem hiding this comment.
Not folded, because the spec already covers it. D1 is answered at this gate, before any child spec starts (PLAN → "What unblocks what", step 1). On a fold, FIX-1638 and FIX-1640 close and their blocks on FIX-1642 go with them. Nothing downstream ever runs in two modes.
Generated by Claude Code
| **What would change my mind:** the three missing pieces fitting in a short section of an | ||
| existing page without it losing its subject. Then the kill line holds and FIX-1639 is a nav edit. | ||
|
|
||
|  |
There was a problem hiding this comment.
D2 is decided in prose (“Locks in: one new guide page”). The paired trade-off SVG duplicates the BP-041 card already above (“It comes down to what’s missing…”).
Optional simplify: keep SVG for open D1 only; use mermaid in “The tree” for settled D2/D3 to match peer epics (usually 3 SVGs + mermaid).
There was a problem hiding this comment.
Not folded. spec-figures.md → "The trade-off" requires a trade-off figure for every decision on SPEC.md's sign-off, whether it is settled or not. D2 is on that sign-off.
Generated by Claude Code
|
Owner clarification (Jake via Architect) — tighten D3 wording If any D3 / PR-body / figure copy still reads as “no cross-flow bus,” rewrite to:
Do not reopen FIX-441. Soft-relate only. Please update Linear: stamped on FIX-1637 / FIX-1641; soft-related FIX-441. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0ac4837847
ℹ️ 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".
| > | **A schedule** to start a run | `schedules.static.<id>`, a `defineScheduleBinding` with `cron` and `block`; or `schedules.resolve` for schedules stored at runtime; `authentication.resolvePrincipal`, for example `createBearerSecretPrincipalResolver` | `createScheduledTransportAdapter()` in `adapters`; a schedule index when one tick fans out to many stored schedules | A scheduler that calls `POST /api/flows/:flowKind/schedules/:scheduleId/dispatch` on time: Vercel Cron, Cloud Scheduler, EventBridge, or BullMQ's repeatable jobs through `@flow-state-dev/bullmq/schedules` | | ||
| > | **Another flow** to start a run | On the sender, `dispatcher({ flowKind, action, session })`; on the receiver, `internal.actions.<action>` | Both flows registered on the same `createFlowState` | Nothing | | ||
| > | **Another system** (a queue, an event bus) to start a run | The entry it should run | A custom inbound transport adapter in `adapters` | Whatever delivers to your adapter | | ||
| > | **Work to continue** after the request returns | `dispatcher()` into `internal.actions`, or `.sideChain()` in a sequencer | `worker: bullmqWorker({ connection })` for queue-backed runs, and its mode | Redis, and a worker process when the web tier runs `dispatch-only` | |
There was a problem hiding this comment.
Do not promise that side chains outlive requests
The table presents .sideChain() as an alternative to dispatcher() for work that continues after the initiating request returns. However, docs/architecture/sequencer-dsl.md:286-288 and apps/docs/docs/advanced/sequencer-side-chains.md:68-72 define side chains as request-scoped: the executor drains them before terminal status and keeps the stream open until they settle. Publishing this draft would therefore direct builders to a mechanism that cannot provide the page's central durability promise; this row should reserve after-request work for dispatched runs and describe side chains only as concurrent work within a still-running request.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed against sequencer-dsl.md and Sequencer side chains, and fixed in c3e6aff. The keeps-going row names only dispatcher(). The draft now says .sideChain() runs beside the request, and the request stays open until it settles. Recorded in DECISIONS.md → Decided in review.
Generated by Claude Code
| > On a queue-backed host, such as one using `bullmqWorker`, a delivery into an existing session | ||
| > throws `DispatchRefusedError` with `refused: "external-dispatcher"`. Nothing is enqueued. A |
There was a problem hiding this comment.
Scope the refusal to an external effective dispatcher
This wording makes any host using bullmqWorker sound as though it refuses { id }, but docs/architecture/dispatched-work.md:244-272 defines locality by the effective dispatcher: worker-only installs no dispatcher, so nested dispatch runs in-process and does not trigger external-dispatcher. This affects worker-only BullMQ deployments and contradicts ER-4's more accurate “host that hands work to an external queue” qualification; use that effective-dispatcher condition here and in the channel paragraph instead.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed against dispatched-work.md → "The rule that decides everything", and fixed in c3e6aff. The draft scopes the refusal to hosts whose dispatcher hands work to an external queue: bullmqWorker in colocated or dispatch-only mode. It also says worker-only does not refuse. The same scoping now appears in ER-4, the SPEC teams row, the closure's Input, and PLAN.
Generated by Claude Code
| Remove the `notification` row, and `notification` from the list of known values above it. | ||
| It names cross-flow event subscribers, which don't ship (D3). Drift fix only. |
There was a problem hiding this comment.
Preserve the shipped notification source badge
Removing notification from the documented known-source set is inaccurate while packages/devtool/src/react/components/workspace/request-separator.tsx:57-62 still recognizes it and renders a dedicated “Notification” badge, and packages/core/src/types/auth.ts:14-19 still documents it as known. Because custom adapters may legally continue emitting this source, the proposed edit would make the docs disagree with observable runtime behavior; either retain it with an accurate legacy/custom description or include removal of the shipped recognition in a separately scoped runtime change.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed: core's InboundSource doc and the DevTool badge both still recognize notification. Fixed in c3e6aff. The drift fix now rewords the row and keeps the value. The row no longer calls it cross-flow event subscribers, because no built-in transport emits it. D3's Locks in, its figure, end-state.svg, EVOLUTION and the PLAN seam all changed with it.
Generated by Claude Code
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. |
…ification row reworded, fence scoped to the effective dispatcher - D3: dispatcher() into internal.actions is the shipped cross-flow bus; only FIX-441's .notify / NotificationFlow topic bus is rejected (owner clarification). - The notification Known-sources row is reworded, not removed: core's InboundSource and the DevTool still recognize it. - The keeps-going row names dispatcher() alone; .sideChain() is request-scoped. - The id/key fence follows the effective dispatcher: worker-only does not refuse. - FIX-1641 keeps its block on the closure (every child does); the page never waits for it. Recorded in Decided in review. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GmvuVRtAQQvxJfj4fMVirA
FIX-1643 joins as a child beside FIX-1641: set table, dependency graph, path lane, plan row and seams, ER-6, and the ownership note. It blocks the closure only through the closure rule; the page never waits on it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GmvuVRtAQQvxJfj4fMVirA
|
Answers to the two open questions, recorded.
Generated by Claude Code |
… set, redraw the path past the gate Review of #2394 found two gaps. The owner filed FIX-1644 (folder wake config POC, examples #2374) and FIX-1645 (wake principal plan) as children blocking the closure minutes before #2368 merged, and the set never listed them. And the path figure still drew the gate as now, with the spec in review, while PLAN said the gate had passed. - SPEC: set table, header count, dependency graph and its caption carry both children; "Not doing" names folder wakes and trust-lane runtime. - DECISIONS: why each sits in the set, ownership sentence, end-state POC note, and a history entry. - BUSINESS-RULES: ER-6 covers the folder convention and the plan. - PLAN: path redrawn past the gate with FIX-1644 and FIX-1645 lanes, the canceled FIX-1638 and FIX-1640 lanes dropped to a footnote; issue table, unblock step and two seams. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GmvuVRtAQQvxJfj4fMVirA


{ id }refusal as a table row, or a channel that never answersGoal: a builder who wants a flow to react to things outside a chat (a webhook, a clock, another flow) and to keep working after the request returns can find, from one published page, which existing way to use, what to configure in the flow vs the host vs their infrastructure, and what doesn't work yet on a queue-backed host.
Proved by the closure issue FIX-1642 on one
maincommit; a planted false option on the page must fail the run. Why this goal: SPEC.md.Everything the page leans on already ships. The fence keeps a docs epic from becoming a runtime one.
Why now. The public release puts FSD in front of outside builders, and our own support desk found the queue-host gap (FIX-1634) by doing nothing on BullMQ. Goal 4: document a limitation plainly. The page links existing deploy guides and writes none.
The set: one page (FIX-1639), two children proposed to fold into it (FIX-1638 table, FIX-1640 terms), two POCs beside it (FIX-1641 wake authoring, draft #2369; FIX-1643 subscribe and route, draft #2372), and the closure FIX-1642. As of 2026-09-29: all Backlog; the set table links live Linear state.
One wait, at the gate. The critical path is FIX-1639's spec, the page, then the closure run; FIX-1641 and FIX-1643 block the closure like every child, never the page.
Every rule has one owner, the project's PR-1 included. Dashed cells are where a re-split moves it.
Sign off
Fold the table and the terms into the page, or keep three children? · D1 · open
Plain terms. Your PRD asks for a guide, a settings table and a glossary. They explain the same few features; three writers who never see each other's drafts will explain them three ways.
The trade-off. The figure's first row: one consistent page for one review, at the price of overriding your split and the Architect's "do not merge bodies" note. Everything still ships.
My recommendation. Fold. FIX-1638 and FIX-1640 stay open until you say so.
What would change my mind. You want the table or terms reviewable on their own, for FIX-453 or a design partner.
What being wrong costs. Low: one fold to re-split, before a word is published.
A new page, not a nav change · D2
It comes down to what's missing: a nav entry can point at pages, not supply the table. If wrong: a page that repeats what a sidebar entry would have found.
The event row names only doors that ship · D3
dispatcher({ flowKind, action, session })into the receiver'sinternal.actionsis the cross-flow bus that ships, and the row names it. Only FIX-441's topic bus (.notify/NotificationFlow) stays off: canceled, never exported. If wrong: a reader builds on an API that doesn't exist.Open: D1. Reasoning: DECISIONS.md.
Reviewers · look here
main.epic-wakeleaves the published glossary. The PRD lists it; the outsider rule keeps internal tooling names out ofapps/docs. One line goes to contributor docs instead.Not here: any single issue's approach. Those are the spec PRs.
Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1637 · Project: Framework simplification & cleanup (project spec #2367) · merges after human approval and required checks
How to review this — an epic-spec, not an implementation plan
This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design.
In scope to challenge:
SPEC.md— is this body of work worth doing, and is thegoal the real need at full size, or a smaller one the set could meet while the need stays
unmet? Would the closure issue's check fail if the goal were not met?
That question can only be asked here.
DECISIONS.md— shared surface, naming, sequencing, contracts.BUSINESS-RULES.mdwith no owner, or two.DOCS.md; missing or misleadingpredecessor treatment in conditional
EVOLUTION.md.Out of scope — owned by the individual issue specs:
poc/show shape and scoping, not shippable implementation. Directional evidence, experimental
isolation and absence of secrets/generated dependencies remain in scope.
Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.
Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.
🤖 Generated with Claude Code
https://claude.ai/code/session_01GmvuVRtAQQvxJfj4fMVirA