Repository navigation
spec(FIX-1786): amend after merge · a session's worker is a readonly field of its starting state - #2858
Conversation
…field of its starting state D3's third change, ER-1, ER-17, the set table, the plan's FIX-1788 row and seam, the end-state POC record and the concept described a server-only "link" field. FIX-1788's P1 (#2850) shipped a readonly field of the session's starting state instead, which the product owner approved on 2026-10-07 (FIX-1788's D5, #2857). The evolution record gains the amendment and the call on D3's count: still six mechanism changes, since the three engine changes build the third; ER-22's escalation came after P1 merged them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
There was a problem hiding this comment.
Simplify / architecture review
The epic text was out of date after FIX-1788 P1 (#2850) shipped a readonly starting-state worker instead of the original server-only session link. This PR mostly does the right thing: a dedicated EVOLUTION.md#amendment-binding section, honest ER-22 timing, and keeping D3 at six mechanisms by treating the three engine primitives as one item (3).
Was a simpler approach available?
Yes, in theory — not clearly better in practice after P1.
| Approach | Tradeoff |
|---|---|
Server-only column on SessionRecord (original D4 / epic wording) |
Narrower API, easier indexed listSessions by worker, no per-turn readonly guard. P1 briefly had SessionRecord.link + ?link= and removed it when the product owner rejected a separate “link” concept. |
Writable state + createCheck only (no .readonly(), no list filter) |
Smallest engine surface, but loses list-by-worker without ad hoc indexes and does not fix immutability without another mechanism. |
What shipped: Zod .readonly() + create check + listSessions({ state }) |
Three general Layer-1 features (escalation after the fact, documented fairly in EVOLUTION). Reuses birthSession, createCheck, and serverOwned instead of a parallel subsystem — good reuse, wider blast radius than a typed column. |
Verdict: Given PO approval and code already on main, ratifying readonly state in the epic is the coherent path. I would not reopen the server-only field unless you are willing to revert P1’s engine work. The main simplification left is spec shape, not the binding model.
What to simplify in this PR (or a tiny follow-up)
- Make
EVOLUTION.md#amendment-bindingthe canonical home for the three engine bullets. D3 Locks in (3) and How it got here now repeat the same paragraph; trim D3 to invariants + pointer (PLAN’s FIX-1788 row already says “with its three engine changes” — good pattern). - Merge order / links: Line 58 points at
FIX-1788/EVOLUTION.md#amendment-binding(#2857). On the PR branch alone that anchor did not exist yet; on currentmainit does after #2857. If these amendments ever land separately again, note “detail in #2857” until the issue spec merges. - Stale sibling artifact (out of diff):
poc/singleton-worker-link/README.mdstill says “server-only session field set at create.” One line pointing at#amendment-bindingwould close the loop. - Optional non-functional note:
listSessionsfiltering on readonly fields is JSON-path equality after owner indexes — fine for MVP, but worth one sentence that callers should always scope byflowId/flowKind+ owner keys; dedicated indexes are a later store concern if session counts explode.
What I would not change
- Renaming mechanism (3) to “session state a caller can’t change after create” — correctly captures “caller sets once at create.”
- Splitting epic vs issue evolution — right altitude; issue record should stay thin and cite the epic section.
- Keeping historical How it got here entries that still say “server-only field” — intentional chronology.
Approval stance
Comment, not blocking: Direction matches shipped code and PO call; remaining items are documentation density and hygiene, not a wrong model. Happy to approve once D3 is shortened (or explicitly deferred to a one-line follow-up PR).
Sent by Cursor Automation: Review For Best Approach
| | **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Six things Workforce cannot fake: a scope key, a row rule, session state a caller can't write, a task ledger kept per conversation ([D6](#d6)), task tools that read their roster per call, since an action is fixed when it is defined ([D8](#d8), T1), and a skills library that takes its key per run, since orchestration keys it by the flow's instance and every worker on a singleton shares that one. The other three are names, not mechanisms. Two are renames ([D7](#d7)): discovery's `seats` domain, a `contracts` constant, becomes `workers`, and a task board's seat, in orchestration's types and the hand-off record core defines, becomes assignee. One is a removal: discovery's `mailboxes` domain goes with the mailbox. So `contracts` still names one Workforce domain, as it named `seats` before; whether Layer 1 keeps that closed list is [FIX-1803](https://linear.app/fixpoint-labs/issue/FIX-1803), FIX-1575's open question. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create persists a caller's session state, so a link held there accepts the caller's own other worker, and a row only flow code writes outlives a deleted session id. No engine rule on org-scope writes (Jake, 2026-10-06): org scope is shared with the org by design, a worker flow may write there if that is how it is built to work, and the framework can't know when org data is relevant. The built-in worker flows, `agent` and the coordinator, keep a worker's own state out of it; a custom worker flow's privacy is its author's, and the contract doesn't check it ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | | ||
| | **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change whose old records are dropped, never read in any org ([D9](#d9), [ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)); (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) session data only the server writes. The worker link takes the form this card's *what would change my mind* anticipated: a server-only field on the session record, set and checked when the session is created, never on a turn; a session's worker can't change, and no action names a worker (Jake, 2026-10-06, on FIX-1788's spec). A coordinator's delegates are held where only the server writes too, and the public create can't seed them. FIX-1788 picks the mechanism and builds it, FIX-1791 consumes it. Flow instances and owner pins stay in the engine untouched, with no deprecation markers, until FIX-1798 removes them ([D9](#d9)). A worker's own key for its private state is Layer 2, FIX-1788's, and so is reading a worker's configuration per run: a generator already resolves its tools per call ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). (4) A task ledger kept per conversation, FIX-1794, a change to the task board that leaves the engine untouched ([D6](#d6)). (5) T1, orchestration's task tools reading their roster per call, FIX-1794 as amended in [#2839](https://github.com/fixpoint-labs/flow-state-dev/pull/2839): generic, naming no worker or delegate ([D8](#d8)). (6) Orchestration's skills library taking its key per run, FIX-1788's S7: a function of the running context the composing layer supplies, the shape of [D6](#d6)'s partition, naming no worker; Workforce supplies the worker's key. And two public renames, both FIX-1796's, with no alias ([D7](#d7)): discovery's `seats` domain becomes `workers` in `MANIFEST_DOMAINS`, and a task board's seat becomes assignee in orchestration's board types and the hand-off record's field. And one public removal, FIX-1792's (its S9, BR-5a): discovery's `mailboxes` domain leaves `MANIFEST_DOMAINS` and core's discovery tool, with no alias. Any other Layer 1 change comes back to this epic | | ||
| | **Because** | Workers, coordinators and workstreams compose what ships: resources, scopes, sessions, projected collections, boards. Six things Workforce cannot fake: a scope key, a row rule, session state a caller can't change after create, a task ledger kept per conversation ([D6](#d6)), task tools that read their roster per call, since an action is fixed when it is defined ([D8](#d8), T1), and a skills library that takes its key per run, since orchestration keys it by the flow's instance and every worker on a singleton shares that one. The other three are names, not mechanisms. Two are renames ([D7](#d7)): discovery's `seats` domain, a `contracts` constant, becomes `workers`, and a task board's seat, in orchestration's types and the hand-off record core defines, becomes assignee. One is a removal: discovery's `mailboxes` domain goes with the mailbox. So `contracts` still names one Workforce domain, as it named `seats` before; whether Layer 1 keeps that closed list is [FIX-1803](https://linear.app/fixpoint-labs/issue/FIX-1803), FIX-1575's open question. [The end-state POC](#what-the-end-state-poc-showed) settled the third: the public create stored a caller's session state unchecked, and as sent when its schema refused it, so a worker named there skipped the check the flow ran later; and a row only flow code writes outlives a deleted session id. What shipped checks the worker in the create itself and fixes it after ([amended after merge](EVOLUTION.md#amendment-binding)). No engine rule on org-scope writes (Jake, 2026-10-06): org scope is shared with the org by design, a worker flow may write there if that is how it is built to work, and the framework can't know when org data is relevant. The built-in worker flows, `agent` and the coordinator, keep a worker's own state out of it; a custom worker flow's privacy is its author's, and the contract doesn't check it ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) | | ||
| | **Locks in** | (1) user data keyed per (user, org) for every flow, FIX-1790, a persisted key change whose old records are dropped, never read in any org ([D9](#d9), [ER-3](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)); (2) "owner writes, org reads" on a row, FIX-1793, new work the 2026-09-23 security lock left for later; (3) session state a caller can't change after create, as FIX-1788's P1 shipped it ([#2850](https://github.com/fixpoint-labs/flow-state-dev/pull/2850)) and the product owner approved it on 2026-10-07. A session's worker is a readonly field of its starting state: the caller names it with `createSession({ state })`, the flow's optional create check confirms it, the engine refuses any later change to it, and sessions can be listed by it. It is named at create, never on a turn; a session's worker can't change, and no action names a worker (Jake, 2026-10-06, on FIX-1788's spec). A coordinator's delegates are server-owned: only the server writes them, and the public create can't seed them. The item took three engine changes it didn't name as first written: a readonly guard on session state, a state filter on listing inside each store, and a refusal at create of a starting state the schema rejects, on flows that bind their sessions. They build this one mechanism, not new ones, and none names a worker: the engine knows readonly fields ([EVOLUTION.md](EVOLUTION.md#amendment-binding)). FIX-1788 picks the mechanism and builds it, FIX-1791 consumes it. Flow instances and owner pins stay in the engine untouched, with no deprecation markers, until FIX-1798 removes them ([D9](#d9)). A worker's own key for its private state is Layer 2, FIX-1788's, and so is reading a worker's configuration per run: a generator already resolves its tools per call ([ER-2](BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)). (4) A task ledger kept per conversation, FIX-1794, a change to the task board that leaves the engine untouched ([D6](#d6)). (5) T1, orchestration's task tools reading their roster per call, FIX-1794 as amended in [#2839](https://github.com/fixpoint-labs/flow-state-dev/pull/2839): generic, naming no worker or delegate ([D8](#d8)). (6) Orchestration's skills library taking its key per run, FIX-1788's S7: a function of the running context the composing layer supplies, the shape of [D6](#d6)'s partition, naming no worker; Workforce supplies the worker's key. And two public renames, both FIX-1796's, with no alias ([D7](#d7)): discovery's `seats` domain becomes `workers` in `MANIFEST_DOMAINS`, and a task board's seat becomes assignee in orchestration's board types and the hand-off record's field. And one public removal, FIX-1792's (its S9, BR-5a): discovery's `mailboxes` domain leaves `MANIFEST_DOMAINS` and core's discovery tool, with no alias. Any other Layer 1 change comes back to this epic | |
There was a problem hiding this comment.
Simplify: Item (3) in Locks in now duplicates EVOLUTION.md#amendment-binding almost verbatim (readonly semantics, the three engine primitives, FIX-1788/1791 ownership, then items 4–6 in the same cell).
Consider keeping D3 (3) to: headline mechanism name, worker/delegate invariants, and a single link to EVOLUTION for the engine trio. PLAN already uses the shorter “with its three engine changes” pattern — mirroring that here would make the “six mechanisms” count scannable without hiding that item (3) absorbed three engine features.
| refuses any later change to it, and sessions can be listed by it. The product owner approved that | ||
| on 2026-10-07 and rejected a separate link concept. FIX-1788's own amendment | ||
| ([#2857](https://github.com/fixpoint-labs/flow-state-dev/pull/2857)) records it as its D5, with | ||
| the issue-level detail in [its evolution record](../../issues/FIX-1788/EVOLUTION.md#amendment-binding). |
There was a problem hiding this comment.
Coordination: This hard-links to FIX-1788/EVOLUTION.md#amendment-binding (#2857). That’s correct on main after #2857 lands; on a branch that only contains this epic amend, the anchor 404s until the issue spec merges.
If you want the epic PR to be self-contained when reviewed alone, a softer phrasing (“issue evolution in #2857”) avoids a broken link during parallel review. Not a model objection — doc ordering only.
|
|
||
| - **A readonly guard on session state.** A top-level `.readonly()` field of a flow's session | ||
| `stateSchema` is refused on any change after create, on every path that writes session state. | ||
| - **A state filter on listing, inside the store.** `listSessions({ state })` filters on readonly |
There was a problem hiding this comment.
Optional spec simplification (non-blocking): The three bullets are the right honest accounting for ER-22. If implementers will hit listSessions({ state }) heavily (Workforce findWorkerSession), one sentence on query shape (always narrow by flow + owner scope before JSON filter) and that readonly fields are not btree-indexed today would prevent treating ?state.workerId= as a free global index. Runtime cost of readonly vs a server column is higher for listing; acceptable at MVP scale per P1 stores.
| | # | Rule | Owner | Checked at | | ||
| |---|---|---|---| | ||
| | ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's link to its worker is set and checked by the server when the session is created, held where only the server writes, and never changes; no caller and no action names a worker ([D3](DECISIONS.md#d3)), and a forged link reads nothing. A worker's private state is keyed by the worker, not the flow; today's per-worker cells are dropped, not moved ([D9](DECISIONS.md#d9)) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure | | ||
| | ER-1 | A worker is a configuration plus an owner, stored as a user-scoped resource. Its configuration names the flow that runs it, any registered worker flow ([ER-2](#what-a-team-gets-and-what-it-doesnt)), and each flow is one singleton shared by every worker that names it. Standard workers are a read-only collection projected from the installation's files; forking one hires a non-standard worker. A session's worker is a readonly field of its starting state. The caller names it when creating the session, the worker flow's create check accepts only a worker that caller can read (their own, or a standard one), and the engine refuses any later change to it; sessions can be listed by it, and no action or message names a worker ([D3](DECISIONS.md#d3)). A forged value is refused at create. A worker's private state is keyed by the worker, not the flow; today's per-worker cells are dropped, not moved ([D9](DECISIONS.md#d9)) | FIX-1788 decides · FIX-1791, FIX-1795, FIX-1792 consume | FIX-1791's and FIX-1795's spec review · the closure | |
There was a problem hiding this comment.
ER-1 is now very long and overlaps D3/CONCEPT on session-worker rules. If you want another simplification pass: ER-1 could state the invariant in one sentence and point at D3 / #amendment-binding for mechanism detail. Not required for this amend to be correct.


The problem
The epic's retained spec, merged in #2795, says a session's worker sits in a server-only "link" field on the session record, beside its state, set and checked when the session is created (D3 item 3, ER-1). That isn't what shipped. FIX-1788's P1 (#2850) binds a session through a readonly field of its starting state, and the product owner approved that on 2026-10-07 and rejected a separate link concept. FIX-1788's own amendment, #2857, records it as that issue's D5 and leaves the epic's text to this PR.
What this does
It changes only
specs/epics/FIX-1786/. Nothing is implemented.createSession({ state }), the flow's optional create check confirms it, the engine refuses any later change to it, and sessions can be listed by it.What's asked of you
The product owner approved the direction on 2026-10-07. This PR records it at epic altitude. Review the record, and merge it if it says what you meant.
Does D3 still count six engine mechanism changes? Recommendation: yes. D3 counts what Workforce can't fake, and all three engine changes build the third of those, session state a caller can't change after create. None names a worker, so "no worker noun in Layer 1" stands. The honest part: item (3) as written named one field, and P1 merged three general engine changes before the epic recorded them. ER-22, the kill line, asks for an escalation before such a change; this one came after, as the product owner's approval. What would change my mind: counting the readonly guard as its own mechanism, because any flow can use it. Then D3 says seven and ER-22's list grows by one. Being wrong either way costs a line of text, not a build.
Sections changed
DECISIONS.md→ D3. Because: "session state a caller can't write" becomes "can't change after create", and the POC sentence on "a link held there" is restated. Locks in (3) is restated as shipped and names the three engine changes.DECISIONS.md→ What the end-state POC showed. "Link" wording replaced; the findings stand as run. Changed notes the shipped form.DECISIONS.md→ How it got here. A new entry. The older entries, including the FIX-1789 gate entry that says "server-only field", stay as written.BUSINESS-RULES.md→ ER-1 (the session's worker, the forged value) and ER-17 ("a worker link" becomes "the session's worker").PLAN.md→ FIX-1788's row and the "session data only the server writes" seam.SPEC.md→ the set table's FIX-1788 row.concept/CONCEPT.md→ the session paragraph, the note after the costs, and security rule 4. Each said "a caller can never supply" the worker.EVOLUTION.md→ a new section, Amended after merge: what changed, what is retained, and the count call above.No figure carried the link, so none changed.
Merge order: after #2857. Two links here point at FIX-1788's D5 and its
#amendment-bindinganchor, which exist only once #2857 lands.Links: original epic review #2795 · FIX-1788 amendment #2857 · P1 #2850 · FIX-1786 · FIX-1788. This merges into
mainwhen the product owner merges it.How to review this
This is a post-merge amendment to a retained epic spec. It records a direction the product owner already approved, so check the record, not the direction.
🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code