Skip to content

refactor: name the middle execution tier a side chain (FIX-766) - #1307

Merged
jhoffner merged 19 commits into
mainfrom
fix/FIX-766
Aug 15, 2026
Merged

jhoffner merged 19 commits into
mainfrom
fix/FIX-766

Conversation

@jhoffner

@jhoffner jhoffner commented Aug 14, 2026 •

Copy link
Copy Markdown
Collaborator

The framework has three places work can run: in the turn, alongside the turn, and outliving the turn. The middle one had no stable name — it was work in the methods you called, background in one of its own methods, and Side Chains in the published page that taught it. And background was doing double duty elsewhere: it titles the page for the third tier, and the guide names it the umbrella over all three at once ("background work is the name all of them go by").

Nothing is published yet, so this is a rename. After the first npm publish it becomes a deprecation cycle across five packages.

What this does

Names the middle tier side chain everywhere a developer can see it, so the tiers read main → side chain → detached and background goes back to meaning the umbrella. .work() → .sideChain(), .workIf() → .sideChainIf(), .waitForWork() → .waitForSideChain(), .forEachBackground() → .forEachSideChain(), plus the values you read back, the published types in core / engine / testing, the internal dispatch discriminator, the comment/JSDoc layer, the user-visible pool error strings, and the DevTool badge (BG → SC).

It also deletes the flow-level work config — WorkConfig and the work member on four flow interfaces declared four lifecycle hooks that nothing ever invoked. Removed rather than renamed, so the canonical name doesn't inherit a dead contract.

Completeness is a CI check, not a claim: scripts/validate-side-chain-vocabulary.mjs runs inside pnpm typecheck and fails if the retired vocabulary reappears. On origin/main it reports 407 sites across 60 files and exits 1; on this branch it exits 0.

What's asked of you

The persisted question was NOT settled by the spec, and this PR previously implied it was

This is the correction most worth your attention, because a reader who trusts "decision 2 settled it" will not check.

The spec decided two persisted surfaces. Decision 2 argued "no shim" for provenance.phase (a value nothing reads to decide anything) and the block path (an identifier whose alias would land in every prefix comparison in the path grammar). Both arguments are sound for those two.

The rename touched five. "Persisted surface" was never enumerated as a class, so three more travelled through as ordinary identifiers — which in source is exactly what they look like. Two were found by reviewers, not by me, and my first attempt at enumerating them was itself too narrow: scoped to state-schema keys and patchState-style writers, it found one and I reported "no fourth". It structurally could not see a persisted item field.

Surface Carrier Read to decide anything? Disposition
provenance.phase value "work" → "sideChain" persisted item value No — DevTool badge only No shim — spec decision 2
block path …/work[n] → …/sideChain[n] persisted identifier (replay-log key) Yes No shim — spec decision 2; accepted re-execution, pinned by a characterization test
ItemProvenance.workGroupId → sideChainGroupId persisted item field No — every consumer is an identity-propagating write Safe unshimmed
StatusItem.backgroundTasks → sideChainTasks persisted item field Yes — the DevTool drops the row entirely Dual-read (found in review)
reportedBackgroundTaskIds → reportedSideChainTaskIds persisted session state Yes — re-announces finished jobs Dual-read (found in review)

Method: parsed origin/main with ts-morph for every property declaration of the 72 renamed names, classified by carrier — contracts/src/items (written to request_items / trace_events), anything under a *StateSchema, anything under stores/persistence/durability. Its stated limit: it enumerates renamed keys, so a renamed value like provenance.phase is invisible to it and is in the table only because the spec named it. If a sixth surface exists, it is most likely another value.

Both dual-reads are read-side only — no write path changes, decision 2 not reopened. If you'd rather either stayed unshimmed on pre-publish grounds, say so; it should be a stated decision either way.

For later, not this PR

pnpm typecheck doesn't cover test files in several packages (include: ["src/**/*"]). Five of this change's near-misses were stale fixtures the compiler never read. Worth its own issue; not filed.

Parts worth reviewing closely

Reviewer hat from here — a product read can stop above.

  1. The guard has been wrong ten times, in both directions — that is the honest count. Five holes found during implementation; review found a sixth (the "background" dispatch discriminator), a seventh (the wrapped-argument comparison, inside the rule written to close the second), and a tenth (PATH_OP_ARG_INDEX assumed one arity for two builders, so a direct blockPathSegment("work", i) produced nothing — while blockPathSegment was named in the guarded list). Review also found it wrong the other way twice: banning the work token, then still matching any member or object key. It is now a closed denylist scoped by what a name belongs to. What I'd most like checked is whether an eleventh is out there, in either direction.
  2. packages/engine/test/side-chain-rename-continuation.test.ts — the assertion direction. It asserts the completed child does re-run. Inverting it would look like a bug fix and is only satisfiable by adding the block-path alias decision 2 rejects. The second test is the control.
  3. Prose is the weakest surface here, and three review rounds have proved it. The identifier sweep has control fixtures; the prose sweep has none. Ten of 44 phrase rewrites were tier errors (comments about workstreams and detached children where background is the correct umbrella word). A later round found eight more of a different class — the retired tier word surviving in ordinary English beside correctly-renamed code, including two on the very page this rename is named after. All fixed by hand. I am not claiming prose is now complete: the mechanical shapes are greppable and clean, and the residual class is precisely the one no grep can express.

My own weak spot, measured. The closed denylist trades "bans correct code" for "silently permits a retired name nobody listed". Audited against what the codemod renamed: 45 were missing; eleven were framework source and are now refused, 34 are test locals excluded on purpose. A test audits the list going forward.


Fixes FIX-766 · Spec document · Spec PR #1287 (closed, approved) · Goal verdict: §10 documents that no goal check applies — this is a rename with no behavioural delta, and the evidence is the existing side-chain suites (abort signalling, pool draining, crash-recovery replay) passing unchanged except for identifiers.

How to review this (spec-backed change)

This change has an approved spec. The approach and every §6 Decision were signed off before implementation, so review the code against that direction rather than re-arguing it.

With one caveat this PR has demonstrated twice: an approved spec settles the questions it asked. Decision 2 answered "shim or not" for two persisted surfaces and was silent on the class; three more existed. Treat a §6 decision as binding on its subject, not as coverage of everything adjacent.

The spec is the Linear document linked above. The spec file is not in this diff — it lives on the retained spec/FIX-766 branch, never on main (BP-037).

Engineering calls (made, not asked)
  • The guard denies a closed set of retired names, scoped by what the name belongs to. Distinctive names refused anywhere. work refused only when called or declared as a method. Contract fields (workGroupId, backgroundTasks, workResults) refused only where the contract is declared. Stated under-reach: a read of a contract field, and a declaration outside those packages, are not caught — under-reaching with a written boundary beats red-lighting every domain model.
  • Each path builder maps to its own op-argument index. One shared constant was right for childBlockPath (op at 2) and wrong for blockPathSegment (op at 0). Naming a builder as guarded is a claim; the index is what makes it true. The other blockPath* helpers take no tier op and are deliberately absent.
  • A segment-literal rule covers the route past the builders (extendBlockPath(p, "work[0]")). Added on derivation; it immediately found two stale "work[0]" sites this rename had left in sequencer-kernel.test.ts.
  • The pre-filter is derived from the denylist, so adding a name widens it automatically. 2,531 files parsed → 655; 8.5s → 4.2s. --parity re-runs with the filter off and diffs; passes on this branch and on origin/main, proving none of the 407 findings are hidden.
  • A deliberate, unescapable over-reach, now documented: a phase/scope field valued "work" is denied repository-wide regardless of local meaning. Keying it to declared carriers needs type information absent at those positions and would go green on the untypechecked files the rule exists for. There is no per-site escape hatch — EXEMPT_FILES is pinned by assertion — so a legitimate future use is a hard CI block requiring a script edit.
  • The exemption list closes at two, both rename-boundary characterization tests, one per persisted surface crossed. Pinned by name.
  • The status count is dual-read through one shared helper, not inlined at three call sites.
  • runtime.workTasks became pendingSideChainTasks — sideChainTasks is a count on the persisted contract; this is an in-memory array, both in sequencer.ts.
  • Prose is swept, unguarded, and manually re-audited. Coverage boundary: comments and docs can regress without failing CI.
  • User-visible error strings are surface, not prose. "work pool drain aborted" → "side-chain pool drain aborted".
  • background(block) was deleted from a method table rather than renamed — never a DSL method, a pre-existing doc error.
  • Bump: minor across all five publishable packages (BP-022).
  • Retitled server/background-work.md to "Detached work", slug kept. Zero anchors newly broken.

Declined, with reasons: extracting a shared ts-morph bootstrap (two guards is not a pattern), committing a one-shot codemod (a recipe for a rewrite nobody will run rots without failing), and narrowing the scope/phase value rules to typed carriers (would go green on exactly the untypechecked files the rule was written for — the honest half, the undocumented cost, was taken instead).

Verification
# origin/main, with this branch's final guard
$ node scripts/validate-side-chain-vocabulary.mjs
[side-chain-vocabulary] 407 retired tier-2 name(s) across 60 file(s).   EXIT=1
$ node scripts/validate-side-chain-vocabulary.mjs --parity
[side-chain-vocabulary] parity OK — the pre-filter removes no findings.

# this branch
[side-chain-vocabulary] OK — no retired tier-2 names survive.

Mutation-tested. Six of these initially survived across the rounds and are now covered — the reason for re-running the table after every change rather than trusting it:

Mutation Result
Revert the wrapped-argument fix 1 failed / 39 passed
Disable the conditional-ancestor rule 1 failed / 39 passed
Re-broaden E1 to a token denylist 9 failed / 31 passed
Callable rule drops the call requirement 1 failed / 39 passed
Contract-field rule ignores the owning package 2 failed / 38 passed
E2 union fires without a named holder 1 failed / 39 passed
blockPathSegment index back to the shared 2 1 failed / 39 passed
Segment-literal rule disabled 1 failed / 39 passed
Drop one name from the closed set 1 failed / 39 passed
Guard restored 40 passed
Continuation test: path rewrite made a no-op expected 1 to be 2
DevTool badge: label reverted to BG expected [ 'BG', 'BG' ] to equal [ 'SC', 'SC' ]
Status-count dual-read: legacy branch dropped 3 failed / 6 passed
State-key dual-read: legacy branch dropped 2 failed / 3 passed

Full runs on this branch: pnpm typecheck 60/60 + all three validators · pnpm test 57/57 tasks, exit 0 · pnpm docs:build clean under onBrokenLinks: "throw" · core 1988, engine 2295, devtool 256, contracts 48, kitchen-sink 90, integration-tests 66.

labs/trading-desk — closed with evidence, not asserted. It failed three times, always as portfolio-backing.spec.ts "Test timed out in 5000ms". A clean full-suite baseline on origin/main is 57/57, exit 0, with that test at 3.30s against a 5s budget — ~1.7s of headroom. This branch's clean run is also 57/57 with the same test at 3.63s. Every failure occurred in runs where a second suite of mine was competing for CPU. git diff --name-only origin/main..HEAD -- labs/ is empty and the package references none of the renamed vocabulary. Being precise: this is not a reproduction of the flake on main; it establishes that both branches pass clean and the failures track load, not the diff.

One artifact worth naming: npx vitest run --root packages/engine from the repo root fails a test that pnpm --filter … test passes — it resolves a fixture against process.cwd(). Use the filter form.

Scope, and how each number was derived

Re-derived against main at 15bf350 rather than trusted, because the spec's counts predate FIX-1001, which edits the two files carrying most of the sites.

Surface Spec Re-derived Method
DSL verbs (calls + declarations) 124 129 AST, property-access name + method/property declarations
provenance.phase value "work" 29 29 AST, literal bound to phase
workGroupId 6 6 AST identifier
StatusItem.backgroundTasks 27 27 AST identifier
FlowErrorScope's "work" 1 1 AST, literal-type union member
Runtime path literals 6 6 AST, callee + argument position
Markdown references 365 377 regex over git ls-files '*.md'

Markdown, re-derived across eight reference shapes after review found four method tables missed. The gap was a backticked verb with an arglist and no leading dot — `work(block)` — falling between the .work( rule and the bare-backticked rule. .agents/ was in the sweep's roots all along (52 tracked files); the miss was the shape. All eight shapes are now zero except this change's own before/after migration table.

Prose, in two classes, both found by review rather than by rule: 10 of 44 phrase rewrites were tier errors (tier-3 text rewritten as side chain), and 8 further sites were the retired tier word surviving in English beside renamed code. All fixed. The mechanical shapes are clean and greppable; the residual risk is the class no grep expresses.

Deliberate non-renames, each with a control fixture asserting zero: Workstream*, the priorWork family, onBackgroundWork and its plumbing, CSS background*, framework/network/teamwork, scheduleWork/workQueue/doWork, a "idle" | "work" status union, work as a variable, as the object of an access, and as a data field, and backgroundTasks declared outside the contract packages.


Generated by Claude Code


Note

High Risk
Breaking API rename across five packages plus replay-path key changes that can double-run in-flight side chains after deploy; persisted-field shims reduce duplicate UI/status noise but path migration has no back-compat.

Overview
FIX-766 standardizes vocabulary so the three execution tiers read main → side chain → detached, and background again means the umbrella over all of them.

Sequencer DSL (breaking, minor bumps): .work() / .workIf() / .waitForWork() / .forEachBackground() become .sideChain() / .sideChainIf() / .waitForSideChain() / .forEachSideChain(). Related runtime types move with them (RequestSideChainPool*, composeSideChainSignal, testing SideChainTrace / sideChainResults, DevTool badge SC).

Observable contract renames: provenance.phase is "sideChain" (was "work"), workGroupId → sideChainGroupId, StatusItem.backgroundTasks → sideChainTasks, FlowErrorScope "work" → "sideChain".

Removed: flow-level WorkConfig / work lifecycle hooks that were never invoked.

Migration / durability: Replay memoization keys use path segments …/sideChain[n] instead of …/work[n] — requests in flight across deploy may re-run completed side-chain children once (no migration). Kitchen-sink dual-reads legacy session key reportedBackgroundTaskIds when deciding which background jobs were already announced.

Enforcement: pnpm typecheck runs scripts/validate-side-chain-vocabulary.mjs so retired tier-2 names cannot creep back in.

Docs, agent skills, changesets, and kitchen-sink pipelines are updated to the new names end-to-end.

Reviewed by Cursor Bugbot for commit 354e6b6. Configure here.

claude added 6 commits August 14, 2026 23:10
The tier that runs alongside a turn had three names — `work` in the DSL,
`background` in one of its own methods, and "side chain" in the docs — and
`background` also named the third tier and the umbrella over all three.
Settle on `sideChain` everywhere a developer can see it, which frees
`background` back to the umbrella the guides already say it is.

Covers all four encodings of the concept: identifiers, `"work"` as a
string-literal union member (`ItemProvenance.phase`, `FlowErrorScope`),
`background` naming tier 2 (`composeBackgroundSignal`), and the runtime
path literals that become block-path segments — the last of which moves a
persisted replay-log key, so a side chain completed before this change and
continued after it runs a second time. Accepted, pre-publish, and pinned by
a characterization test.

Deletes the flow-level `work` config (`WorkConfig` and the `work` member on
four flow interfaces): four lifecycle hooks nothing ever invoked, removed
rather than renamed so the canonical name does not inherit a dead contract.

Completeness is enforced by scripts/validate-side-chain-vocabulary.mjs,
wired into `pnpm typecheck`. It failed on main before this change and its
rules had to be widened four times during implementation — each time
something else (typecheck, a red suite) caught what it had missed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
… not see (FIX-766)

Eight backticked `.work` / `work` references in doc comments — including
two in `contracts/src/items/types.ts`, which is published contract
documentation. A code span is prose, so no AST rule reached them; found by
grepping the retired name rather than by re-reading the diff.

Renaming inside three pending changeset fragments also pulled them into
validate-changeset-refs' scope (it checks fragments a branch edits). Their
issue ids were in the filename or the authoring commit but not the body,
which is where the rule wants them, so each now names its issue.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
… (FIX-766)

A tier threaded through a helper the E2 rules do not know by name, and the
tracked-files-only walk. Both are real and both are deliberate — a wider
argument rule flags correct code, and the git-ls-files walk is what keeps
worktree copies out of the count. Stated so nobody reads green as proof.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
It runs to the gate's suspension; the interrupt flip is the test's own
setup step, and calling it runToInterrupted described the caller's next
line rather than the helper's.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
…(FIX-766)

An edit left it orphaned above effectiveParent's own docblock, documenting
nothing, and still claiming three accepted positions after the count reached
five. It now lists all five and says which check caught each one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
…tooltip (FIX-766)

The badge label went BG -> SC, and nothing asserted the text — only the
title behind it. Reverting the label to BG now fails the suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
@linear-code

linear-code Bot commented Aug 14, 2026

Copy link
Copy Markdown

FIX-766

@greptile-apps

greptile-apps Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Too many files changed for review (159 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

@vercel

vercel Bot commented Aug 14, 2026 •

Copy link
Copy Markdown

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

3 Skipped Deployments
Project Deployment Actions Updated (UTC)
flow-state-dev-docs Ignored Ignored Aug 15, 2026 2:27am
flow-state-dev-kitchen-sink Ignored Ignored Aug 15, 2026 2:27am
flow-state-dev-ui Ignored Ignored Preview Aug 15, 2026 2:27am

@cursor

cursor Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_48b45dea-1de1-4dc0-886e-e5efeda4aafc)

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

Simplify review — FIX-766 side-chain rename

Verdict: The hard rename (no aliases, delete dead WorkConfig, replay-path characterization test) is the right call for a pre-publish framework. I would not recommend reverting to alias-based migration or BP-030 path shims — the accepted in-flight re-execution cost is documented honestly and the continuation test makes it attributable.

The main question is whether the guard machinery is the simplest way to keep the rename complete. My read: mostly yes, with two caveats.

Where the approach is sound

  • Encoding-based AST guard matches the repo's existing pattern (validate-updater-purity.mjs + fixture tests). A regex or ESLint id-denylist would not catch E2 conditional assignments, E4 path literals, or tokenization false positives (Workstream, framework). The mutation table in the PR description is convincing.
  • Runtime behavior is rename-only — no perf regressions in the pool, sequencer dispatch, or drain paths.
  • Deleting WorkConfig is a genuine simplification, not scope creep.
  • Concept predicates over name lists for allowlists (background+work = umbrella) is the right shape; a fixed exemption list would rot.

Where complexity crept in (and simpler alternatives)

  1. The guard's blind spot is now the main residual risk. Prose (comments, JSDoc, error strings) is deliberately unscanned — fair, but it means the rename is incomplete in the layer developers read most. Several runtime files still teach "work" phase, work() shapes, and "work pool" errors while the types say sideChain. That's the dual-vocabulary problem this PR exists to kill, just in comments instead of identifiers. Simpler fix than extending the guard: a one-time comment/JSDoc sweep in packages/core + packages/engine runtime sources before merge (or a lightweight prose regex pass like validate-model-strings.mjs, scoped to tier-2 literals only).

  2. Internal DSL plumbing still says background. SideChainCallShape + .sideChain() public API, but resolveCallShape(..., "background") and the "background" overload discriminator are unchanged. E3 doesn't flag string literals, so this is invisible to the guard. Renaming the pattern to "sideChain" is a small, high-coherence win — no API surface change.

  3. 524-line guard + 85-line header is heavy but proportional to the failure mode (seven scope corrections during implementation). If this becomes a recurring pattern, consider extracting shared ts-morph bootstrap from validate-updater-purity.mjs rather than growing two independent monoliths. Not blocking.

  4. No committed codemod — scripts/codemod/rename-sequencer-then-to-step.ts sets precedent for large DSL renames. Even post-merge, a one-shot rename-work-to-side-chain.ts would document the mechanical rewrite recipe for the next person. Optional follow-up.

  5. Integration scenario filenames (work-pool-fix554.test.ts, work-pool-signal-isolation.test.ts) still use tier-2 vocabulary in names/describe strings while content was updated. Low priority, but grep hygiene matters for a vocabulary rename.

What I would not change

  • Adding .work() deprecation aliases — opposite of the goal.
  • Moving the guard to the zero-install CI guards job — it needs ts-morph; typecheck hook is correct.
  • Re-litigating replay-path re-execution — decision 2 is settled and tested.

Suggested pre-merge nits (optional, not blocking)

Item Effort
Comment/JSDoc sweep ("work" phase, work() shapes, "work pool" errors) Small
Rename resolveCallShape pattern "background" → "sideChain" Small
Merge duplicate JSDoc before composeSideChainSignal (lines 703–711 orphan) Trivial
Drop unnecessary cast in composeSideChainSignal (_requestSideChainSignal is already on BlockContext) Trivial
Pin exemptFiles in side-chain-vocabulary-check.test.ts (sibling guards do this) Trivial

Bottom line: Direction is right; the guard earns its place. The remaining simplification is finishing the rename in prose and internal plumbing, not re-architecting. Happy to approve once the comment/pattern nits are addressed, but they're small enough I'd also accept as fast follow-ups if you want this landed.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/core/src/types/block.ts Outdated
@@ -514,7 +514,7 @@ export interface BlockContext<
*/
taskId?: string;
/** Execution phase — "work" for background scopes, "main" otherwise. */

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.

Stale JSDoc after the rename — still says "work" for background scopes while the type is "sideChain". The guard intentionally skips prose, so this won't fail CI. Worth fixing in the same pass as other comment drift (error-capture.ts JSDoc, sequencer.ts inline comments).

Comment thread packages/core/src/blocks/sequencer.ts Outdated
arg2?: BlockDefinition<any, any> | SideChainOptions,
arg3?: SideChainOptions
): SequencerDefinition<TInput, TOutput, TStateSchema> {
// Shapes: work(block) | work(connector, block) | work(block, options) |

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.

Comment still documents work(block) shapes and "work" phase a few lines below, while the method is now sideChain. Small, but it's exactly the three-name confusion this epic targets — just relocated to comments.

Comment thread packages/core/src/blocks/sequencer.ts Outdated
): SequencerDefinition<TInput, TOutput, TStateSchema> {
// Shapes: work(block) | work(connector, block) | work(block, options) |
// work(connector, block, options).
const shape = resolveCallShape([arg1, arg2, arg3], "background");

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.

Internal discriminator still "background" while the public surface is sideChain / SideChainCallShape. E3 doesn't scan string literals, so the guard is green here. Renaming the pattern literal to "sideChain" (and updating arg-shapes.ts overloads + tests) would close the last dual-vocabulary pocket in the DSL implementation — no API change.

Comment thread packages/core/src/blocks/sequencer.ts Outdated
@@ -701,19 +701,19 @@ function createRuntimeState(): SequencerRuntimeState {
}

/**

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.

Looks like an orphan JSDoc block left over from the backgroundTaskCtx → sideChainTaskCtx rename — the block above describes sideChainTaskCtx, then a second /** opens for composeSideChainSignal. Merge into one doc block?

Comment thread packages/core/src/blocks/sequencer.ts Outdated
): AbortSignal | undefined {
const background = (ctx as { _requestBackgroundSignal?: AbortSignal })
._requestBackgroundSignal;
const background = (ctx as { _requestSideChainSignal?: AbortSignal })

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.

Unnecessary cast — BlockContext already declares _requestSideChainSignal (see block.ts). sideChainTaskCtx reads it without a cast on the next function. Drop the cast for consistency.

| { status: "rejected"; meta: RequestSideChainTaskMeta; reason: unknown }
>;

if (signal === undefined) {

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.

Error string still says "work pool drain aborted" (and the module header still says "background work pool"). Developers hitting this at runtime will see the retired vocabulary. Align with side-chain naming?

* only one that changes a PERSISTED key, because the op name becomes a block
* path segment and the path keys the replay log.
*
* **Known gaps — not caught, stated so nobody assumes coverage:**

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.

The documented prose gap is the main residual risk for a vocabulary rename PR. The identifier guard is strong; the comment layer is not guarded at all. If a full prose scan feels too broad, even a targeted pass over packages/*/src/**/*.ts comment nodes for "work" / tier-2 background literals would catch the drift that's already present in runtime files.

@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: bb38cb820d

ℹ️ 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 on lines +164 to +167
if (!tokens.includes("work")) return false;
if (isUmbrellaName(tokens)) return false;
if (isPriorWorkName(tokens)) return false;
return true;

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 Restrict the guard to side-chain identifiers

The new pnpm typecheck gate rejects every identifier containing a standalone work token, even when it has nothing to do with side chains. For example, scheduleWork and workQueue both produce E1 findings, while an unrelated union such as "idle" | "work" is similarly rejected by E2. Any future task, queue, or domain code using this ordinary term will therefore fail CI until it is misleadingly renamed or added to an ever-growing allowlist; constrain the rules to the retired tier APIs and semantic positions instead.

Useful? React with 👍 / 👎.

Comment on lines +281 to +282
if (Node.isCallExpression(parent) && parent.getArguments().includes(literal)) {
if (/phase|provenance/i.test(parent.getExpression().getText())) return true;

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 wrapped arguments when checking builders

When the retired value is wrapped, as in makeProvenance(id, "work" as const), effectiveParent() climbs to the call expression but getArguments().includes(literal) still compares its arguments with the inner string node, so the check returns false; the equivalent unwrapped call is detected. Because the comment identifies test fixtures outside package typechecks as a primary reason for this rule, this hole lets exactly those stale phase values pass the new completeness gate. Compare against the effective wrapped argument or test whether an argument contains the literal.

Useful? React with 👍 / 👎.

…FIX-766)

Review found the check over-reaching in the direction its own PR description
warned about. `carriesRetiredTierToken` banned any identifier whose camel-split
contained `work`, so `scheduleWork`, `workQueue` and a `"idle" | "work"` status
union all failed `pnpm typecheck` — and the only exits were to rename correct
code misleadingly or grow an allowlist. A gate that red-lights correct code is
the dangerous direction.

Deny by name, allow by concept. The asymmetry is what makes it work: the set of
names legitimately containing these words is open-ended and must be judged by
concept, while the set of RETIRED names is frozen — nothing is ever added to a
vocabulary just retired — so listing them cannot rot. Names that are also
ordinary English (`work`, `backgroundTasks`) are refused only in MEMBER
position, where they are unambiguously the API rather than somebody's variable.

Also closes a seventh hole, in the rule written to close the second: the
call-argument check compared `getArguments()` against the bare literal, but the
list holds the wrapper, so `makeProvenance(id, "work" as const)` passed. It
defeated the rule in exactly the case it was written for — a wrapped literal in
a fixture the compiler never sees, because several packages compile only
`src/**`.

Six mutations, each shown to kill a test; two of them (member-object position,
unnamed union holder) initially survived and are now covered.

On origin/main the check reports 361 sites across 59 files and exits 1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

Both reviews addressed in 6ed2ff0. The most useful finding is the one I'd asked for and the one I didn't.

I asked whether a sixth encoding was out there. Cursor found it; Codex then found a seventh, and separately found the guard wrong in the opposite direction. All three are fixed, and the PR description now carries the real count rather than a renumbered one.

Taken

The "background" dispatch discriminator (cursor #2) — resolveCallShape(args, "background") and its overload are now "sideChain". Public API said .sideChain() while the internals still dispatched on the retired word, and E3 can't see string literals so the guard was blind to it. resolveCallShape is exported from no package index, so no API surface moves. arg-shapes.test.ts moved with it — and notably pnpm typecheck did not catch the stale test, because core's tsconfig is include: ["src/**/*"] too. That's now four near-misses from the same gap.

The seventh hole (codex #2) — you're right, and the detail that makes it worth calling out is where it was: the rule written to close the as const gap compared parent.getArguments() against the bare literal, but the argument list holds the wrapper. So makeProvenance(id, "work" as const) passed. It defeated the rule in exactly the intersection the rule was written for — a wrapped literal in a fixture the compiler never typechecks. effectiveParent now returns the outermost wrapper and the comparison uses it. Fixture added for the wrapped form; reverting the fix fails it.

E1 over-reach (codex #1) — taken as stated, including the framing. The description argued that a false positive "tells someone to rename correct code to get green, which is the dangerous direction for a gate", and then shipped a token denylist with that property: scheduleWork, workQueue and type Status = "idle" | "work" all failed CI. It is now a closed denylist of retired names. The asymmetry is the part worth keeping in mind — cursor's "a fixed list would rot" is true of the allowlist, whose membership grows with the codebase, and false of the denylist, because nothing is ever added to a vocabulary that has just been retired. Names that are also ordinary English (work, backgroundTasks, workGroupId, workResults) are refused only in member position, so pipeline.work(b) fails and const work = 3 / work.id don't.

Both properties are pinned by fixtures: adding scheduleWork doesn't fail CI, reintroducing .work() does. Re-broadening E1 to a token rule kills 9 tests.

Prose (cursor #1) — split, because the two halves have different stakes. Error strings are surface: new Error("work pool drain aborted") → "side-chain pool drain aborted"; a developer meeting the retired vocabulary in a runtime error is being taught it by the framework. Comments and JSDoc in core + engine runtime sources are swept (44 lines, 17 files). The guard is deliberately not extended to prose — a textual rule over comments is where false positives live and this runs inside pnpm typecheck — so the PR now states the boundary outright: prose is swept, unguarded, and can regress without failing CI.

Worth flagging that the sweep got the tier boundary wrong four times before I caught it: workstream-routes.ts, a detached-request comment, and two dispose-path comments are all tier three, where background is the correct umbrella word. Reverted. block.ts and history.ts genuinely are tier 2 and were kept. Markdown was already swept in the first round and wasn't re-touched.

Nits — scenario files renamed to side-chain-pool-*.test.ts with their describe strings; the orphaned JSDoc moved down to sideChainTaskCtx, which it actually documents and which had none; the cast dropped; exemptFiles pinned the way the sibling guard pins its own.

Declined, with reasons

Shared ts-morph bootstrap — two guards isn't a pattern. The seam is better drawn when a third arrives and shows what's actually common, rather than guessed from a sample of two.

A committed codemod — the rename is done and won't run again. A recipe for a rewrite nobody will execute is documentation with a build step, and it rots without anything failing.

Verification

Six mutations on the guard, each shown to kill a test — two initially survived (member-object position, unnamed union holder) and are now covered, which is the argument for running the table rather than trusting it. pnpm typecheck 60/60 + all three validators; pnpm test 57/57 tasks, exit 0; pnpm docs:build clean under onBrokenLinks: "throw". On origin/main the check now reports 361 sites and exits 1 — down from the token version's 642, and that drop is the over-reach coming out.

The remaining weak spot, stated plainly: the closed denylist is only as good as its membership. The failure mode has moved from "bans correct code" to "silently permits one retired name I forgot to list", which is quieter and is the thing I'd most like a third pair of eyes on.


Generated by Claude Code


Generated by Claude Code

…FIX-766)

Auditing the list against what the codemod actually renamed found 45 retired
names missing from it. That is the failure mode the closed-set design trades
for: it stops banning correct code, and starts silently permitting a retired
name nobody remembered to list.

Eleven of the 45 are framework surface and are now refused — the sequencer's
internal helpers and constants (`dispatchWorkTask`, `runBackground`,
`backgroundTaskCtx`, `backgroundSignalOverride`, `DEFAULT_BACKGROUND_CONCURRENCY`),
the shape types (`WorkOptions`, `WorkResult`, `RunBackgroundResult`), the test
harness's `buildWorkTraces`, the engine's `backgroundController`, and the
DevTool's `BackgroundBadge`.

The other 34 stay out on purpose, and the file says so: they are test locals
and fixture names (`slowWork`, `bgWork`, `backgroundProbe`), plus names that
read as the umbrella (`isBackground`, `backgroundTask`). Listing those by hand
would re-create the over-reach this list exists to undo. The line is: refused
when it named the tier AND lived in framework source.

A test now audits the list against the surfaces the rename moved, so a gap
shows up as a red suite rather than as a silent pass later. Dropping one entry
fails it.

On origin/main the check now reports 407 sites across 60 files and exits 1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

@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: 51b29278ee

ℹ️ 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".

// the settle happens in the child, whose stream is its own.
sessionStateSchema: z.object({
reportedBackgroundTaskIds: z.array(z.string()).default([]),
reportedSideChainTaskIds: z.array(z.string()).default([]),

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 durable acknowledgement key

For sessions created before this deploy, the durable state contains reportedBackgroundTaskIds, while the new schema reads only reportedSideChainTaskIds and defaults it to an empty array. The next turn therefore classifies every previously acknowledged completed or errored ledger row as unreported and announces the old results again; preserve the domain key or dual-read and migrate the old value.

Useful? React with 👍 / 👎.

Comment thread package.json
"build": "turbo run build && pnpm build:assets",
"build:assets": "pnpm --filter @flow-state-dev/devtool build:assets",
"typecheck": "turbo run typecheck && node scripts/validate-package-boundaries.mjs && node scripts/validate-updater-purity.mjs",
"typecheck": "turbo run typecheck && node scripts/validate-package-boundaries.mjs && node scripts/validate-updater-purity.mjs && node scripts/validate-side-chain-vocabulary.mjs",

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 Prefilter sources before the vocabulary AST scan

Every local and CI pnpm typecheck now ends by constructing a ts-morph project over all 2,535 tracked TypeScript-family files, although nearly all cannot contain any member of the script's closed denylist. A direct run in this checkout added roughly 28 seconds, making a one-time vocabulary migration a permanent typecheck penalty; prefilter file text for candidate spellings before adding files to the AST project.

Useful? React with 👍 / 👎.

Comment thread packages/engine/src/flowstate/types.ts Outdated
* Largest `limit` the workstream listing route accepts. Default 100.
*
* Raise it for deployments whose conversations run more background work
* Raise it for deployments whose conversations run more side-chain work

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 Describe the workstream limit as detached work

When operators consult maxWorkstreamListLimit, this now tells them to size it for side-chain work, but the option limits the workstream listing route: Workstreams are detached child sessions, while .sideChain() tasks do not create rows in that list. This points capacity tuning at the wrong workload; retain “background work” or explicitly say “detached workstreams.”

AGENTS.md reference: AGENTS.md:L46-L46

Useful? React with 👍 / 👎.

…r prose (FIX-766)

Three review findings, all taken.

**A third persisted surface nobody enumerated.** `reportedBackgroundTaskIds`
is a session-state key, and it was renamed as an ordinary identifier because
in source that is exactly what it looks like. A conversation started before
the deploy holds its acknowledgements under the old name, so the new reader
defaulted to `[]` and would re-announce every finished job. Decision 2
accepted "no shim" for two surfaces — `provenance.phase` and the block path —
on arguments that reach neither this one: it IS read to decide something, and
dual-reading a flat state key is four lines. So it is shimmed.

Deriving whether a FOURTH exists rather than recalling: 225 persisted key
names on origin/main, intersected with the 72 this rename moved, gives exactly
one — this key. The two other persisted keys carrying the vocabulary
(`workingDirectory`, `workerOutput`) are unrelated concepts, untouched.

**The guard charged rent on every typecheck.** It built a ts-morph project
over all 2,531 tracked files. Now pre-filtered on text first, with the pattern
DERIVED from the denylist rather than maintained beside it — a hand-written
filter drifts from the rules silently, and one narrower than the rule set
deletes coverage without failing anything. 2,531 files parsed becomes 655, and
the check goes 8.5s to 4.2s locally. `--parity` re-runs with the filter off and
diffs, so soundness is checkable on the real tree instead of argued.

**The prose sweep had no discrimination, and this is the evidence.** Ten of its
44 phrase rewrites were tier errors — comments about workstreams, detached
children and detached requests, where `background` is the correct umbrella word
and "side-chain" is simply wrong. Six I caught before pushing; four survived to
review, including `maxWorkstreamListLimit`, which now pointed capacity tuning at
the wrong workload. The identifier sweep has control fixtures proving it spares
`Workstream*`; the prose sweep has none, and a 23% error rate is what that
costs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

All three P2s taken, in 4bb9d36. The third one produced the most useful number in this PR.

1. A third persisted surface — dual-read

reportedBackgroundTaskIds is session state, and it was renamed as an ordinary identifier because in source that is precisely what it looks like. A conversation started before the deploy holds its acknowledgements under the old name; the new reader defaulted to [] and would re-announce every finished job.

The reason it slipped is worth naming: decision 2 settled "no shim" for exactly two persisted surfaces — provenance.phase (a value nothing reads to decide anything) and the block path (an identifier, where the alias lands in every prefix comparison in the path grammar). Neither argument reaches this one. It is read to decide something, and dual-reading a flat state key is four lines. So it is shimmed rather than exempted by an argument built for different surfaces.

Derived whether a fourth exists rather than recalling. Parsed origin/main for every persisted key name — object literals passed to patchState/updateState/setState/persist/save/upsert, plus every property under a *StateSchema — giving 225 keys, and intersected that with the 72 names this rename moved. Exactly one hit: this key. Two other persisted keys carry the vocabulary and were correctly untouched (workingDirectory in the bash tool, workerOutput in the supervisor pattern) — different concepts.

The legacy key is read-only and never written; the union persists under the new name on the next acknowledgement, so a session converges after one report. Five tests pin it; dropping the legacy read from the merge fails two of them.

2. The guard's runtime

It built a ts-morph project over all 2,531 tracked files. Now text-prefiltered first, and the pattern is derived from the denylist rather than maintained beside it — I did not want a hand-written filter that drifts from the rules, because a prefilter narrower than the rule set deletes coverage without failing anything, which is this check's signature failure. Adding a name to the denylist now automatically widens the filter.

2,531 files parsed → 655. 8.5s → 4.2s locally on this machine.

Soundness is checkable, not argued: --parity re-runs the scan with the filter off and diffs the findings. It passes on this branch and on origin/main, where the unfiltered scan finds 407 — so the filter demonstrably hides none of them.

Mutation table re-run afterwards, as asked. All seven rule mutations still fail (A–G below), plus new fixtures asserting every denylist name is admitted by the filter and that framework/network/teamwork/homework are skipped.

One honest note: mutation-testing the filter showed the quoted-literal alternative ("work") is removable with no coverage loss — work is a member name, so its own alternative already matches, a quote not being a letter. I kept it and documented why it is not load-bearing today: E2's rule does not depend on that membership, and work is the most ordinary word on the list, so it leaving RETIRED_MEMBER_NAMES is a plausible future call that would otherwise silently un-admit its files.

3. The prose sweep had no discrimination — here is the measurement

maxWorkstreamListLimit is fixed. But the instruction to re-audit was the right one, because it was not one site. It was ten, across eight files — 23% of the 44 phrase rewrites the sweep made.

Six I caught in my own pass before pushing (workstream-routes.ts ×2, create-request-host.ts ×2, context/types.ts, createFlowState.ts). Four survived to this review: flowstate/types.ts, routes/createFlowApiRouter.ts and runtime-config.ts all document the workstream listing limit — tier three — and createInboundTransportHost.ts describes a detached child inheriting the launching request's config. All four now say workstream/detached again.

The generalisation is the part I'd underline, and it is mine rather than yours: the identifier sweep has control fixtures proving it spares Workstream*, priorWork and onBackgroundWork. The prose sweep had no controls at all — and where background is the correct umbrella word for tier three, an undiscriminating sweep turns correct documentation into wrong documentation. A 23% error rate is what "no controls" costs, and it is only visible because someone went looking.

The PR now states the residual outright: prose is swept, unguarded, and manually re-audited for tier confusion — so the next reader knows a human is what is holding that boundary, not a rule.

Verification

Mutation Result
A wrapped-argument fix reverted 1 failed / 33 passed
B conditional-ancestor rule disabled 1 failed / 33 passed
C E1 re-broadened to a token denylist 9 failed / 25 passed
D member rule matches the OBJECT too 1 failed / 33 passed
E E2 union fires without a named holder 1 failed / 33 passed
F audited exemption swapped 1 failed / 33 passed
G one name dropped from the closed set 1 failed / 33 passed
Restored 34 passed

pnpm typecheck 60/60 + all three validators · pnpm docs:build clean under onBrokenLinks: "throw" · guard on origin/main 407 sites / exit 1, parity OK there too.


Generated by Claude Code


Generated by Claude Code

@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: 4bb9d36d58

ℹ️ 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".

if (item.type === "status") {
const status = item as StatusItem;
if (!status.message && typeof status.backgroundTasks !== "number") {
if (!status.message && typeof status.sideChainTasks !== "number") {

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 Keep reading legacy task-count statuses

When this DevTool reads an empty-message status produced by a pre-upgrade engine, or a persisted ctx.emit.status(..., { transient: false }) call, the row has backgroundTasks rather than sideChainTasks. This condition therefore drops the row before either renderer can show its pending/completed count, so mixed-version and persisted traces lose the only indication that side-chain draining is underway; dual-read the old key for the rollout window.

Useful? React with 👍 / 👎.

Comment thread docs/architecture/blocks.md Outdated
Comment on lines 320 to 324
| `forEachSideChain(block)` | Fire-and-forget fan-out per element | passthrough (value unchanged) |
| `doUntil(condition, block)` | Loop until condition is true | `ref` → final iteration's item |
| `doWhile(condition, block)` | Loop while condition is true | `ref` → final iteration's item |
| `loopBack(stepName, opts)` | Jump back to a named step (bounded) | passthrough |
| `work(block)` | Queue non-aborting side-chain execution | passthrough |

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 Replace every stale sequencer method reference

After removing .work(), this canonical method table updates forEachSideChain but still advertises work(block) at line 324. The same incomplete migration remains in docs/architecture/sequencer-dsl.md:264, the day-one table in apps/docs/docs/sequencers/composing-blocks.md:17, and .agents/skills/create-pattern/SKILL.md:253; users or agents following these references will generate calls that no longer typecheck.

AGENTS.md reference: AGENTS.md:L199-L202

Useful? React with 👍 / 👎.

Comment on lines +217 to +221
if (
Node.isMethodDeclaration(parent) ||
Node.isMethodSignature(parent) ||
Node.isPropertySignature(parent) ||
Node.isPropertyAssignment(parent) ||

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 Limit ordinary member names to the retired APIs

The revised closed-denylist still treats every property declaration or object key named work or backgroundTasks as the retired API: fresh checks against the current rule report E1 for interface Job { work: string } and E3 for const dashboard = { backgroundTasks: 3 }. Any unrelated domain model using these ordinary fields will therefore fail the repository-wide typecheck, so member detection must be constrained to the sequencer/status API surfaces rather than all TypeScript properties.

Useful? React with 👍 / 👎.

…method tables (FIX-766)

**The denylist still taxed ordinary field names.** `interface Job { work: string }`
reported E1 and `const dashboard = { backgroundTasks: 3 }` reported E3, because
the rule keyed on "is it in member position" — which is not the distinction that
matters. What matters is what the name BELONGS to. Two shapes recover that
without type information:

  - `work` is refused only when CALLED or declared as a method. The DSL verb is
    always callable; a `work` holding a string is a word.
  - `workGroupId` / `backgroundTasks` / `workResults` are refused only where the
    contract is DECLARED, inside the packages that own it. A reintroduced field
    on `StatusItem` is the regression; a dashboard's own field is not.

Stated under-reach, because a guard that under-reaches with a written boundary
beats one that red-lights every domain model: a *read* of a contract field, and
a declaration outside those packages, are not caught.

**A second persisted item field, dual-read.** `StatusItem.backgroundTasks` rides
on a persisted item, so a pre-upgrade or replayed status row carries the old
name — and the failure is quieter than a wrong label: the trace tree drops rows
with neither message nor count, so the row DISAPPEARS. One shared reader now
tolerates both spellings; no write path changes.

**Four canonical method tables still taught `work(block)`.** The markdown sweep
matched `.work(` and bare backticked `work`, so a backticked verb WITH an
arglist and no leading dot fell between them. `.agents/` was in the sweep's
roots all along (52 tracked files) — the miss was the shape, not the root. The
skill file is the worst of the four: skills are templates agents copy from, so
it wrote the retired name into new code rather than merely documenting it (same
shape as FIX-1126's `preset/fast` default). Re-derived across eight distinct
reference shapes; the only residuals are this change's own before/after table.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
@cursor

cursor Bot commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_974c505e-1f1d-46fc-be81-3442cc3b05e9)

Copy link
Copy Markdown
Collaborator Author

Both taken, in e7d2bfe, plus the enumeration from the previous round. The over-reach finding is the one I'd underline — it is the second time the same mistake shipped in the same file.

1. The denylist still taxed ordinary field names

Reproduced exactly as reported: interface Job { work: string } → E1, const dashboard = { backgroundTasks: 3 } → E3, and a third I found probing alongside them, type Row = { workResults: number } → E1.

The acceptance property I was given was satisfied and the bug survived it, which is the useful part. "Adding scheduleWork must not fail CI" exercises a function name; the rule matched any member or object key, so a correct fix against that property left the tax fully in place for properties. A test that passes while the defect stands is worse than no test, and this one was mine to widen.

The discriminator is now what the name belongs to, in the two shapes reachable without type information:

  • work — only when CALLED or declared as a method. pipeline.work(b) and work(b: B): Seq are the retired API; { work: string } is a data field and job.work is a read. Callability is a real property of the DSL verb, not a proxy for one.
  • workGroupId / backgroundTasks / workResults — only where the contract is DECLARED, inside the packages that own it. A reintroduced backgroundTasks?: number on StatusItem is the regression worth catching; a dashboard's own field is not.

Stated under-reach, taking your out rather than guessing: a read of a contract field, and a declaration outside those packages, are not caught — telling StatusItem.backgroundTasks from someone else's backgroundTasks needs the declaring type, which this check does not resolve. In src a read of a removed field already fails typecheck; in an untypechecked test directory it is caught by nothing, and that gap is real and written down.

All four shapes are fixtures now, both directions, and the mutation table was re-run: two mutations initially survived — dropping the call requirement, and the contract rule ignoring its package — and are now covered. Eight mutations, all killing tests.

2. Four method tables — and the sweep re-derived

Fixed. .agents/skills/create-pattern/SKILL.md also taught `background(block)`, which was never a DSL method at all — a pre-existing doc error, so I deleted it rather than renaming it into a second name that also doesn't exist.

One correction to the hypothesis: .agents/ was in the sweep's roots. The sweep enumerates via git ls-files '*.md', which includes dot-directories — 52 tracked .agents markdown files were scanned. The miss was the shape, not the root: I matched .work( (leading dot) and bare `work` (backticked, no arglist), and a backticked verb with an arglist and no leading dot — `work(block)` — fell precisely between them.

Re-derived across eight distinct reference shapes rather than fixing four sites: inline call, backticked bare, backticked-with-arglist, heading, unbackticked call, table cell, and each of the two distinctive verb names in prose. Four hits, all the ones reported. Every shape is now zero across all tracked markdown except this change's own before/after migration table, which must keep the old names.

The FIX-1126 parallel holds and is worth restating for the next person: a skill is a template agents copy from, so a retired name there doesn't merely document the past — it writes the past into new code.

3. The enumeration you asked for last round

Complete derived set of persisted surfaces is now in the PR body with its method. Five, not two: provenance.phase and the block path (spec-decided, no shim), ItemProvenance.workGroupId (safe unshimmed — every consumer is an identity-propagating write, nothing reads it to decide), and StatusItem.backgroundTasks and reportedBackgroundTaskIds, both now dual-read on the read side only.

StatusItem.backgroundTasks went through one shared helper rather than three inlined ??s, because there were three readers. Its failure mode is worth stating precisely, since it is quieter than a wrong label: the trace tree drops status rows carrying neither a message nor a count, so reading only the new spelling makes a pre-upgrade row disappear. There is a test that fails if the legacy branch is removed.

And the honest note about my own enumeration: the first one I ran was too narrow. I scoped it to state-schema keys and patchState-style writers, found reportedBackgroundTaskIds, and reported "no fourth" — a derivation that structurally could not see a persisted item field. That is the same shape as the guard's own repeated failure: a rule reporting green because a category sat outside it. The current derivation classifies by carrier (items / state / stores) and has its own stated limit written into the PR — it enumerates renamed keys, so a renamed value like provenance.phase is invisible to it and is in the table only because the spec named it. If a sixth surface exists, it is most likely another value.

Verification

pnpm typecheck 60/60 + all three validators · guard on origin/main 407 sites / exit 1, --parity OK there too · pnpm docs:build clean under onBrokenLinks: "throw" · core 1984, devtool 256, contracts 48, kitchen-sink 90, engine 2295, integration-tests 66.

labs/trading-desk has flaked three times on the same 5s PGlite timeout in portfolio-backing.spec.ts; it passes 2/2 in isolation, labs/ is untouched by this diff, and a full-suite baseline on origin/main is running to confirm the flake predates the branch rather than asserting it.


Generated by Claude Code


Generated by Claude Code

@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: e7d2bfe0d5

ℹ️ 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".

if (
Node.isCallExpression(parent) &&
PATH_BUILDERS.has(parent.getExpression().getText()) &&
parent.getArguments().indexOf(node) === PATH_OP_ARG_INDEX

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 Use the correct operation index for each path builder

PATH_OP_ARG_INDEX is correct for childBlockPath(ctx, runtime, op, stepIndex), but blockPathSegment(op, stepIndex) takes the operation at index 0. Consequently, a direct blockPathSegment("work", i) call produces no E4 finding and can silently restore the retired persisted path segment despite blockPathSegment being explicitly listed as guarded; map each builder to its own argument index and add a fixture for the direct helper call.

Useful? React with 👍 / 👎.

`PATH_OP_ARG_INDEX = 2` was one constant applied to two builders with
different arities. It is correct for `childBlockPath(ctx, runtime, op,
stepIndex)` and wrong for `blockPathSegment(op, index)`, where the op is
first — so a direct `blockPathSegment("work", i)` produced no finding at all,
while `blockPathSegment` was named in the guarded list.

That is the third time in this PR that stated coverage and actual coverage
diverged, and this instance is the sharpest: naming a builder as guarded is a
claim, and the index is what makes it true. A reader checking whether the
direct helper was covered would see the name and stop.

It lands on E4, the encoding that reaches the persisted block path and so the
replay-log key — the rule whose failure mode is a completed side chain
silently re-executing. Decision 2 accepted that consequence only because it
was bounded to the pre-publish window; a hole here means the bound is not
enforced.

Indices are now derived per builder from the declarations. Checking the rest
of the family while there: `blockPathIteration`, `blockPathLoop`,
`blockPathBranch`, `blockPathRescue` and `blockPathTool` take no tier op, so
they are deliberately absent rather than mapped — the assumption had never
been checked for any of them.

Deriving that also exposed a route past the builders entirely: a segment that
is already formatted (`extendBlockPath(p, "work[0]")`). `op[index]` is the
segment's exact shape, so a literal of that shape IS a persisted path segment
however it was written. Adding that rule immediately found two stale
`"work[0]"` arguments this rename had left in `sequencer-kernel.test.ts`.

The exemption list closes at two: both rename-boundary characterization tests,
one per persisted surface crossed. Pinned by name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

Taken, in 141b9b3. Confirmed by deriving both signatures rather than reading the list:

childBlockPath(ctx, runtime, op, stepIndex, iteration?)   op at 2   core/src/blocks/sequencer.ts
blockPathSegment(op, index)                               op at 0   contracts/src/block-instance-id.ts

One constant cannot be right for both. Each builder now carries its own index, and there is a control fixture asserting blockPathSegment(op, "work") does not fire — proving the index is consulted rather than ignored.

Why this one was worth its size

You're right that it is the third instance of the same shape, and it is the sharpest of the three. The other two were categories nobody had enumerated. This one was listed as covered: blockPathSegment appears in PATH_BUILDERS, so anybody auditing E4 coverage sees the builder's name and stops. Naming a builder as guarded is a claim; the index is what makes it true, and the claim outlived the implementation.

And it lands on the one encoding where a hole has a runtime consequence rather than a cosmetic one. E4 reaches the persisted block path, which keys replay-log memoization — the mechanism whose failure mode is a completed side chain silently re-running. Decision 2 accepted that cost only because it is bounded to requests in flight across the pre-publish deploy. A rule that can't see a route by which the retired segment returns doesn't enforce that bound; it just asserts it.

Checking the rest of the family, as asked

Derived from the declarations rather than from the list — and the assumption had indeed never been checked for any of them. The other blockPath* helpers in contracts/src/block-instance-id.ts are blockPathIteration(iteration), blockPathLoop(generation), blockPathBranch(branchName), blockPathRescue(index) and blockPathTool(toolName, callId). None takes a tier op, so they are deliberately absent from the map rather than mapped — now stated in the docblock so the next reader doesn't have to re-derive it.

What deriving it turned up

extendBlockPath(parentPath, segment) takes an already-formatted segment, so it bypasses every op-argument rule by construction. op[index] is the segment's exact shape, which means a literal of that shape is a persisted path segment however it was written — a precise rule, not a broad one.

Adding it immediately found two stale sites this rename had left behind: packages/core/test/sequencer-kernel.test.ts:95 and :107, both passing "work[0]" as the path argument to runSideChain. Not hypothetical, and nothing else in the toolchain could see them — they are string arguments in a test directory that pnpm typecheck does not compile.

That also forced the exemption list from one entry to two. It now holds exactly the two rename-boundary characterization tests, one per persisted surface the rename crosses: the legacy phase record, and the cross-version continuation test that rewrites a durable log to …/work[n] on purpose. Closed category, pinned by name, and the load-time assertion moved with it.

Verification

Nine mutations, all killing tests — including the two new ones: reverting blockPathSegment's index to the shared 2, and disabling the segment-literal rule.

pnpm typecheck 60/60 + all three validators · --parity OK on both branches · pnpm docs:build clean under onBrokenLinks: "throw" · core 1988, engine 2295, devtool 256, contracts 48.

The labs/trading-desk thread, closed with evidence

The baseline finished. origin/main, clean full run: 57/57 tasks, exit 0, with portfolio-backing.spec.ts passing in 3.296s.

That gives the mechanism rather than an assertion: the test has a 5s timeout and a ~3.3s nominal runtime, so roughly 1.7s of headroom. My branch also passes a clean full run 57/57. Every failure of it occurred in runs where I had a second suite competing for CPU — my own doing, not the diff's. git diff --name-only origin/main..HEAD -- labs/ is empty and the package references none of the renamed vocabulary.

Being precise about what this does and doesn't show: I could not make it fail on main on demand, so this is not a reproduction of the flake there. What it establishes is that both branches pass clean, the failures correlate with concurrent load rather than with the change, and there is no code path from this diff to that package.


Generated by Claude Code


Generated by Claude Code

@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: 141b9b33d8

ℹ️ 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".

@@ -441,7 +433,6 @@ export type FlowDefinition<
request?: TRequest;
user?: TUser;
org?: TOrg;

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 Remove the documented flow-level work hooks

Removing FlowDefinition.work here leaves the authoritative example in docs/architecture/flows-and-actions.md:116-121 advertising work: { onStarted, onCompleted, onErrored, onFinished } as valid configuration, so developers following the canonical architecture documentation now write code that does not typecheck. Remove that stanza and clarify that the lifecycle table describes request/action hooks.

AGENTS.md reference: AGENTS.md:L199-L202

Useful? React with 👍 / 👎.

Comment on lines +459 to +461
if (Node.isPropertyAssignment(parent)) {
const name = parent.getName();
return name === "phase" || name === "scope";

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 tier-literal checks to framework contracts

With the current revision, an unrelated first-party model such as const job = { scope: "work" } is classified as E2 here, while the adjacent branch likewise rejects job.scope === "work"; because root pnpm typecheck scans every tracked TypeScript file, legitimate scheduling or domain code fails CI. The fresh evidence beyond the earlier broad-guard comments is that union and member matching is now narrowed, but these scope/phase value rules remain repository-global; restrict them to FlowError/provenance carriers.

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.

Not taking this one, and the reasoning is worth recording because the earlier two narrowings were correct and this one isn't the same shape.

The proposed remedy reintroduces the blind spot the rule exists for. Keying phase/scope to declared carriers needs type information the guard deliberately does not have at these positions. Several packages typecheck only src/** — devtool's tsconfig is include: ["src/**/*"] — so a test fixture's { phase: "work" } is never seen by tsc, and this rule is the only thing between a renamed fixture and a stale one. Restricting it to FlowError/provenance carriers would make it green on precisely the files it was written to cover.

This isn't the over-reach the earlier comments found. The token rule flagged any identifier containing work, and the union rule flagged any union with a "work" member — type Status = "idle" | "work". Both taxed unrelated concepts, and both were conceded. These two rules name two fields that mean the execution tier in this codebase. Repo-wide, scope and phase are dense framework fields (46 "session", 15 "request", 15 "main", plus block/user/org/run/output/stream/input/generator/final), and "work" is not a legitimate value of either under any current meaning. Zero first-party sites collide.

The cost you're pointing at is real, though, and it's now written down. There's no per-site escape hatch — EXEMPT_FILES is pinned by assertion to two rename-boundary tests — so a future legitimate { scope: "work" } is a hard CI block requiring a script edit. That was undocumented. 4430471 adds it to the known-gaps docblock as a gap that runs the other way: deliberate over-reach, why the type-directed alternative fails, and what a developer who hits it has to do. 72adcba fixes its placement so it follows the gap list instead of splitting it.

One thing your comment made visible that mattered more than the rule itself. The defence above only holds while the docs aren't teaching the retired value — and packages/engine/src/errors/error-capture.ts:42 was doing exactly that, documenting the scope union as "block" | "request" | "work" | "resource" after "work" became "sideChain". A developer following it would write scope: "work", fail to compile, and land on this guard with a public doc comment as the thing that sent them there. That and ten sibling sites are fixed in fcfb90c, including packages/core/src/types/block.ts:516, whose JSDoc named "work" one line above phase?: "main" | "sideChain".


Generated by Claude Code

…ose (FIX-766)

`docs/architecture/flows-and-actions.md` still showed a `work: { onStarted…
}` stanza inside its canonical `defineFlow({…})` example. This PR DELETES that
config rather than renaming it, so a developer following the architecture doc
was writing code that does not typecheck. Removed; the changeset already
documents the removal.

The other eight sites are the shape a hand sweep is built to miss. The guard's
own docblock says prose is unscanned and "roughly half of this rename was
prose, and it was swept by hand" — and a hand sweep catches the mechanical
forms (`.work()`, `` `work` ``, `work(block)`) while the retired tier word
survives in ordinary English beside correctly-renamed code. Eight lifecycle
rows and failOnError sentences still said "work failures" next to
`.waitForSideChain()`.

The two in `sequencer-side-chains.md` are the tell: the page was retitled and
its calls updated, and its English still taught the retired word. That is the
residue this change exists to remove, and no rule in the guard can see it.

Bounded deliberately — only sites where `work` NAMES the tier. Generic English
uses of the word are untouched and no surrounding sentence was restyled.

Also documents a gap that runs the other way, in the guard's known-gaps
section: a `phase`/`scope` field valued `"work"` is denied repository-wide
regardless of local meaning. That over-reach is deliberate — the rule must fire
in files the compiler never typechecks, and keying it to declared carriers
would need the type information that is missing exactly there — but it has no
per-site escape hatch, so a legitimate future use is a hard CI block requiring
a script edit. Comment only; no rule or behaviour change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

Round 5 handled in 4430471. One taken, one declined with the honest half taken.

Taken — the deleted work config was still advertised

docs/architecture/flows-and-actions.md showed a work: { onStarted… } stanza inside its canonical defineFlow({…}) example. This PR deletes that config rather than renaming it, so a developer following the architecture doc was writing code that does not compile. Removed. The four block names it referenced (workStartedBlock and friends) appeared nowhere else in the file, so nothing dangles.

Taken — the generalization, which is the part worth keeping

Eight prose sites where work names the tier, all fixed:

Site Was
flows-and-actions.md lifecycle table Non-terminal step/work failure
execution-and-errors.md:283 non-terminal step/work failures
execution-and-errors.md:179 promotes any work failure to terminal
blocks.md:344 promotes work failures to terminal errors
sequencer-side-chains.md:108 does not throw on work failures
sequencer-side-chains.md:118 promote work failures
add-flow/SKILL.md:263 Non-terminal step/work failure
debug-flow/SKILL.md:253 Recoverable step/work failure

The two in sequencer-side-chains.md are the tell, and they indict the method rather than the effort: that page was retitled, its headings rewritten and every call updated to .waitForSideChain() — and the English immediately beside those calls still taught "work failures". A hand sweep catches the mechanical forms because they are patterns you can hold in your head (.work(), `work`, work(block)); the retired tier word in an ordinary sentence is not a pattern, which is exactly why it survived next to code that had been correctly renamed.

Bounded as instructed: only sites where work names the tier, no generic English touched, no surrounding sentences restyled, and nothing added to apps/docs/** about the rename's history.

What I will not claim: that the prose sweep is now complete. The greps cover mechanical shapes; this round's eight sites are proof that the residual class is precisely the one no grep can express. The PR body already states prose as swept-but-unguarded — it now also carries this round as the evidence for why that boundary is real rather than cautious.

Declined — narrowing the scope/phase value rules

I agree with the decline and would have reached it independently; the second reason is the one I find decisive.

Keying those rules to typed carriers requires type information the guard deliberately does not have at those positions, and the property-assignment rule exists because several packages compile only src/**. Narrowing it makes it green on exactly the files it was written for — that is not a hypothetical, it is how three of this PR's earlier holes were found (a fixture's phase: "work", one behind as const, one in a builder argument, none visible to tsc).

It is also not the over-reach we took twice. Those rules flagged unrelated concepts — any identifier containing work, any union with a "work" member. These are keyed to two specific field names that mean the tier in this codebase, which is the closed denylist working as intended rather than failing.

The honest half is taken. The docblock's known-gaps section previously listed only what is not caught; it now also records the converse: a phase/scope field valued "work" is denied repository-wide regardless of local meaning, that this is deliberate for the reason above, and — the part that was undocumented and is a real cost — that there is no per-site escape hatch. EXEMPT_FILES is pinned by assertion to the two rename-boundary tests, so a legitimate future { scope: "work" } is a hard CI block that can only be resolved by renaming the value or editing the rule. Comment only; no rule change, no behaviour change.

Verification

  • node scripts/validate-side-chain-vocabulary.mjs — green; --parity OK. Nothing here changes rules, and a red result would have meant I'd changed behaviour I didn't intend to.
  • Guard fixtures — 40 passed, including the exemption-count assertion.
  • pnpm docs:build — clean under onBrokenLinks: "throw" (two published-page sites changed).
  • pnpm test on this branch, clean run with nothing else competing: 57/57 tasks, exit 0, portfolio-backing.spec.ts passing at 3.63s — which also closes the labs/trading-desk thread from the previous round: origin/main gave 57/57 with the same test at 3.30s against a 5s budget, so the earlier failures track CPU contention from a second suite I was running, not this diff.

Nothing in the round I think is wrong.


Generated by Claude Code


Generated by Claude Code

claude added 2 commits August 15, 2026 01:26
…-766)

The block landed between the `.js`/`.jsx` bullet and the UNTRACKED bullet,
so twenty lines of prose sat mid-list and the closing bullet read as a stray
fragment detached from the list it belongs to. Moved after the list; the
bullets now close intact and the note follows as its own paragraph.

Placement only — the text is byte-identical, same length and same character
multiset, just reordered. The `include: ["src/**\/*"]` escape is retained
deliberately: unescaped, the `*/` would terminate the block comment.

This file exists to be read by whoever the guard blocks next, so a list broken
in the middle is a real cost rather than a formatting nit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
…-766)

Round 5's prose pass was scoped to markdown. The retired vocabulary was also
live in code comments inside the packages this change publishes, and two of
those contradict the declaration they sit on:

  - `types/block.ts` documented `phase?: "main" | "sideChain"` as
    `"work" for background scopes` — naming a value the type cannot hold, one
    line above the type that cannot hold it.
  - `errors/error-capture.ts` ENUMERATED the `FlowErrorScope` members as
    `"block" | "request" | "work" | "resource"`, listing one that no longer
    exists.

The second closes a loop worth naming. A developer following that comment
writes `scope: "work"`, fails to compile, and then trips the guard's
repository-wide `scope`/`phase` denial — the over-reach defended two rounds
ago on the grounds that no legitimate use collides. That defence holds only
while the docs are not actively teaching the retired value; they were.

The rest name a phase value or a method that no longer exists, including four
inside the bodies of `sideChain()` and `sideChainIf()` themselves — the
methods documenting their own shapes under the name they no longer have.

Comments only: 13 lines changed, 13 replaced, no reflow and no restyling.
`FIX-663` / `FIX-554` tracking ids in the touched comments are left in place —
they violate BP-006 but are pre-existing and not this change's business.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

Round 6 in fcfb90c — all eleven taken. The prose pass had been scoped to markdown; the same vocabulary was live in code comments inside the packages this change publishes.

The two that matter

Both contradict the declaration they sit on, in packages about to be published:

  • packages/core/src/types/block.ts documented phase?: "main" | "sideChain" as "work" for background scopes — naming a value the type cannot hold, one line above the type that cannot hold it.
  • packages/engine/src/errors/error-capture.ts enumerated the FlowErrorScope members as "block" | "request" | "work" | "resource", listing one that no longer exists.

The second is the worst site in the PR, and it closes a loop worth seeing. A developer follows that comment, writes scope: "work", fails to compile, and then trips the guard's repository-wide scope/phase denial — the over-reach I defended two rounds ago on the grounds that no legitimate use collides. That defence is only honest while the docs aren't teaching the retired value. They were. The rule and the comment were pulling against each other, and the comment would have made the rule look like the bug.

The remaining nine name a phase value or a removed method, including four inside the bodies of sideChain() and sideChainIf() — the methods documenting their own call shapes under the name they no longer have.

Verification, with what it does and doesn't prove

  • node scripts/validate-side-chain-vocabulary.mjs — green. Stating plainly: this is not evidence these are fixed. The guard does not scan comments; it was green before this commit too, with all eleven sites present. Its docblock lists prose as an unscanned gap, and round 6 is that gap being exercised.
  • Both of your sweeps return 0. Sweep 1 (comment lines naming the tier): 0. Sweep 2 (single-line doc comments): 0. No site deliberately left.
  • pnpm typecheck — 60/60 tasks + all three validators. The load-bearing check here, since sites 1 and 2 are in .ts files where an unbalanced comment edit breaks the parse rather than merely reading wrong.
  • Diff shape: 13 insertions, 13 deletions across 6 files — a 1:1 line swap. No reflow, no restyling, no surrounding sentences touched.

Three changed lines beyond the eleven, named because you asked that every line trace to the list

Each is a continuation of an enumerated site within the same comment, and each names the tier or the phase:

  1. sequencer.ts:1615 — (work → "trace"), the second half of site 4's sentence about the phase driving the generator's default role.
  2. sequencer-kernel.ts:133 — "under the background signal", the same clause as site 9's "work" phase. That signal is _requestSideChainSignal; leaving it would have half-fixed one sentence.
  3. sequencer-kernel.ts:136 — "background dispatch never rewrites the running output descriptor", the closing line of that same docblock.

If you'd rather any of those had stayed, they're trivially revertible — but leaving a sentence renamed at its start and retired at its end seemed worse than the small overshoot.

Declined / left alone, as instructed

  • FIX-663 and FIX-554 ids retained in the touched comments. They do violate BP-006 (planning ids in code), but they're pre-existing and not this change's business. Flagging, not fixing.
  • No comment-scanning rule added to the guard. Agreed with the decline: ordinary English "work" in comments is everywhere, so the false-positive surface is large — and that is the same over-reach this PR has already had to undo twice. The docblock documents prose as unscanned, and round 6 is now the concrete evidence for how that gap behaves. If it's wanted, it's a separate issue.

Nothing in the round I think is wrong. The scoping miss was worth catching — five rounds of mechanical sweeps kept coming back clean because they were looking at markdown, and the two sites that actually contradicted a published type were sitting in .ts the whole time.


Generated by Claude Code


Generated by Claude Code

Round 6 was scoped to `packages/*/src`, which left the test trees. Eleven
comments there described current code by retired names.

Six are settled rather than judgment calls: the two store recovery suites
assert `provenance.phase === "sideChain"` while three comments in each of
those same files describe the value as `phase:"work"`. The code was renamed
and the comments describing that exact code were not.

The rest name the pool by its old symbol, including
`request-side-chain-pool.test.ts` — a file renamed by this change whose own
header still called it "the per-request background work pool".

Bounded to what names a renamed symbol or a retired value. The three
`background-work-recovery.test.ts` filenames stay: unlike
`request-work-pool.test.ts`, which moved because the symbol it tests moved,
these cover crash recovery of durable background work, and this change
explicitly restores `background` as the umbrella over all three tiers. That
reasoning also bounds the edits inside them — `work pool` and `phase:"work"`
are fixed; the word `background` reading as the umbrella is left alone.

Two files are deliberately untouched and must stay that way: the guard's own
fixtures and the exempt legacy-record test, whose subject IS the retired
spelling. The sweep over `packages/*/test` now returns exactly those 8 sites
and no others — zero would mean one of them had been edited.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

@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: fcfb90cb3a

ℹ️ 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".

return;
}

if (Node.isStringLiteral(node)) {

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 Scan no-substitution template literals

When a retired value is written as a backtick literal without interpolation, ts-morph represents it as a NoSubstitutionTemplateLiteral, so this Node.isStringLiteral branch and the later interpolated-template branch both skip it. As a result, analyzeSources accepts { phase: work }, blockPathSegment(work, i), and extendBlockPath(parent, work[0]), while detecting their double-quoted equivalents; because blockPathSegment accepts any string, typechecking will not prevent the old persisted path segment from returning.

Useful? React with 👍 / 👎.

The guard had exactly two literal branches — `isStringLiteral` and
`isTemplateExpression`. A backtick string with no `${}` is a
`NoSubstitutionTemplateLiteral`, which is neither, so it fell through both and
every rule underneath them. The check accepted

    { phase: `work` }            blockPathSegment(`work`, i)
    extendBlockPath(p, `work[0]`)

while rejecting their double-quoted equivalents. It lands on E4, the encoding
that reaches the persisted block path, and `blockPathSegment` takes any string
— so the compiler would not have caught it either. Latent when found, which is
the regression the guard exists to stop rather than a reason to discount it.

**Third instance of the same defect class**, after `PATH_OP_ARG_INDEX`
assuming one arity for two builders and the member rule matching any property:
the guard CLAIMS coverage it does not have, and a reader auditing coverage sees
the branch and stops. A branch is only as wide as the node kinds it names.

Fixed by derivation rather than another `if`. TypeScript spells a complete
string two ways — `StringLiteral` and `NoSubstitutionTemplateLiteral` — and
that set is closed by the language, not by whatever this check is next shown to
miss. `getLiteralValue()` is defined on both, so every downstream rule works
unchanged once the filter admits both, and the filter site was the only place
carrying the assumption.

Fixtures include the controls that make them mean something: the quoted forms
must still fire, and an unrelated backtick string must not. This change has
undone a widening over-reach twice; the template-literal door is a new way back
in. Reverting the fix fails exactly the three new fixtures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

Round 8 in f69447b6. Real hole, confirmed before fixing and mutation-proven after.

The hole

Reproduced exactly: all three backtick forms missed, all three double-quoted equivalents fired.

MISSES   { phase: `work` }              FIRES E2   { phase: "work" }
MISSES   blockPathSegment(`work`, i)    FIRES E4   blockPathSegment("work", i)
MISSES   extendBlockPath(p, `work[0]`)  FIRES E4   extendBlockPath(p, "work[0]")

A backtick string with no ${} is a NoSubstitutionTemplateLiteral — neither StringLiteral nor TemplateExpression — so it fell through both branches and every rule beneath them. On E4, where blockPathSegment takes any string, tsc would not have caught it either.

Third instance of the class, and the pattern is the finding. After PATH_OP_ARG_INDEX assuming one arity for two builders, and the member rule matching any property: the guard claims coverage it does not have, and a reader auditing coverage sees the branch and stops. A branch is only as wide as the node kinds it names.

Fixed by derivation, not another if

TypeScript spells a complete string exactly two ways — StringLiteral and NoSubstitutionTemplateLiteral — and that set is closed by the language, not by whatever this check is next shown to miss. getLiteralValue() is defined on both, so once the filter admits both, every downstream rule works unchanged.

I checked whether anything else carried the assumption: isRetiredTierLiteral and effectiveParent use only getLiteralValue() and generic parent walking, and the filter site was the sole place naming isStringLiteral. One helper, one call site.

Fixtures, with the controls that make them mean anything

Three for the shapes named, plus two control groups:

  • No regression — the double-quoted equivalents still fire.
  • No widening — an unrelated backtick string does not fire: `hello work`, `workflow`, extendBlockPath(p, `step[0]`). This PR has undone a widening over-reach twice, and the template-literal door is a fresh way back in; I did not want to close a hole by opening that.

Mutation check: reverting the filter to isStringLiteral-only fails exactly the three new fixtures (3 failed / 42 passed), restore → 45 passed. The controls pass either way, which is correct — they are regression guards, not the thing under test.

Full table re-run since the filter is upstream of every literal rule — nine mutations, all killing tests, and blockPathSegment's index mutation now fails 3 rather than 1, because the new backtick fixtures exercise that path too.

Verification

  • node scripts/validate-side-chain-vocabulary.mjs — green; --parity OK.
  • Guard fixtures — 45 passed (was 40).
  • pnpm typecheck — 60/60 + all three validators.
  • core — 122 files / 1993 tests passing.
  • Live backtick tier literals in code: 0. The sweep returns 7 hits, all inside the guard's own fixture file — already on the KEEP list because its subject is the retired spelling.
  • Full suite running on this HEAD; will report.

On the env var — you asked what I think

A hard throw is the wrong behaviour there, and I'd raise it as a bug rather than a papercut. The message is FSDEV_DEFAULT_MODEL was set, but no intents are declared; the override has no effect — it says outright that the override has no effect. Something with no effect cannot be a correctness hazard, so failing closed buys nothing and costs a lot: the variable is ambient, so it poisons every flow in the process that happens not to declare intents, and the failure surfaces far from the cause. It cost me a wrong attribution earlier in this PR — I spent a cycle chasing eight "failures" in trading-desk that were entirely this.

A warn is the right level: the user asked for something that will not happen, which is worth saying once and not worth halting for. If there is a real hazard behind it — an override silently applying to some flows and not others, so the process is in a mixed state — then the throw is defensible but the message is wrong, because it describes a no-op. Either way the current pairing (fatal error, "has no effect" text) is internally inconsistent, and that inconsistency is the bug worth filing. Out of scope here; not touched.


Generated by Claude Code


Generated by Claude Code

@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: f69447b64a

ℹ️ 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 on lines +619 to +623
const parent = node.getParent();
const callee = Node.isCallExpression(parent)
? parent.getExpression().getText()
: undefined;
const opIndex = callee === undefined ? undefined : PATH_BUILDERS.get(callee);

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 Normalize wrapped path-builder arguments

Fresh evidence beyond the earlier wrapped-argument fix is that it only reaches E2: blockPathSegment("work" as const, i) and childBlockPath(ctx, runtime, "work" as const, i) still produce no finding because this branch inspects the literal's immediate parent instead of the effective wrapped argument. Both calls typecheck and recreate the retired persisted work[...] replay key, so apply the same effectiveParent() normalization here before checking the callee and argument position.

Useful? React with 👍 / 👎.

// persisted path segment however it was written. Found while deriving
// the builder arities: `extendBlockPath` takes an already-formatted
// segment, so no op-argument rule can reach it.
if (/^(work|workIf|forEachBackground)\[\d*\]?/.test(node.getLiteralValue())) {

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 Require an exact persisted path segment

This repository-wide rule also matches unrelated literals such as "work[shop", "work[abc]", and "work[0]suffix" because the digits and closing bracket are optional and the expression is not end-anchored. Those strings therefore fail root pnpm typecheck even though blockPathSegment emits the exact numeric op[index] shape; require the complete segment, or an explicit path boundary, instead.

Useful? React with 👍 / 👎.

Comment on lines 6 to 7
* → thinkingStyleRouter → biasCheck (.work) → perspective capture (.sideChainIf)
* → mem.captureFromItems (.work) → autoTitle (.work) → incrementRequestCount

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 Finish renaming the pipeline map

Fresh evidence beyond the previously reported method tables is that this changed pipeline map still labels three operations as .work, even though the implementation below now invokes the removed .sideChain() API. Because the vocabulary guard deliberately ignores comments, this canonical overview will continue teaching an invalid composition recipe unless all three labels are updated.

Useful? React with 👍 / 👎.

…ffectiveParent (FIX-766)

Three findings from review, plus one I found by auditing after them.

**The segment regex over-reached.** `\[\d*\]?` with no `$` allowed zero digits,
an optional closing bracket and any suffix, so `"work[shop"`, `"work[abc]"` and
`"work[0]suffix"` all failed CI. `blockPathSegment(op, index)` emits exactly
`op[index]`, so anything else is a false positive — the direction this check has
already had to correct twice. Anchored to `\[\d+\]$`.

**E4's path builder read `getParent()` where `effectiveParent()` was required**,
so `blockPathSegment("work" as const, i)` produced nothing: the raw parent is
the AsExpression, and the argument list holds the wrapper rather than the
literal. The helper exists precisely for that trap and its docblock says so —
the earlier wrapped-argument fix reached E2 only, and E4, the encoding that
reaches the persisted block path, kept the hole for four rounds.

**Then the audit.** Checking every raw `getParent()` in the file rather than
fixing the two lines named found a third branch with the same assumption:
`isCalledOrMethodDeclaration` missed `(pipeline.work)(b)`, because a
ParenthesizedExpression sits between the access and the call. The assumption was
never per-rule, it was per-branch, and three branches held it independently.
Every literal and callee branch now routes through the one helper.

Also fixes the kitchen-sink pipeline map, which labelled three steps `.work`
in the same docblock that says `.sideChainIf` — the canonical overview teaching
a removed API. It survived every prior sweep because a bare `.work` with no
parens matches none of the patterns those sweeps used.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH
@cursor

cursor Bot commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_db81c878-97db-40ff-84b7-28817a4c3022)

…IX-766)

Review caught the segment regex allowing `"work[shop"`. Rather than fix only
that, I probed the other two pattern-shaped rules for the same defect. The
regex-literal rule had it — `/work\[shop/` fired — because the bracket was not
required to be followed by an index. The template-head rule did not, because it
requires the exact `op:` prefix; that distinction is now pinned in both
directions so it is not re-derived.

This is the consolidating pass rather than a fourth patch: every literal filter
and every callee walk now routes through the shared helpers, and every
pattern-shaped rule has been probed against a near-miss. The defect class this
change kept hitting — a branch carrying its own copy of an assumption — is
closed by construction in this file, not by absence of further reports.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

Round 9 in 354e6b6f + a18556e3. All three taken, plus two more of the same class found by auditing instead of waiting.

1. Segment regex over-reached — fixed and anchored

\[\d*\]? with no $ allowed zero digits, an optional bracket and any suffix. blockPathSegment(op, index) emits exactly op[index], so anything else is a false positive. Now \[\d+\]$. Fixtures prove "work[shop", "work[abc]", "work[0]suffix" do not fire and "work[0]" / "work[12]" still do.

2. E4 ignored effectiveParent() — fixed, and it was worse than two lines

Confirmed: blockPathSegment("work" as const, i) produced nothing. You're right that the helper's own docblock describes exactly this trap — the earlier wrapped-argument fix reached E2 only.

You said not to fix only the two lines named, so I audited every raw getParent() in the file. That found a third branch with the same assumption: isCalledOrMethodDeclaration missed (pipeline.work)(b), because a ParenthesizedExpression sits between the access and the call.

The assumption was never per-rule, it was per-branch, and three branches held it independently. That reframing is the actual finding. Every literal filter and callee walk now routes through the shared helper. The template branch was checked and never consulted getParent() at all — verified, not assumed.

A bonus from the same fix: name: "work" as const in sequencer.ts now fires too, since the else-if shares the effective parent.

3. run.ts pipeline map — fixed

Three .work labels in the docblock that elsewhere says .sideChainIf. Taken as your correction. Worth naming why it survived: a bare .work with no parens matches none of "work", `work`, \bwork\( or work pool — the sweep was green because it couldn't express the shape, which is the same failure mode as every guard hole on this PR.

The audit you didn't ask for, which is my answer to the round-cap question

After fixing #1, I probed the other two pattern-shaped rules for the same over-reach. One had it: the regex-literal rule fired on /work\[shop/. Now requires a non-letter after the bracket. The template-head rule did not — it requires the exact op: prefix, so `workshop:${x}` and `working:${x}` correctly pass. Both directions pinned so the distinction isn't re-derived.

On whether another round is likely — plainly, as asked. The class this change kept hitting is a branch carrying its own copy of an assumption. Rounds 4, 8 and 9 were all that class: per-builder arity, per-node-kind coverage, per-branch parent walking, per-rule pattern tightness. I have now closed it by construction rather than by absence of reports:

  • every literal filter goes through isCompleteStringLiteral
  • every callee/argument walk goes through effectiveParent
  • every pattern-shaped rule has been probed against a near-miss in both directions
  • 58 fixtures; ten mutations, each shown to kill tests

So I don't think the guard needs another consolidating pass — this was it. What I can't rule out is a different class: a rule whose predicate is semantically wrong rather than structurally inconsistent. Nothing in the file suggests one right now, but that's the honest limit of what an audit of this shape proves.

Verification

  • Guard green, --parity OK, pnpm typecheck 60/60 + all three validators.
  • Guard fixtures: 58 passed (was 45).
  • Mutations, each killing tests: un-anchor the segment regex (1), path builder back to raw getParent() (2), identifier rule back to raw grandparent (1), un-tighten the regex rule (1), plus the six standing ones.
  • Corrected sweep residual: zero tracked sources. The only hits are packages/*/dist/** (gitignored, confirmed), the guard's own fixture file, and this change's own changeset migration table.

One suite note, honestly

labs/trading-desk's portfolio-backing.spec.ts failed a fourth time — 5271ms against a 5000ms per-test budget, a 5% overshoot. In isolation it passes 3/3 with the test body at 2.38–2.56s, so it has ~2x headroom idle, which is thin for a PGlite test under a parallel monorepo run. labs/ is untouched by this diff and references none of the renamed vocabulary. I'm not going to keep re-litigating it, but I'd stop calling it noise: a test that needs 2.4s against a 5s limit and shares a machine with 50+ packages will keep doing this, and it is worth its own issue rather than a footnote in every run.


Generated by Claude Code


Generated by Claude Code

@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: a18556e39b

ℹ️ 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 on lines +1117 to +1118
definition: FlowDefinition<TActions, TSession, TRequest, TUser, TOrg, TResources>
): FlowType<TActions, TSession, TRequest, TUser, TOrg, TResources> {

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 Reject the removed work config at runtime

When a plain-JavaScript consumer or a TypeScript caller passing a non-fresh object still supplies work to defineFlow or its instance factory, the narrowed type here does not reject it: normalizedDefinition retains the property, but createFlowInstance silently omits it. The flow is therefore constructed successfully while the lifecycle config—and resources previously collected from its blocks—disappears; add a runtime removed-key guard for both definition and instance options, similar to rejectRemovedMiddleware.

Useful? React with 👍 / 👎.

Comment on lines +30 to +33
const sessionStateSchema = z.object({
reportedSideChainTaskIds: z.array(z.string()).default([]),
reportedBackgroundTaskIds: z.array(z.string()).default([]),
});

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 Test the production legacy-key path

If production drops either reportedBackgroundTaskIds from its schema or the legacy union read, all five regression tests still pass because this file redeclares both pieces instead of importing or executing the pipeline. That leaves the old-session duplicate-reporting bug unprotected despite the test claiming to pin it; export and test the production helper/schema or exercise the actual pipeline.

Useful? React with 👍 / 👎.

Comment on lines +638 to +641
const callee = Node.isCallExpression(parent)
? parent.getExpression().getText()
: undefined;
const opIndex = callee === undefined ? undefined : PATH_BUILDERS.get(callee);

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 Resolve aliased path builders before matching

When a guarded builder is imported under an alias or through a namespace, such as import { blockPathSegment as seg } ...; seg("work", 0) or paths.blockPathSegment("work", 0), getText() yields seg or paths.blockPathSegment, so this exact-name lookup returns no E4 finding. Both calls typecheck and recreate the retired persisted path segment; resolve import aliases or the terminal property name before looking up the operation index.

Useful? React with 👍 / 👎.

Comment on lines +659 to +663
if (Node.isTemplateExpression(node) && inSequencerSrc) {
const head = node.getHead().getLiteralText();
if (/^(work|workIf|forEachBackground):/.test(head)) {
record(node, "E4", `\`${head}\${…}\``);
}

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 Detect interpolated persisted-path templates

A path assembled as extendBlockPath(parent, work[${i}]) produces no finding because this template branch only recognizes the work: default-name form. With a numeric i, that expression typechecks and reconstructs the exact retired persisted segment at runtime, bypassing the completeness gate; recognize the work[${...}] segment shape in path-building positions as well.

Useful? React with 👍 / 👎.

// segment. Same over-reach the segment rule had, found by auditing the
// other pattern-shaped rules after review caught that one rather than
// waiting to be told about this one.
if (/(^|\/|\\\/)(work|workIf|forEachBackground)\\\[(?![a-zA-Z])/.test(source)) {

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 Restrict regex matches to numeric path segments

Any tracked TypeScript file containing an unrelated regex such as /work\[(pending|done)\]/, /work\[[a-z]+\]/, /work\[\w+\]/, or /work\[0\]suffix/ is rejected by the repository-wide typecheck. The current negative-letter lookahead constrains only the first character after [, while persisted segments have the exact numeric op[index] shape; require a numeric matcher or literal followed by a segment boundary.

Useful? React with 👍 / 👎.

…ble to fail (FIX-766)

**`defineFlow` now rejects `work` at runtime, on both call sites.** Removing it
from the types stops a fresh object literal in TypeScript and stops nothing
else: plain JS, and a non-fresh object TS lets through, kept passing `work: {…}`
and watched `createFlowInstance` drop it silently. BP-030 says to reject removed
keys loudly, and `rejectRemovedMiddleware` in this same file is the shape.

The message is precise about the consequence, because the obvious reading is
wrong in both directions. No lifecycle behaviour is lost — those four hooks were
never invoked. What a silent drop takes with it is resources: the hooks WERE
walked for declaration discovery, so a resource declared only on one of them was
registered before and is not now. That is a real behaviour change hiding behind
a dead contract.

**The legacy-key test could not fail.** It mirrored `sessionStateSchema` and
reimplemented the union locally, so deleting the legacy key from production left
all five assertions green — a test pinning a duplicate-announcement bug it could
not have caught, which is CLAUDE.md rule 5 head-on. Its docblock admitted the
mirror; being candid about a test that cannot fail does not make it a test.

The pipeline now exports the schema and the read rule, and the test imports
both. Proven by mutation rather than asserted: dropping the legacy read from
production fails 2 of 6, dropping the legacy key from the schema fails 3 of 6.
Before this change, both mutations left it fully green.

Changeset gains the migration line — `work` throwing is a different story for a
consumer than `work` being ignored.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AvVWQFrLregceP8RPCtjvH

Copy link
Copy Markdown
Collaborator Author

Round 10 in b91c728a. Both behaviour findings taken; the three guard findings left for FIX-1168.

1. defineFlow rejects the removed work key

Removing it from the types stops a fresh object literal in TypeScript and stops nothing else — plain JS, and a non-fresh object TS lets through, kept passing work: {…} and watched createFlowInstance drop it. rejectRemovedWork follows rejectRemovedMiddleware exactly: same shape, same two call sites (definition and options).

The message took the most care, because the obvious reading is wrong in both directions:

Its four hooks were never invoked, so no lifecycle behaviour is lost — but they were walked for resource declaration, so any resource declared only there is no longer registered.

Nobody loses a firing hook; the hooks never fired. What a silent drop takes with it is the resource declarations those blocks contributed. That's a real behaviour change hiding behind a dead contract, which is exactly why "silently ignore" was the wrong default. Three tests: both call sites, plus one asserting the message still names the resource consequence — otherwise it decays to "removed" and the why is lost.

2. The legacy-key test could not fail — fixed by removing the mirror, not moving it

You're right, and the docblock admitting it was the tell. It declared its own sessionStateSchema and reimplemented alreadyReported, so every assertion ran against the test file's own copy. Being candid about a test that cannot fail does not make it a test — and the thing it claimed to pin is a duplicate-announcement bug for every pre-upgrade session.

Took the smaller of the two options: the pipeline now exports reportAcknowledgementSchema and alreadyReportedTaskIds, and the test imports both. The pipeline uses them too, so there is one definition rather than two agreeing.

Mutation-checked against production, both ways:

Mutation (in the pipeline, not the test) Before After
Drop the legacy read from the union 5/5 passed 2 of 6 fail
Drop the legacy key from the schema 5/5 passed 3 of 6 fail

That is the difference between a test and a mirror.

3. Changeset

Added — work throwing is a different migration story than work being ignored. The line says the throw is on both the definition and instance options, that no lifecycle behaviour is lost, and that the resource declarations are the thing to move.

Verification

  • pnpm typecheck 60/60 + all three validators; guard green, --parity OK.
  • core 2009 tests, kitchen-sink 91 tests — both with env -u FSDEV_DEFAULT_MODEL.
  • Changeset refs validator green.
  • Round 9's full suite completed: 57/57 tasks, PNPM_EXIT=0, zero failing tests — including portfolio-backing, which passed that run. That is the first clean full-suite result the branch has had since the push cadence started starving the job, and it covers 354e6b6f/a18556e3.

On the deferrals and the merge gate

I agree with all three deferrals, and with taking this to the gate. The aliased-builder finding is genuinely what the type-aware rewrite is for. The other two — the `work[${i}]` template argument and the loose regex lookahead — are real syntactic gaps that type-awareness will not close, and flagging them as a separate part of FIX-1168 is the right call precisely because someone will otherwise assume the rewrite covered them.

The thing that makes deferral correct rather than convenient: all three are hypothetical. No instance in the tree, guard green, and the realistic route to a retired persisted segment is through the builders, which are covered. The guard fails on main at 407 sites and passes here — it has done the job this rename needed. Chasing the tail of a hand-written AST matcher is unbounded work, and it is not what is holding the first publish.


Generated by Claude Code


Generated by Claude Code

@jhoffner
jhoffner merged commit f56c6b2 into main Aug 15, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Aug 20, 2026
`fix/LAB-133` was rebased/force-pushed before PR #1327 merged, so `main` carries
LAB-133's commits under new SHAs while this branch still carries the originals.
Same changes, two unrelated lineages — which is why the merge base fell back to
`f56c6b216` (PR #1307) and 9 files conflicted across 32 hunks.

Resolution: every conflicted file's main-side contributors are LAB-133 commits
that have a paired equivalent in this branch's lineage. Seven of the eight pairs
are patch-id identical; the eighth (the `sessionState` -> `detached` rename)
differs only because it was applied over LAB-134's larger agent.ts, and its
`detached` usage set is identical to main's. So main contributes no content this
branch lacks, and each hunk kept LAB-134's side — which is main's LAB-133
content plus LAB-134's own work (work recorder, translation, `appliedCount`).

The rename's polarity is unchanged: `detached: true` == the old
`sessionState: false`. The only diff-vs-main touching a `detached` line is a
two-space indentation shift from LAB-134's try/finally wrapper.

Verified: 187/187 claude-code tests pass; `turbo run typecheck --force` 61/61
with 0 cached; diff vs main is LAB-134's work only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MVcrTezeLMBQRVHRg2QX2f
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