Skip to content

spec(epic): keeping flows alive, one page from an outside event to work that keeps going (FIX-1637) - #2368

Merged
jhoffner merged 4 commits into
mainfrom
epic/keeping-flows-alive
Sep 29, 2026
Merged

jhoffner merged 4 commits into
mainfrom
epic/keeping-flows-alive

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator
A builder who… Today After this epic
wants a flow to react to an outside service Finds Webhooks; nothing joins it to schedules or to work that keeps going One page walks webhook, schedule, hand-off
wants a flow to run on a clock Reads four pages to learn which parts are theirs One table: flow, host, their scheduler
runs on a queue-backed host (BullMQ) Meets the { id } refusal as a table row, or a channel that never answers Reads it before building, with what works instead
meets wake, dispatch, tick Sees them used, defined nowhere Each defined once
uses Workforce channels and boards Reads 800 lines to tell them apart One section, with links

Goal: 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.

flowchart LR
  N["docs site nav · one main commit"] --> P["the page and the pages it links"]
  P --> F["fixture flow · webhook wake · schedule wake · hand-off"]
  P --> K["every key the page names"]
  P --> Q["BullMQ host · session id vs key"]
  F -->|"work finishes after the request returns"| OK["PASS · the epic's goal is met"]
  K -->|"all resolve to shipped exports"| OK
  Q -->|"refusal matches external-dispatcher"| OK
  C["control · one planted false option"] -.-> K
  K -.->|"under the control"| X["must FAIL · names the claim"]
Loading

Proved by the closure issue FIX-1642 on one main commit; a planted false option on the page must fail the run. Why this goal: SPEC.md.

What's in the box: one published page with the path, the id vs key fence, the flow / host / ops table and three terms. Linked, not rewritten: the reference pages and scheduler guides. Not built: the id fix, a Heartbeats noun, new L1 nouns, Relay, deploy how-tos, live UI

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.

The path: this spec in review at the now line; FIX-1639 spec then page after the gate; FIX-1638 and FIX-1640 pending D1; FIX-1641's and FIX-1643's examples in review; the closure plan beside FIX-1639 and its run after the page merges

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.

Who owns what: eight rules by FIX-1639, FIX-1638, FIX-1640 and the closure; FIX-1639 owns all but the proof, dashed cells show where a re-split moves ownership

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

One page from one writer, recommended, beside three children as the PRD split them. Decides it: five features described once, not three ways. Price: overriding the owner's split. Tie: every deliverable ships

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

A new page that links the rest, chosen, beside a nav change only. Decides it: three pieces no page has. Price: one more guide to keep true

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

Only shipped doors, chosen, with dispatcher as the cross-flow bus, beside FIX-441's topic bus. Decides it: notify and NotificationFlow aren't exported. Price: no one-to-many topic

dispatcher({ flowKind, action, session }) into the receiver's internal.actions is 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

  • Is a page needed at all? The kill line says a nav change wins if the pages already give the path. D2 says three pieces are missing; check them against main.
  • epic-wake leaves the published glossary. The PRD lists it; the outsider rule keeps internal tooling names out of apps/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:

  • The objective and the goal in SPEC.md — is this body of work worth doing, and is the
    goal 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?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in BUSINESS-RULES.md with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.
  • Shared promises and publication ownership in DOCS.md; missing or misleading
    predecessor treatment in conditional EVOLUTION.md.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's 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

…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
@vercel

vercel Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 29, 2026 1:55pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 29, 2026 1:55pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 29, 2026 1:55pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 29, 2026

Copy link
Copy Markdown

FIX-1637

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

Copy link
Copy Markdown
Collaborator Author

Process guards is red, but not because of this PR.

  • Failing step: scripts/validate-spec-folder.mjs: "spec/ … must hold nothing but README.md. Found: spec/_projects".
  • Cause: main at ba29a29 is the merge of project(public-launch): Public Launch — the project-spec (never merged) #2359 (project/public-launch). That merge put spec/_projects/public-launch/ on main. Project specs are meant to live only on never-merged project/* branches.
  • Proof it's main, not this PR:
    • main's own Process guards run at ba29a29 failed (run 36568591848).
    • Running the guard on a git archive origin/main tree exits 1 with the same message.
    • This branch only adds specs/epics/FIX-1637/, and all six guard scripts pass on its own tree.
  • Fix: none exists yet. The proposed patch removes spec/_projects/public-launch/ from main. The content survives on project/public-launch (bd55748). That fix is outside this epic's diff, so it isn't pushed here. It's with the owner to decide.

Generated by Claude Code

@jhoffner
jhoffner marked this pull request as ready for review September 29, 2026 12:55

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1637/SPEC.md Outdated
| [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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread specs/epics/FIX-1637/SPEC.md Outdated

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread specs/epics/FIX-1637/DECISIONS.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

![A new page that links the rest, chosen, beside a nav change only. Decides it: three pieces no page has, which a nav entry cannot supply. Price: one more guide beside Work that outlives the turn. Locks in a page that links rather than repeats. Flips if the missing pieces fit an existing page](figures/d2-new-page.svg)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator Author

Owner clarification (Jake via Architect) — tighten D3 wording

If any D3 / PR-body / figure copy still reads as “no cross-flow bus,” rewrite to:

  • Supported (shipped cross-flow delivery): dispatcher({ flowKind, action, session }) into the receiver’s internal.actions is the cross-flow bus. Keep naming it on the event row / path.
  • Invent-kill / not-shipped: FIX-441 .notify / NotificationFlow topic/notification bus only (canceled; never exported).

Do not reopen FIX-441. Soft-relate only.

Please update DECISIONS.md D3 (and any PR summary / figure alts that say “beside the cross-flow event bus” without that split) so a reader cannot confuse invent-killing the topic bus with invent-killing dispatcher.

Linear: stamped on FIX-1637 / FIX-1641; soft-related FIX-441.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread specs/epics/FIX-1637/DOCS.md Outdated
> | **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` |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread specs/epics/FIX-1637/DOCS.md Outdated
Comment on lines +39 to +40
> 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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread specs/epics/FIX-1637/DOCS.md Outdated
Comment on lines +98 to +99
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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-29T12:59:27.328205Z 0ac4837 Draft marked ready
ℹ️ 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" or "@codex security review".

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
@jhoffner
jhoffner merged commit 2b6d67e into main Sep 29, 2026
11 of 12 checks passed

Copy link
Copy Markdown
Collaborator Author

Answers to the two open questions, recorded.

  • Process guards red on main (comment). The owner decided to fix main. Draft #2392 removes spec/_projects/public-launch/ from main, and the content stays on project/public-launch. The fix is outside this epic, so the epic spec only notes that it's in progress.
  • D1. The owner chose to fold, as recommended. FIX-1638 and FIX-1640 become sections of FIX-1639's page. Both are canceled and no longer block FIX-1642. Follow-up #2394 records D1 as decided and removes the re-split ownership cells. This PR stays as it merged.

Generated by Claude Code

jhoffner pushed a commit that referenced this pull request Sep 29, 2026
… 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants