Repository navigation
Conversation
…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
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TffUsFtp2vmst6YLcapdCf
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TffUsFtp2vmst6YLcapdCf
There was a problem hiding this comment.
💡 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".
There was a problem hiding this comment.
/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 flatsequencerStateSchema/targetStateSchemas(capability/merge.ts). Worth an explicit note in non-goals or a sharedresolveBlockStateFromConfighelper that also mergesMergedCapabilitySurface.
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
deepEqualare 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.
Sent by Cursor Automation: Review For Best Approach
| 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. |
There was a problem hiding this comment.
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.
| 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). |
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
Consider reusing existing observability gates instead of a bespoke NODE_ENV check:
isTraceObservabilityEnabled()from@flow-state-dev/core(supportsFSDEV_TRACE_OBSERVABILITYoverride)logRuntimeEvent(logger, "warn", "[flow-state] …", …)frompackages/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).
| 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. |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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.
| (~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). |
There was a problem hiding this comment.
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.
| **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. |
There was a problem hiding this comment.
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.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TffUsFtp2vmst6YLcapdCf
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
There was a problem hiding this comment.
💡 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".
…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
There was a problem hiding this comment.
💡 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".
…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
There was a problem hiding this comment.
💡 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".
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
There was a problem hiding this comment.
💡 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".
| "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 |
There was a problem hiding this comment.
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 👍 / 👎.
…tion-phase notes Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TffUsFtp2vmst6YLcapdCf
|
I think we should still use stateSchema ( |
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 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".
| 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 |
There was a problem hiding this comment.
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 👍 / 👎.
| 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. |
There was a problem hiding this comment.
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 👍 / 👎.
| 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). |
There was a problem hiding this comment.
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 👍 / 👎.
| 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). |
There was a problem hiding this comment.
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 👍 / 👎.
|
@codex review |
There was a problem hiding this comment.
💡 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".
| "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. |
There was a problem hiding this comment.
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 👍 / 👎.
| 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. |
There was a problem hiding this comment.
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 👍 / 👎.
| 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. |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
💡 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".
| - **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 → |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
💡 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".
| > 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. |
There was a problem hiding this comment.
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 👍 / 👎.
|
Codex Review: Didn't find any major issues. Keep them coming! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
@codex review |
1 similar comment
|
@codex review |
|
Codex Review: Didn't find any major issues. Bravo. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
Codex Review: Didn't find any major issues. More of your lovely PRs please. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |


Spec PR — not for merge. Reviews the design for FIX-917 before any code is written;
fsd:implement-issuecloses 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:
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.stateSchemastate and then callsctx.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
stateconfig key. Collapse the four top-level keys into a singlestateobject whose sub-keys name the context accessor each one types:state.sub-key)stateSchemastate.ownctx.selfparentStateSchemastate.parentctx.parentsequencerStateSchemastate.sequencerctx.sequencertargetStateSchemasstate.targetsctx.targets/ctx.getTarget()The mapping becomes 1:1 and self-documenting. Only
state.owndeclares 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 callsctx.suspend()on a path where that container will not be checkpointed, emit a dev-modeconsole.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
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.ownsignals ownership by name.4. Focus practices
5. What using it looks like
Accessors unchanged (
ctx.self/ctx.parent/ctx.sequencer/ctx.targets); only the declaration shape moves.Part 2 observable — a handler that writes
ctx.selfthenctx.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
stateconfig key with sub-keysown/parent/sequencer/targets. Rejected: two-key split; keep four keys. Locks in: single public block-state config key, 1:1 declaration→accessor mapping.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.state.own. Locks in: no false positives.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