Skip to content

spec(FIX-1654): Abort fence should compare the request's incarnation, not createdAt - #2415

Merged
jhoffner merged 2 commits into
mainfrom
spec/FIX-1654
Sep 30, 2026
Merged

jhoffner merged 2 commits into
mainfrom
spec/FIX-1654

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
cancels their request just as another user's request takes the freed id, in the same millisecond The cancel lands on the other user's request and stops it The cancel misses: "no such request", and the other request runs on
cancels their request while their own retry hands the record over Told the request does not exist, while it keeps running The cancel is recorded on the request they own
runs a request recorded before incarnations existed Cancel works Cancel works the same way
maintains their own request store Compares a timestamp Compares the request's incarnation; their build breaks until they do

Goal: a cancel lands on exactly the request its owner check read, never on another request that took the id in between, even in the same millisecond, and never misses that request because its own owner's retry rewrote the record, on all four first-party stores, legacy records included.

flowchart LR
  R["the cancel route reads the record"] --> I1["another tenant takes the id · same ms"]
  R --> I2["the owner's retry hands the record off"]
  I1 --> W["the route's conditional write"]
  I2 --> W
  W -->|"404, nothing written · and 202, intent recorded"| P["PASS · on all four stores"]
  C["control · main 70f777def"] -.-> W
  W -.->|"under the control"| F["must FAIL · 202 on theirs · 404 on own"]
Loading

Both interleaves run through the real route and real store writes; only the timing is forced. Check: route cases in abort.test.ts plus fence cases in the request-store conformance suite on memory, filesystem, SQLite and Postgres (PGlite). Control: the POC on main 70f777def, which answers 202 on the other tenant's request and 404 on the owner's. Not over HTTP, because the window sits between two store calls inside one handler: SPEC.md.

Two-by-two grid: today, fenced on createdAt, a same-millisecond reuse takes the cancel and a same-owner hand-off answers 404 while running; after, fenced on the incarnation, the first misses and the second records the cancel

Same route, same interleaves. Today both cells go wrong in opposite directions; the incarnation gets both right.

How: the route passes the incarnation of the record it checked; each store compares it with the stored record's, resolving a legacy record as legacy_<createdAt>, inside the step that already checks status. No schema change.

Sign off

The goal, at that size: both directions, on all four stores, legacy records included. If wrong: a fence that's right for strangers and still tells an owner their running request is gone.

The fence names a request by its incarnation, replacing createdAt outright · D1

Trade-off figure: D1 in DECISIONS.md.

It comes down to the owner's hand-off: any option still comparing createdAt answers 404 there. If wrong: an out-of-tree store author meets a compile error for a window only a same-millisecond reuse opens.

Open: none. D1 is the one to weigh. Reasoning and what lost: DECISIONS.md. The cases: BUSINESS-RULES.md.

Reviewers · look here

  • Decisions → D1. Is replacing the argument (a compile break for out-of-tree stores) right, over an optional field that old stores silently ignore?
  • Plan → S6. Postgres states the legacy rule in SQL rather than calling the helper. Is the conformance legacy case enough to hold the two equal?

Not here: other writers that could use the fence (the stale-request sweep, FIX-1128); how the incarnation is minted (FIX-1286).

POC · the createdAt fence on main, both directions

bash specs/issues/FIX-1654/poc/abort-fence-createdat/run.sh answers: does the createdAt fence fail on main? Both cases pinned today's defect on 70f777def (202 on another tenant's request; 404 on the owner's running one). Throwaway; excluded from default test and typecheck discovery.

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1654 · epic FIX-1635 · builds on FIX-1021 and FIX-1286 · merges after human approval and required checks (contract)

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing the shape of the proposed solution. It is knowingly incomplete, is not real code,
    and is not what will ship. Review it for directional viability only. Do not report
    that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
    wouldn't build: all of that is true on purpose.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it
will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G


Generated by Claude Code

Retained spec set for moving setFieldsIfStatus's identity fence from
createdAt to the incarnation across the memory, filesystem, SQLite and
Postgres request stores, with legacy records resolved as
legacy_<createdAt>. A POC on main shows the createdAt fence failing both
ways: a same-millisecond reuse takes another tenant's cancel, and a
same-owner hand-off makes the owner's own cancel miss.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G
@jhoffner jhoffner added the spec label Sep 29, 2026 — with Claude
@vercel

vercel Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

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

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

Request Review

@chatgpt-codex-connector

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

Copy link
Copy Markdown

Codex Review Summary

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-29T22:52:56.867209Z 9803956 PR opened
ℹ️ 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.

@linear-code

linear-code Bot commented Sep 29, 2026

Copy link
Copy Markdown

FIX-1654

Copy link
Copy Markdown
Collaborator Author

Process guards is red, but not because of this PR. The spec-folder guard fails on main itself because spec/_projects is on main: the log names only that path. It fails on every PR.

No fix for it exists yet. Removing the guard is waiting on the maintainer's decision, so I'm not changing it from here.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Second-look and architecture review of the FIX-1654 spec: no changes requested.

The PR is spec only (+753 lines, all under specs/issues/FIX-1654/). I checked it against origin/main (70f777def) and found nothing that meets the bar for a finding. The plan implies roughly 60–90 lines of code across 4 stores, the route and the conformance suite.

Alternatives I considered and found justified:

  • Replace createdAt outright instead of fencing on both. Keeping both fences would leave the owner hand-off miss in place. It would also add a second notion of "the same request" to the store contract. The POC shows both failure directions on main.
  • Export resolveRequestIncarnation from the engine barrel (S2). store-sqlite and out-of-tree stores are separate packages. Without the export, each would copy the legacy rule and drift. The helper already exists in scope-keys.ts.
  • Postgres restating the rule in SQL (S6). A JS-side comparison would break the atomic step. The legacy conformance cases (V3/V4) keep the two forms equal. The spec is right to reject a new column, index or migration.
  • The POC and the two SVG figures. These are retained evidence under the spec contract. The POC is also the control that must fail on main. The figures repeat some table content, which is worth trimming only as taste, not as a change request.

