Skip to content

spec(FIX-1786): amend after merge · a session's worker is a readonly field of its starting state - #2858

Merged
jhoffner merged 1 commit into
mainfrom
spec/FIX-1786-amend-binding
Oct 7, 2026
Merged

jhoffner merged 1 commit into
mainfrom
spec/FIX-1786-amend-binding

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator

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.

  • One mechanism, described as shipped. A session's worker is a readonly field of its starting state. The caller sets 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.
  • A forged value is answered by the create check. A caller can name only a worker the check accepts: their own, or a standard one. A readonly value can't change after.
  • The three engine changes are recorded under D3 item (3): a readonly guard on session state, a state filter on listing inside each store, and a create-time schema refusal on flows that bind their sessions.
flowchart LR
  C["createSession · state · workerId"] --> K["create check · own or standard worker"]
  K --> R["session · workerId readonly"]
  R --> L["listSessions · state · workerId"]
  R -.->|"any later change"| X["refused"]
Loading

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

  1. 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.
  2. DECISIONS.md → What the end-state POC showed. "Link" wording replaced; the findings stand as run. Changed notes the shipped form.
  3. 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.
  4. BUSINESS-RULES.md → ER-1 (the session's worker, the forged value) and ER-17 ("a worker link" becomes "the session's worker").
  5. PLAN.md → FIX-1788's row and the "session data only the server writes" seam.
  6. SPEC.md → the set table's FIX-1788 row.
  7. concept/CONCEPT.md → the session paragraph, the note after the costs, and security rule 4. Each said "a caller can never supply" the worker.
  8. 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-binding anchor, which exist only once #2857 lands.

Links: original epic review #2795 · FIX-1788 amendment #2857 · P1 #2850 · FIX-1786 · FIX-1788. This merges into main when 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

…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
@vercel

vercel Bot commented Oct 7, 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 Oct 7, 2026 9:27pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 7, 2026 9:27pm UTC
flow-state-dev-ui Ignored Ignored Oct 7, 2026 9:27pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 7, 2026

Copy link
Copy Markdown

FIX-1786

@jhoffner
jhoffner marked this pull request as ready for review October 7, 2026 21:42
@jhoffner
jhoffner merged commit ac39e7c into main Oct 7, 2026
18 checks passed

@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 / 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)

  1. Make EVOLUTION.md#amendment-binding the 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).
  2. 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 current main it does after #2857. If these amendments ever land separately again, note “detail in #2857” until the issue spec merges.
  3. Stale sibling artifact (out of diff): poc/singleton-worker-link/README.md still says “server-only session field set at create.” One line pointing at #amendment-binding would close the loop.
  4. Optional non-functional note: listSessions filtering on readonly fields is JSON-path equality after owner indexes — fine for MVP, but worth one sentence that callers should always scope by flowId/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).

Open in Web View Automation 

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 |

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: 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).

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.

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

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.

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 |

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.

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.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants