Repository navigation
spec(FIX-1790): use the glossary terms worker, user and flow - #2816
Conversation
Post-merge amendment to the retained spec merged in #2810. The epic glossary (FIX-1786) retires "seat" and "hired seat"; Jake asked on #2810 for one name per thing. Prose, the docs draft, the cells figure and POC comments now say "worker" / "hired worker". Headings of today's docs pages and EVOLUTION quotes of FIX-1538 stay verbatim. No direction or rule changes. 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
|
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. |
|
Second-look review (automated, for the picking-up agent) Verdict: approach is right; no changes required. A terminology-only swap is the correct size for this ask, and I found no unintended meaning change. Checked on head
One suggestion (not blocking), on scope: the same glossary retires "person" (say user) and "kind" (say flow). The spec still has about 86 "person" lines across the six prose files. Jake's rule on #2810 was "one name for something wherever possible", and ER-25 asks for the new terms. Doing "person" in a second follow-up costs another review round on a spec that is already merged. Options:
I'd take option 2. This PR is easy to approve at its current size, and mixing in the key-notation cases would make it harder to check that nothing pinned moved. The only thing to avoid is leaving "person"/"kind" unowned. Name the follow-up in the PR or on FIX-1790. Architecture lens (improve-codebase-architecture): nothing to refactor. The change touches only Generated by Claude Code |
There was a problem hiding this comment.
Simplify review
This amend does one thing: bring FIX-1790’s forward-looking prose in line with epic worker vocabulary, without touching implementation identifiers or rewriting FIX-1538 lineage quotes. That split is the right boundary.
Was a full sweep necessary?
Yes, for this spec. A single glossary pointer would be smaller, but FIX-1790 is almost entirely about the today → after isolation story; leaving “seat” in BR/PLAN/SPEC while the epic says “worker” would force every reader to mentally translate. The ~49-line mechanical pass across the six spec docs, cells.svg, and POC comments is proportionate—not scope creep.
What you correctly did not sweep: EVOLUTION “Prior intent” cells and DOCS UPDATE · "literal page title" lines still say seat where they quote today’s published anchors or FIX-1538 sources. That matches FIX-1575-style citation hygiene and avoids drift from linked artifacts.
Simpler alternative considered and rejected: Defer all renames to FIX-1796/FIX-1788 only. Epic D4 already expects behaviour described in new terms in child specs; FIX-1789 was authored worker-native from the start. Waiting would make FIX-1790 the odd spec out for no implementation savings.
Complexity / smell check
- No new abstractions, cross-imports, or custom machinery—docs-only.
.seat→.workerin the SVG is optional churn (no runtime consumer) but helps grep stay honest; fine either way.- Performance: N/A.
Optional polish (non-blocking)
Two draft sentences in DOCS.md use bare worker where the same issue elsewhere says hired worker / user-owned worker—easy to misread next to BullMQ “worker” in PLAN V5. Inline notes below; I’d tighten wording when those pages are published, not necessarily in this amend.
Verdict: Direction is clean and appropriately minimal. Approved.
Sent by Cursor Automation: Review For Best Approach
| > user and the key, `<orgId>/<userId>/<key>`. It reads the row from that person's data in that | ||
| > organization, and returns `null` when the id names no organization or the row names a different | ||
| > one. On a seat only one member can reach, it also returns `null` for an id naming another user. | ||
| > one. On a worker only one member can reach, it also returns `null` for an id naming another user. |
There was a problem hiding this comment.
Terminology (optional): Bare “On a worker only one member can reach…” sits in a scheduled.md draft a few lines from BullMQ/job “worker” language elsewhere in FIX-1790. BR-12 still says user-owned worker. Consider hired worker or user-owned worker here so implementers don’t parse this as a queue worker.
There was a problem hiding this comment.
Folded in 97805d9: the scheduled.md draft now reads "On a hired worker only one member can reach", so it no longer reads as a BullMQ queue worker.
Generated by Claude Code
| > Where a hired worker keeps what it learns about alice. Inside the acme organization: one cell for | ||
| > alice in acme, holding her user record and her shared user-scoped resources, which every flow | ||
| > in acme uses, hired seats included; and one cell per seat for flow-isolated data, such as alice | ||
| > in acme uses, hired workers included; and one cell per worker for flow-isolated data, such as alice |
There was a problem hiding this comment.
Clarity (optional): “one cell per worker” / “person per worker” is correct for acme.support.ada-style flow isolation, but “worker” alone can sound like roster/workforce generically. Per hired worker (flow instance) or per worker flow would track the example in the same block—only if you want extra disambiguation before publication.
There was a problem hiding this comment.
Folded in 97805d9 (alt text: "one cell per hired worker") and 3e59d65 (the paragraph under it: "one cell per user per hired worker"). Both now match BR-12's "hired worker".
Generated by Claude Code
| FIX-1790 owns "which org a user's record belongs to" in the epic's ownership table | ||
| ([epic DOCS.md](../../epics/FIX-1786/DOCS.md#ownership)). Every page below describes user data as | ||
| one record per person per organization, which is now true for every flow, so the hired-seat | ||
| one record per person per organization, which is now true for every flow, so the hired-worker |
There was a problem hiding this comment.
Reuse (optional): FIX-1789’s DOCS.md header explicitly defers code identifiers to FIX-1796 while prose uses worker terms. A one-sentence pointer here to epic Vocabulary (“prose uses worker; quoted FIX-1538 headings and symbols stay until FIX-1796/FIX-1798”) would document the amend rule for the next vocabulary pass without another file-wide sweep. Not required for this PR.
Second terminology pass on the post-merge amendment. The FIX-1786 glossary also retires "person" (say user) and "kind" (say flow). Prose, the DOCS.md draft, the three figures, the key-shape POC README and the key-shape placeholders (<person> -> <user>; the key bytes are unchanged) now use the new terms. "people" became "users" where it meant users. Headings of today's docs pages, the template heading "Five people", EVOLUTION quotes of prior decisions and code identifiers (flowKind, flow_kind, a schedule row's `kind`) are unchanged. Also folds two optional Cursor notes on #2816: DOCS.md's durable-hire alt text and scheduled.md draft say "hired worker", not a bare "worker" next to BullMQ's queue workers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Completes Cursor's optional note on #2816 (DOCS.md L60): the paragraph under the alt text had the same bare "per worker". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV


The problem
The FIX-1790 spec merged in #2810 still calls a hired worker a "seat". The epic's glossary retires that word (FIX-1786 vocabulary), and ER-25 asks each child to document in the new terms. Jake raised it on #2810 (comment): "You are still using seat. A seat is a worker and we should only have one name for something wherever possible." Round 1 on #2810 didn't apply it, so this follow-up does. It also applies the same glossary's other two retired terms the spec used: "person" (say user) and "kind" (say flow). #2810 is merged and its body can't be edited, so the change is described here.
What this does
A terminology-only amendment to
specs/issues/FIX-1790/. Every place the spec uses "seat" as its own word now says worker or hired worker:SPEC.md,DECISIONS.md,BUSINESS-RULES.md,PLAN.mdand the new-text columns ofEVOLUTION.mdDOCS.mddraft text the implementer will publish (durable-hire alt text and paragraph, flow-isolation, scheduled, the upgrade section)figures/cells.svg: the two box labels ("Hired worker"), "the worker's own cell", "every flow in Acme, the worker too", the aria-label, and the spec-owned CSS class.seatrenamed to.worker. Re-rendered in light and dark with headless Chromium; nothing overflows its boxpoc/key-shape/check.mjs(re-run: PASS, same counts)A second commit applies the glossary's other two retired terms the same way:
DOCS.mddraft, mermaid labels, all three figures (cells.svg,d1-before-the-step.svg,d2-attribution.svg, re-rendered light and dark), andpoc/key-shape/README.md.DOCS.mddraft ("follows the flow'sisolateUserState", "isolated cells on that flow are a stop").<person>:~org:<org>and<person>:~org:<org>:<flow>are now<user>:~org:<org>and<user>:~org:<org>:<flow>. That covers the pinned names inPLAN.md,SPEC.md,DECISIONS.md, the published upgrade section inDOCS.md, and the POC README. Only the placeholder's label changed. The key bytes and the pinned shape are the same.A third commit folds two optional Cursor notes: the
DOCS.mddurable-hire and scheduled drafts say "hired worker" where a bare "worker" sat near BullMQ's queue workers.No rule, decision or direction changes. Every edit swaps a word; no sentence changed meaning. The spec pins no new public name containing a retired term.
grep -i seatgrep -i persongrep -i peoplegrep -i kind(substring, includesflowKind,flow_kind)What's asked of you
Nothing to decide. Approve if the wording reads right; it changes no direction, so it doesn't reopen #2810's approval.
Parts worth reviewing closely
The 8 lines still containing "seat" (12 occurrences), each left on purpose:
DOCS.md:37REMOVE "Hired seats share within one organization"flow-isolation.md, which this change deletes. A locator has to match the page as it isDOCS.md:50The "Hired seats share within one organization" subsection is removedDOCS.md:53"What a seat saves for a person"durable-hire.md. The draft text under it now says "hired worker". Renaming that section heading would change its anchor and is a new docs change, not a word swap, so it's left for FIX-1788, whichDOCS.mdalready says owns the hire pages' move to worker terms. Flagging it: after this spec ships, that page will have a "seat" heading over "worker" text until FIX-1788 landsDOCS.md:55the person's data "outside hired seats"DOCS.md:82"Schedules on a hired seat" becomes "Schedules in a user's data"DOCS.md:117replacing "Upgrading: moving hired seats' stored data"EVOLUTION.md:11FIX-1538 D1: a hired seat keeps … and seats and the app's flows …EVOLUTION.md:12FIX-1538 D2 …: keys a seat alone declares, for people whose seats ran …,"Upgrading a deployment that already has seats","Upgrading: moving hired seats' stored data"The "person", "people" and "kind" hits left in place:
DOCS.md:53"What a seat saves for a person"DOCS.md:105EVOLUTION.md:10FIX-735: a person's shared user data … the bare person idEVOLUTION.md:11a person's data in its own (org, person) cellEVOLUTION.md:13"… decides the person's cross-org data …"SPEC.md:5Five people, before and afterEVOLUTION.md:12for people whose seats ran in one orgSPEC.md:96DOCS.md:98ctx.flowKindDOCS.md:101`kind`in a code commentkindfield, a code identifierDOCS.md:156,:159,:161flow_kindEVOLUTION.md:14no kind fallbackAlso worth a glance:
"pinned seat" became "pinned worker" (
PLAN.mdS4, V1, V2, invariants;BUSINESS-RULES.mdBR-8;DECISIONS.md). It still means a worker whose flow copy carries an owner pin."FIX-1538's seat cell" became "FIX-1538's hired-worker cell" (
PLAN.mdpinned names, the sketch).DOCS.mdline 215: "FIX-1788 owns the seat pages' move to workers" now reads "FIX-1788 owns the hire pages' move to worker terms". Same ownership, without the retired word."other-person check" became "other-user check" (
PLAN.mdV5), and "the person's isolated cells on that kind" became "the user's isolated cells on that flow" (DOCS.mdupgrade step 2).The
BUSINESS-RULES.mdsection heading is now "Where a user's data lives". Nothing links to its anchor.Links: spec
specs/issues/FIX-1790/· Linear FIX-1790 · epic FIX-1786 · original review #2810 (the comment this answers) · merges after approval and checks, as a post-merge spec amendmentHow to review this
This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
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?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.BUSINESS-RULES.mdmisses, or a rule that would invalidate the design.DOCS.mdand their fit with the rules; a missing ormisleading lineage claim in conditional
EVOLUTION.md.Out of scope — deliberately unsettled here, and owned by the implementing agent:
PLAN.mdpins on purpose.PLAN.mdleft open on purpose — it is directional by design, and a gap at thataltitude is intended, not an omission.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
PLAN.mdmay include a rough pseudocode sketchshowing 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/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 reviewfor the implementer to weigh against real code. It will not be argued with, and itwill 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.
Everything else
origin/mainat100cd278e(the spec(FIX-1790): A user's data is kept per org, for every flow #2810 merge). Onlyspecs/issues/FIX-1790/changes. Commits:de30827(seat),97805d9(person, people, kind, and the Cursor notes),3e59d65(the rest of Cursor's L60 note).seatId,seatAddress,seat-door.tsorhireWorkforceappears in this spec, so none needed protecting.node specs/issues/FIX-1790/poc/key-shape/check.mjs→PASS — no proposed key names a legacy cell or another tuple's cell.(24,964/24,964 shared keys equal FIX-1538's pinned cell, unchanged). All three figures rendered light and dark perdocs/contributing/spec-figures.md. Each is still self-contained, carries the dark media query, and has one aria-label, and no text overruns its box.🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code