Architecture note for the implementer, which does not block anything: isSameRequest (packages/engine/src/stores/scope-keys.ts:517) already compares two records' resolved incarnations. Stores probably shouldn't reuse it here, because the fence compares a stored record with a passed-in string, not with another record. Confirm that while implementing and leave a comment if the two should be unified later.


Generated by Claude Code

@jhoffner jhoffner left a comment

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.

FSD Architect — direction lean (not impl).

Approve D1. Merge = Jake’s call.

Approach: Right Hard-gates follow-on to FIX-1021 + FIX-1286. Goal correctly owns both failure directions (same-ms stranger reuse and same-owner hand-off). Route-only was rightly rejected; incarnation mint stays 1286; other writers (stale sweep / FIX-1128) out of scope. POC on 70f777def is the right control.

D1: Replace createdAt with incarnation outright — not optional beside it, not “accept either.” Any leftover createdAt compare keeps BR-3 (owner hand-off → false 404). Dual fence = two identities for “same request,” which FIX-1286 already forbade. Compile break for out-of-tree stores is the honest migration signal; fail-closed for untyped adapters + conformance fence case is correct. Flip condition stands: only a known OOT store we must not break this release would buy an options-field soft land — none is named here.

Soft (S6): Postgres stating the legacy rule in SQL is fine if conformance V3/V4 hold it equal to resolveRequestIncarnation — don’t add a JS path “just to share code.”

Open: none. No D-n, no Linear edit.

@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 (spec FIX-1654)

Verdict: The implementation approach is the right minimal patch, not an over-built design. This is mostly finishing what FIX-1286 already promised (types.ts still documents the fence follow-up) and what FIX-1021 wired: rename the fifth setFieldsIfStatus argument, compare via existing resolveRequestIncarnation on the TS path, mirror that rule once in Postgres SQL, export the helper for out-of-tree stores. Rejected forks (route-only, dual fence, deprecating both number and string, freezing createdAt) are the ones that would either not fix the bug or add a second identity notion.

Where complexity shows up is artifact surface area, not architecture:

  • The same two failure modes (same-ms stranger leak + same-owner hand-off 404) are narrated in SPEC, DECISIONS, PLAN, POC README, and the POC file header. One canonical story plus pointers elsewhere would shrink the diff without weakening sign-off.
  • figures/what-changes.svg largely duplicates the "Four people" table and the short prose under What changes; I'd keep either the table or that figure for gate readers.
  • DECISIONS carries three views of dropped options (mermaid dashed edges, D1 "Instead of", and the table). Two is enough.
  • The retained POC and run.sh copy pattern match FIX-1286 and are justified: today's abort.test.ts interleave at different createdAts (1_000 vs 2_000) does not exercise BR-1; the POC's equal-createdAt cases are the real red control.

At implement time (optional trim, not blocking): V3's full legacy matrix in conformance is the main "could be smaller" knob—request-incarnation.test.ts already pins derivation; you could lean on it and keep conformance to the two fence interleaves if you want less duplication. I'd only do that if you're confident Postgres SQL drift cannot slip past route tests.

No third-party package buys anything here; this is a contract-aligned string compare and a SQL COALESCE aligned with code you already own.

Approving direction for merge; inline notes are editorial simplifications you can take or leave before or during implementation.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1654/SPEC.md Resolved
Comment thread specs/issues/FIX-1654/SPEC.md Resolved
Comment thread specs/issues/FIX-1654/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1654/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1654/PLAN.md Resolved

@jhoffner jhoffner left a comment

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 owner approval / not the gate. Shared jhoffner login — this is FSD Architect coherence only. Direction merge still needs human product-owner sign-off and required checks.

Coherence: clean. Sole open issue-spec for FIX-1654. Complements merged FIX-1286 (#2400 → 70f777def, which named this fence follow-up) and merged FIX-1021 (#2387, which landed the createdAt fence). No competing open stream on abort-fence / expectedCreatedAt → incarnation. FIX-1128 and FIX-1647 stay correctly out of scope. D1 (replace createdAt outright) matches FIX-1286's identity lock: keeping both fences would leave the owner hand-off miss. POC control pinned to that same main commit is the right bar.

Soft (does not block direction): Linear nests FIX-1654 under FIX-1635, but the locked children list on the epic body / never-merge epic-spec #2360 does not name it yet (unlike Jake's 1647/1648 AuthZ expansions). If this is a hard-gates child, fold it into the epic set on #2360 + Linear; if it is remainder debt outside the release proof, un-nest. Also: Linear still shows FIX-1286/FIX-1021 as In Review — status lag only; both are on main.

No two-direction fork. No Jake ping from this watch.

@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: 9803956ae8

ℹ️ About Codex in GitHub

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

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

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

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

Comment thread specs/issues/FIX-1654/DOCS.md Resolved
Comment thread specs/issues/FIX-1654/PLAN.md Resolved
Comment thread specs/issues/FIX-1654/PLAN.md Resolved
…ntegration scenario

Folds the Codex review on 9803956: the cancel route's in-process fire is
fenced by incarnation too (the registry tags each controller), SQLite keeps
the legacy rule local to respect its type-only engine boundary, and a
runAction scenario in integration-tests joins the checks. Cursor's six
editorial nits are recorded verbatim in PLAN -> Notes from review.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants