Skip to content

spec(FIX-917): Block state fast-follows — consolidate the 4-key schema surface, warn on silent suspend-reset - #866

Open
jhoffner wants to merge 5 commits into
mainfrom
spec/FIX-917
Open

jhoffner wants to merge 5 commits into
mainfrom
spec/FIX-917

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Spec PR — not for merge. Reviews the design for FIX-917 before any code is written; fsd:implement-issue closes this unmerged when implementation starts. Spec doc: docs/specs/FIX-917.md.

Two independent fast-follows from the FIX-914 (block-level state) PR review. They ship together because they touch the same surface (block state), but each stands alone.


Part I — The Case

1. Problem — why it matters, why now

FIX-914 gave any block its own request-scoped state and unified the runtime onto one container. Two rough edges surfaced in that PR's review and were deferred as non-blocking follow-ups:

  1. The declaration surface is still fragmented. A block declares state-schema intent through four separate top-level config keys — stateSchema, parentStateSchema, sequencerStateSchema, targetStateSchemas — even though the runtime now resolves all four over one container mechanism. Four keys for one concept is the main remaining complexity after the runtime unification, and leaving it un-consolidated risks the fragmentation ossifying as more code is written against it.
  2. State loss on suspend is silent. A non-sequencer block (handler / generator / router) that writes its own stateSchema state and then calls ctx.suspend() loses that state on resume — the container is re-created from schema defaults with no error, no warning, no log line. For the FIX-911 use case this unblocks (a generator accumulating loaded skills across a tool loop), that reads as "it silently forgot everything."

Why now. The keys and the suspend behaviour are days old (FIX-914 just landed), so the config surface has almost no external consumers yet — the cheapest moment to consolidate it is before more code depends on the four-key shape. The silent reset is a correctness/observability gap; a warning is a small, self-contained guard until the durable-checkpoint follow-up (out of scope) lands.

2. Solution in plain terms

Part 1 — one state config key. Collapse the four top-level keys into a single state object whose sub-keys name the context accessor each one types:

Today (top-level key) Becomes (state. sub-key) Types the accessor
stateSchema state.own ctx.self
parentStateSchema state.parent ctx.parent
sequencerStateSchema state.sequencer ctx.sequencer
targetStateSchemas state.targets ctx.targets / ctx.getTarget()

The mapping becomes 1:1 and self-documenting. Only state.own declares a store this block owns; the other three declare the expected shape of state owned elsewhere that this block reads/writes through a typed accessor.

Part 2 — warn on silent suspend-reset. When a non-sequencer block whose own (state.own) container has been written to calls ctx.suspend() on a path where that container will not be checkpointed, emit a dev-mode console.warn (and a trace note) naming the block and the state that will be lost on resume.

Philosophy. Tenet 2 (more impactful without getting bigger): Part 1 removes surface — four keys become one — while the runtime stays exactly as unified as FIX-914 made it. Tenet 1 (coherence): a config surface that fragments a concept the runtime unified is incoherent; this realigns them. Tenet 3 (subtraction is part of the change): the deliverable is a net removal of public keys.

3. Tradeoffs & alternatives

  • Two-key split (stateSchema + readsState: { parent, sequencer, targets }) — semantically honest about ownership but keeps two top-level keys and maps less cleanly to the four accessors. Rejected; state.own signals ownership by name.
  • Do nothing / just document — rejected: review explicitly flagged ossification risk, and the near-zero-consumer window is closing.
  • Part 2 throw instead of warn — breaks a legitimate pattern and regresses a path that "works" today. A warning is the right altitude until durable checkpointing lands.
  • Genuine complexity: (a) backward-compat policy for the four legacy keys (Decision 2); (b) Part 2's "will this container be checkpointed?" predicate without false-positive noise.

4. Focus practices

  • BP-030 (tolerate old shape) governs Decision 2 (dual-read vs. hard rename).
  • BP-035 (second-path checklist) — Part 2 is a suspend/resume second-path fix; walk cancel/error and the warning's off state.
  • BP-007 / BP-034 — the four keys are documented public config; finish the rename across docs/READMEs/JSDoc, not just types.
  • Change-specific: the warning is dev-only and side-effect-free — never fires in production, never alters control flow.

5. What using it looks like

// BEFORE (FIX-914 four-key surface)
generator({
  name: "loader",
  stateSchema: z.object({ loaded: z.array(z.string()).default([]) }),
  sequencerStateSchema: z.object({ turn: z.number() }),
});

// AFTER (FIX-917 consolidated surface)
generator({
  name: "loader",
  state: {
    own: z.object({ loaded: z.array(z.string()).default([]) }),
    sequencer: z.object({ turn: z.number() }),
  },
});

Accessors unchanged (ctx.self / ctx.parent / ctx.sequencer / ctx.targets); only the declaration shape moves.

Part 2 observable — a handler that writes ctx.self then ctx.suspend() now emits a dev warning naming the state that will be lost on resume (instead of silently resetting to defaults).

6. Decisions & rules — the sign-off surface

  1. One state config key with sub-keys own/parent/sequencer/targets. Rejected: two-key split; keep four keys. Locks in: single public block-state config key, 1:1 declaration→accessor mapping.
  2. Hard rename, no dual-read — contingent on confirming zero external consumers. Rejected: BP-030 dual-read + deprecation. Ramification: no legacy-shape debt, but any out-of-repo consumer breaks. Primary decision needing human sign-off — if an external consumer exists, fall back to dual-read.
  3. Part 2 is a dev-mode console.warn + trace note, not a throw and not a persist. Rejected: throw; silently persist. Locks in: zero happy-path behaviour change; persistence is the separate durable-checkpoint follow-up.
  4. Warning fires only when own-state is dirty AND uncovered by a checkpoint. Rejected: warn on every suspend from a block with state.own. Locks in: no false positives.
  5. Warning is production-gated and side-effect-free. Rejected: always-on log.

Non-goals. Durable checkpoint/persistence for non-sequencer block state (the real fix for #2). Capability-contributed own-state schema merging (FIX-911 PR2 seam). Any change to the four context accessors themselves.

Size estimate. Medium (multi-file, one PR, ~150–350 LOC). Splittable into two PRs along the two parts; Part 1 is larger, Part 2 is self-contained.


Part II (technical design, implementation sequence, edge cases, testing, docs plan, open questions) is in the spec doc: docs/specs/FIX-917.md.

Linear: https://linear.app/fixpoint-labs/issue/FIX-917


Generated by Claude Code

…rface, warn on silent suspend-reset

Versioned spec for FIX-917 (docs-only, BP-022 no changeset). Two fast-follows
from the FIX-914 block-level-state PR review:

1. Consolidate the four top-level state-schema config keys (stateSchema /
   parentStateSchema / sequencerStateSchema / targetStateSchemas) into a single
   `state` object whose sub-keys (own/parent/sequencer/targets) map 1:1 to the
   ctx.self / ctx.parent / ctx.sequencer / ctx.targets accessors. Config-layer
   remap only; runtime container mechanism unchanged.
2. Warn (dev-mode console.warn + trace note) when a non-sequencer block with
   dirty own state suspends on a path where that state will not be checkpointed
   — turning today's silent reset into an observable one until durable
   block-state checkpointing lands.

Primary open decision for human sign-off: hard rename vs. BP-030 dual-read for
the four legacy keys.

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

linear-code Bot commented Jul 23, 2026

Copy link
Copy Markdown

FIX-917

@vercel

vercel Bot commented Jul 23, 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 Jul 23, 2026 2:10am
flow-state-dev-kitchen-sink Ignored Ignored Jul 23, 2026 2:10am
flow-state-dev-ui Ignored Ignored Preview Jul 23, 2026 2:10am

jhoffner pushed a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TffUsFtp2vmst6YLcapdCf
@jhoffner
jhoffner marked this pull request as ready for review July 23, 2026 01:25
jhoffner pushed a commit that referenced this pull request Jul 23, 2026

@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: 64059c4d2d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md Resolved
Comment thread docs/specs/FIX-917.md Resolved

@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-917 spec

This PR is spec-only (adds docs/specs/FIX-917.md), so this review focuses on whether the proposed implementation approach is the simplest path to the stated goals, not runtime code.

Verdict

The two-part split is sound and well-scoped. Part 1 (four keys → one state object with accessor-aligned sub-keys) is a clear author-facing win and matches consolidation precedent (FIX-435 flat resources). Part 2 (dev warning on silent suspend-reset) is the right altitude until durable checkpointing lands.

I would not call the current plan the simplest possible end state, though. The main complexity risks are (a) introducing a nested config shape while keeping four flat runtime fields indefinitely, and (b) Part 2's checkpoint-coverage predicate before its semantics are pinned. Those are addressable in the spec before implementation without changing the core goals.

What looks good

  • Problem framing and "why now" (pre-ossification window) are crisp.
  • The state.own / parent / sequencer / targets → accessor mapping is self-documenting.
  • Tradeoffs and rejected alternatives are recorded with rationale (two-key split, throw-on-suspend, always-on log).
  • Non-goals correctly defer durable checkpointing and capability own-state merge.
  • Splittable into two PRs along Part 1 / Part 2.
  • Testing split (type-tests vs targeted warn spy) is appropriate.

Simplification opportunities (recommended before/during implementation)

1. Config/runtime dual shape (§7, lines 240–245)

Part 1 subtracts public keys but keeps four internal runtime fields via buildBlock normalization. That's pragmatic for a fast-follow, but it trades one fragmentation for another unless it's explicitly temporary. Consider either pushing config.state through to the engine in the same change, or documenting a follow-up to delete the flat runtime surface once migration is done.

2. Part 2 v1 predicate is the hardest part and still open (§7 lines 257–267, §12 Q3)

The dirty + non-sequencer + checkpoint-coverage walk is where false positives/negatives live, and checkpoint coverage is still an open question. A simpler v1 might be: warn when own-state is dirty and caller is non-sequencer, without the ancestor walk — accept a possible false positive inside a checkpointed sequencer until coverage semantics are nailed. That ships observability faster with less bespoke predicate code. If the full predicate is kept, pin the coverage rule in the spec with a table-driven case matrix from sequencer-checkpoint before coding.

3. Reuse existing observability plumbing (§7 lines 269–273)

The spec proposes raw process.env.NODE_ENV !== "production" + console.warn. The repo already has isTraceObservabilityEnabled() (packages/core/src/helpers/trace-observability.ts) and logRuntimeEvent with the [flow-state] prefix (packages/engine/src/execution/logging.ts). Aligning Part 2 with those avoids a one-off gate and keeps DevTool/CLI filtering consistent. Also note: DEFAULT_RUNTIME_LOGGER suppresses console in NODE_ENV=test — the spec should state expected test behavior.

4. Dirty detection: prefer O(1) signal over per-suspend deepEqual (§7 lines 261–263)

normalizeStateDefault + deepEqual on every real suspend is workable but wasteful. StateContainer.getVersion() bumps only on committed mutations (state-container.ts). A cheap prefilter (version === 0 → not dirty) before any deep compare would keep the predicate off hot replay paths and avoid recomputing schema defaults. Place the check after replay/resume early-returns in the suspend closure (~2657–2710), not at the top.

5. Defer optional DevTool trace note to v1 follow-up (§7 lines 271–273)

console.warn (or logRuntimeEvent) is the stated deliverable. A new "state_change-adjacent annotation" is a second channel with undefined shape — reasonable follow-up once the message format stabilizes.

6. Close open decisions in §6 before implementation

  • Decision 2 (hard rename): Treat the external-consumer check (step 4) as a gate before coding, not a parallel implementation branch in the same PR. If any published consumer exists, scope changes materially (BP-030 dual-read).
  • Sequencer state.own (§12 Q2): Still "recommended" but undecided — weakens the one-entry-point story. Pick yes/no at sign-off.
  • Capability asymmetry: Blocks move to state.* but capabilities keep flat sequencerStateSchema / targetStateSchemas (capability/merge.ts). Worth an explicit note in non-goals or a shared resolveBlockStateFromConfig helper that also merges MergedCapabilitySurface.

7. Line-number / dependency hygiene

The spec assumes FIX-914 is landed (parentStateSchema, ctx.self, etc.). On current main those APIs don't exist yet (handlers still expose scope-level requestStateSchema / sessionStateSchema). Re-validate all cited paths and line numbers against the FIX-914 branch at implementation time.

Skipped (reasonable as-is or out of scope)

  • Third-party packages: Zod + in-repo deepEqual are appropriate; no new deps needed.
  • Throw-on-suspend: correctly rejected.
  • Durable checkpointing: correctly deferred.
  • Consolidating handler scope keys (requestStateSchema, etc.) — different concept from block-level state; correctly out of scope.

Summary

Approve the direction; tighten the spec around Part 2's v1 scope, observability reuse, and the config/runtime shape story before implementation starts. None of this blocks merging the spec itself — these are recommendations to keep the eventual implementation closer to "medium ~150–350 LOC" than an open-ended predicate + dual-shape maintenance burden.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/specs/FIX-917.md
required for Part 1** — the runtime container mechanism in
`createExecutionContext.ts` (`_withExecutionScope`, ~2782) keeps reading
`resolvedParent.stateSchema`. The consolidation is a config-layer remap; the runtime
contract is unchanged.

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.

Simplification note: Normalizing config.state back into flat stateSchema / parentStateSchema / etc. keeps the engine unchanged, but it means Part 1 only simplifies the author-facing surface — the runtime still carries four fields indefinitely.

Consider either (a) documenting this as explicit temporary debt with a follow-up to make the engine read config.state directly, or (b) extending Part 1 to one shape end-to-end. Without that, "four keys → one key" is config-only subtraction.

Comment thread docs/specs/FIX-917.md Resolved
Comment thread docs/specs/FIX-917.md
2. `parentChain.parent.stateSchema !== undefined` (block declared own state).
3. The container is **dirty** — its current value differs from
`normalizeStateDefault(stateSchema)` (deep-equal against defaults; reuse the shared
`deepEqual` util per CLAUDE.md coding conventions).

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.

Per-suspend normalizeStateDefault(stateSchema) + full deepEqual works but is heavier than necessary. StateContainer.getVersion() is O(1) and only bumps on committed mutations.

Also: run this check after the replay-log and resume-context early-returns in the suspend closure (~2657–2710 in createExecutionContext.ts), not at the top — otherwise replay-heavy flows pay the cost on every ctx.suspend() re-entry.

Comment thread docs/specs/FIX-917.md
ancestor sequencer checkpoints, the state may survive via that path — do not warn.
Confirm the exact checkpoint-coverage rule against `sequencer-checkpoint` behaviour.)

When all hold, and `process.env.NODE_ENV !== "production"`, `console.warn(...)` with a

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.

Consider reusing existing observability gates instead of a bespoke NODE_ENV check:

  • isTraceObservabilityEnabled() from @flow-state-dev/core (supports FSDEV_TRACE_OBSERVABILITY override)
  • logRuntimeEvent(logger, "warn", "[flow-state] …", …) from packages/engine/src/execution/logging.ts

This keeps Part 2 consistent with trace/state_snapshot gating elsewhere. Worth noting expected behavior under NODE_ENV=test (logger suppresses console there).

Comment thread docs/specs/FIX-917.md
message naming the block, the dirty top-level keys, and a pointer that durable
block-state checkpointing is not yet implemented. Optionally emit a trace note adjacent
to the existing suspend trace (a `state_change`-adjacent annotation) so it is visible in
DevTool, not just stdout — keep this behind the same dev gate.

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.

Suggest deferring the optional DevTool trace note to a follow-up. console.warn / logRuntimeEvent is the core deliverable; a new "state_change-adjacent annotation" is a second channel with undefined shape and adds scope to Part 2.

Comment thread docs/specs/FIX-917.md
warning).
- *Ramification:* no legacy-shape debt carried forward, but any out-of-repo consumer
of the four keys breaks. **This is the primary decision needing human sign-off** —
if any published/external consumer exists, fall back to dual-read + deprecation.

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.

Decision 2's dual-read fallback (BP-030) is a materially different implementation path. Recommend treating step 4 (confirm zero external consumers) as a hard gate before any coding, not a branch within the same PR. If consumers exist, Part 1 scope and LOC estimate change significantly.

Comment thread docs/specs/FIX-917.md
(~406). NOTE: a sequencer *owns* state via `stateSchema`; it does not read a parent
the same way. Decide whether the sequencer surface also moves to `state.own` for
consistency (recommended) — this is the "3 of 4 factories" the issue references
(the sequencer already has a distinct declaration path).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is still open in §12 Q2 but it affects whether Part 1 truly delivers "one entry point." Recommend resolving at sign-off: if yes, make sequencer state.own required in the migration checklist; if no, document why sequencers stay on a distinct path.

Comment thread docs/specs/FIX-917.md
**Non-goals.** Durable checkpoint/persistence for non-sequencer block state (the real
fix for #2). Capability-contributed own-state `stateSchema` merging (FIX-911's PR2 seam
— needs `extendSchema` duplicate-field collision detection first). Any change to the
four context accessors themselves.

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.

Worth an explicit note: after Part 1, blocks declare state via state.* but capabilities still expose flat sequencerStateSchema / targetStateSchemas (MergedCapabilitySurface in capability/merge.ts). Not blocking, but authors will see two shapes. Either document the asymmetry or add a resolveBlockStateFromConfig(config, mergedSurface?) helper that merges both in one place.

jhoffner pushed a commit that referenced this pull request Jul 23, 2026
Decision 2's hard-rename removes public config keys, a breaking change;
BP-022 (pre-1.0) reserves `minor` for breaking changes and `patch` for
non-breaking. Dual-read fallback stays `patch`.

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

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

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md Resolved
…heckpoint-coverage walk

Two independent reviewers (Codex r3635010743, Cursor r3634992918) converged: the
ancestor/checkpoint-coverage walk is a false negative on the common HITL path — a
sequencer checkpoint persists only ctx.sequencer.state, not a child block's own
state.own container. Adopt the simpler predicate (dirty own-state + non-sequencer
caller, no coverage walk), accepting a rare harmless false positive to never produce
a false negative. Resolve §12 Q3, update Decision 4, and sync §3/§8/§9 references.

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

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

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md Resolved
…untime (BP-030)

Codex r3635062826: removing the four legacy keys at the TS type level only
leaves JS callers, stale compiled consumers, and TS excess-property escapes
able to pass them; buildBlock normalizes only config.state.*, so a stray
legacy key would be silently ignored -> silent state loss. Spec now mandates
a runtime dead-key throw in buildBlock even on the hard-rename path.

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

@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: 0fb2c3284c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md Resolved
Part 2 predicate excluded ALL sequencer callers on the assumption they
are checkpointed. A sequencer with durable:false emits no state_snapshot,
so a dirty non-durable sequencer that suspends silently resets its own
state — the exact false negative the spec promises never to produce.

Widen the predicate: warn when own-state is dirty AND the caller is not
covered by its own checkpoint (non-sequencer, OR durable:false sequencer).
Local O(1) read of the caller's own `durable` flag — no ancestor walk.
Updated §7 predicate, §6 Decision 4, §9 edge-case table, §8 step + test,
and the §2/§3/§12 restatements for coherence.

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

@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: 0367a63f37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md
Comment on lines +192 to +195
"Not covered by its own checkpoint" = a non-sequencer block, **or** a sequencer with
`durable: false` (which emits no `state_snapshot`, so its own state also resets on
resume). A default (durable) sequencer is the only caller excluded, because it
checkpoints its own `ctx.sequencer.state`. This is a local, O(1) read of the caller's

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 Cover transient slots in sequencer suspend warnings

When a default durable sequencer uses transientSlot() in its state.own schema and mutates that slot before ctx.suspend(), this exclusion suppresses the warning even though the checkpoint path explicitly strips transient keys before writing state_snapshot; the architecture contract says those fields never enter the durable checkpoint store and reset to schema defaults on resume (docs/architecture/state-and-scopes.md:64-68, packages/core/src/blocks/sequencer.ts:285-290). Please include dirty transient slots in the predicate/tests or explicitly scope them out, otherwise the spec still leaves a supported silent-reset path.

Useful? React with 👍 / 👎.

jhoffner pushed a commit that referenced this pull request Jul 23, 2026
…tion-phase notes

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TffUsFtp2vmst6YLcapdCf
@jhoffner jhoffner added the spec label Jul 23, 2026
@jhoffner

Copy link
Copy Markdown
Collaborator Author

state.own vs ctx.self. Should just be .self for both.

I think we should still use stateSchema (stateSchema: { self: z.object(...) }) so that its clear its a schema.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

Codex Review Summary

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-31T22:58:23.477402Z 0367a63 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@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: 0367a63f37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md
Comment on lines +150 to +156
ctx.self?.push("items", input.value); // own state now dirty
await ctx.suspend({ reason: "await-approval" });
// ^ dev console.warn: [flow-state] block "accumulate" suspended with
// non-empty own state ({items}) that will NOT survive resume — its
// container re-initializes to schema defaults. (durable block-state
// checkpointing: not yet implemented.)
return ctx.self?.get("items"); // after resume: [] (reset), now visible

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 state-ref API in the example

The example calls nonexistent ctx.self.push(...) and ctx.self.get(...) methods. Block state accessors use the StateRef contract: mutations go through operations such as pushState("items", value), while values are read from ctx.self.state.items. As written, the example will not type-check and gives implementers incorrect usage for the newly renamed surface.

AGENTS.md reference: AGENTS.md:L137-L139

Useful? React with 👍 / 👎.

Comment thread docs/specs/FIX-917.md
Comment on lines +296 to +305
when the caller is a non-sequencer block (`kind !== "sequencer"`), **or** when it is a
sequencer that opted out of checkpointing (`kind === "sequencer"` **and**
`durable === false`). A default (durable) sequencer is excluded because it checkpoints
its own `ctx.sequencer.state`; a `durable: false` sequencer is **not** checkpointed
(opt-out at `packages/core/src/blocks/sequencer-methods.ts` ~393–403 — no
`state_snapshot` is emitted when `durable` is false), so a dirty non-durable sequencer
that suspends would silently reset its own state on resume — the exact false negative
this warning exists to prevent. This is a **local, O(1) read of the caller's own
`durable` flag** — it does NOT reintroduce the ancestor-checkpoint-coverage walk (see
below); it inspects only the calling block itself.

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 Thread the durability flag to the suspend seam

Fresh evidence after the earlier durable: false fix is that the proposed seam cannot perform this local read: ExecutionParent has no durable field, and both _withExecutionScope callers omit it; moreover, the sequencer factory resolves config.durable ?? true only into a closure local rather than the built block config. The build plan therefore needs to add and populate this runtime field (or specify another real source), otherwise the predicate cannot distinguish non-durable sequencers and the previously identified false negative remains.

AGENTS.md reference: AGENTS.md:L137-L139

Useful? React with 👍 / 👎.

Comment thread docs/specs/FIX-917.md
Comment on lines +283 to +289
Seam: the per-scope `suspend` closure in
`packages/engine/src/context/createExecutionContext.ts` (~2636). At suspend time the
calling scope node is available as `parentChain?.parent` (the block that called
`ctx.suspend()`), and its state container as `parentChain?.parentStateContainer` (the
container created in `_withExecutionScope` at ~2782, named `parentStateContainer` for
legacy reasons — it is the *calling block's own* container from the perspective of this
closure).

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 Place the warning after resolved-resume short-circuits

The existing suspend closure first checks the replay log and resume context and can return previously resolved data without throwing a new suspension. Because the plan only says to add the predicate somewhere in this closure, a straightforward implementation will also warn when a resumed block re-reaches an already resolved gate, even though that invocation neither suspends nor loses its current state. Specify that the warning runs immediately before the new SuspensionError is thrown, and add a resume-path test that prevents a duplicate false warning.

Useful? React with 👍 / 👎.

Comment thread docs/specs/FIX-917.md
Comment on lines +306 to +308
3. The container is **dirty** — its current value differs from
`normalizeStateDefault(stateSchema)` (deep-equal against defaults; reuse the shared
`deepEqual` util per CLAUDE.md coding conventions).

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 Compare against the captured initial state

Re-running normalizeStateDefault(stateSchema) at suspension does not reliably detect mutation because Zod defaults may be functions, such as a generated ID or timestamp. An untouched container initialized from one evaluation will differ from the second evaluation and trigger the warning, contradicting the promised clean-state behavior. Capture the normalized initial value when the container is created, or use the container's mutation/version signal, instead of evaluating defaults again.

Useful? React with 👍 / 👎.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: 0367a63f37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md
Comment on lines +192 to +196
"Not covered by its own checkpoint" = a non-sequencer block, **or** a sequencer with
`durable: false` (which emits no `state_snapshot`, so its own state also resets on
resume). A default (durable) sequencer is the only caller excluded, because it
checkpoints its own `ctx.sequencer.state`. This is a local, O(1) read of the caller's
own `durable` flag, not a walk.

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 Account for state changed inside the suspending step

Do not categorically exclude every default-durable sequencer: when a sequencer mutates ordinary own state and calls ctx.suspend() from the same operation, packages/core/src/blocks/sequencer.ts emits the durable snapshot only after operation.run returns, so the suspension jumps to the catch before that checkpoint; its terminal frame is also not written as a new checkpoint by runAction. The prior checkpoint therefore lacks the mutation, yet this predicate suppresses the warning. Compare against the last checkpointed state or checkpoint immediately before throwing rather than treating durable !== false as complete coverage.

Useful? React with 👍 / 👎.

Comment thread docs/specs/FIX-917.md
Comment on lines +336 to +341
1. **Add `BlockStateConfig` type + `state` field to the four factory config
interfaces** (`handler.ts`, `generator.ts`, `router.ts`, `sequencer-methods.ts`).
Wire the internal generics to source from `config.state.*`. *Test:* type-tests in
`packages/core/src/types/tests/` (extend `sequencer-state-schema-bubbling`,
`targets`, `flow-state-inference`) compile with the new shape and infer the same
`ctx.*` types. *Modify;* no new files.

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 per-subkey state defaults in withDefaults

Add an explicit migration for handler.withDefaults: its current runtime merge is { ...defaults, ...config }, so if defaults provide state: { sequencer: ... } and an individual handler provides state: { own: ... }, the latter replaces the entire nested object and silently drops the sequencer declaration; today's separate top-level keys compose independently. The plan should require a per-subkey merge, corresponding generic handling, and a test combining default and per-handler state declarations.

Useful? React with 👍 / 👎.

Comment thread docs/specs/FIX-917.md
Comment on lines +328 to +332
When all hold, and `process.env.NODE_ENV !== "production"`, `console.warn(...)` with a
message naming the block, the dirty top-level keys, and a pointer that durable
block-state checkpointing is not yet implemented. Optionally emit a trace note adjacent
to the existing suspend trace (a `state_change`-adjacent annotation) so it is visible in
DevTool, not just stdout — keep this behind the same dev gate.

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 Specify a real trace emission path

Replace this optional, undefined “trace note” with a concrete existing event/API or remove it from Decision 3: the item/event taxonomy has no trace-note or state-change annotation surface, and the implementation sequence only requires console.warn, despite earlier sections promising DevTool visibility. As written, implementations can silently omit a signed-off deliverable or invent an incompatible trace shape; specify whether this is an existing debug event and how DevTool consumes it, including a test.

AGENTS.md reference: AGENTS.md:L137-L139

Useful? React with 👍 / 👎.

@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: 0367a63f37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md
Comment on lines +415 to +419
- **Changeset (BP-022):** the Decision 2 **hard-rename removes public config keys and breaks
legacy type-checking → `minor`** (pre-1.0: `minor` covers breaking changes, `patch` is
non-breaking only; `docs/contributing/best-practices.md` BP-022). Note the four-key → `state`
migration in the fragment. If the Decision 2 **dual-read fallback** is chosen instead (both
shapes accepted, old shape deprecation-warns, nothing removed), that path is non-breaking →

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 Include the engine package in the changeset

The changeset plan assigns a bump only for the core config rename, but Part 2 also changes observable behavior in the publishable @flow-state-dev/engine package by adding a runtime warning. Following this plan could therefore release the engine change without corresponding release metadata; specify both package entries (core minor for the hard rename and engine patch for the warning).

AGENTS.md reference: AGENTS.md:L31-L35

Useful? React with 👍 / 👎.

@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: 0367a63f37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/specs/FIX-917.md
Comment on lines +6 to +8
> Two independent fast-follows from the FIX-914 (block-level state) PR review.
> They ship together because they touch the same surface (block state), but each
> stands alone and could be split into its own PR — see §6 size estimate.

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 Lead with the required plain-language summary

Replace this opening with the required 2–4 sentence plain-language solution summary before the detailed case. The current lead discusses “fast-follows,” FIX-914, block state, and PR structure without explaining what will change or why to a non-expert; readers do not reach the actual solution until §2. The repository explicitly treats the active best practices as implementation standards with higher authority than AGENTS.md, and BP-039 requires that summary at the beginning of every spec.

AGENTS.md reference: AGENTS.md:L7-L14

Useful? React with 👍 / 👎.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: 0367a63f37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

1 similar comment
@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 0367a63f37

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

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 0367a63f37

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants