Skip to content

spec(FIX-1790): use the glossary terms worker, user and flow - #2816

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-1790-amend-1
Oct 6, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-1790-amend-1

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

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:

  • prose in SPEC.md, DECISIONS.md, BUSINESS-RULES.md, PLAN.md and the new-text columns of EVOLUTION.md
  • the DOCS.md draft 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 .seat renamed to .worker. Re-rendered in light and dark with headless Chromium; nothing overflows its box
  • the two comments in poc/key-shape/check.mjs (re-run: PASS, same counts)

A second commit applies the glossary's other two retired terms the same way:

  • "person" becomes "user" (and "people" becomes "users" where it means users), in prose, the DOCS.md draft, mermaid labels, all three figures (cells.svg, d1-before-the-step.svg, d2-attribution.svg, re-rendered light and dark), and poc/key-shape/README.md.
  • "kind" becomes "flow" where it means a worker's flow: two places in the DOCS.md draft ("follows the flow's isolateUserState", "isolated cells on that flow are a stop").
  • Key-shape placeholders renamed: <person>:~org:<org> and <person>:~org:<org>:<flow> are now <user>:~org:<org> and <user>:~org:<org>:<flow>. That covers the pinned names in PLAN.md, SPEC.md, DECISIONS.md, the published upgrade section in DOCS.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.md durable-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.

Term Before (lines / occurrences) After (lines / occurrences)
grep -i seat 54 / 66 8 / 12
grep -i person 102 / 129 5 / 7 (one is "impersonation")
grep -i people 7 / 7 2 / 2
grep -i kind (substring, includes flowKind, flow_kind) 9 / 9 7 / 7

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:

Where Hit Why it stays
DOCS.md:37 heading REMOVE "Hired seats share within one organization" Names today's subsection on flow-isolation.md, which this change deletes. A locator has to match the page as it is
DOCS.md:50 The "Hired seats share within one organization" subsection is removed Same subsection, same reason
DOCS.md:53 heading "What a seat saves for a person" Names today's section on 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, which DOCS.md already 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 lands
DOCS.md:55 the person's data "outside hired seats" Quotes the label on today's figure, which this change removes
DOCS.md:82 "Schedules on a hired seat" becomes "Schedules in a user's data" Names today's heading, which this change already renames
DOCS.md:117 replacing "Upgrading: moving hired seats' stored data" Names today's section, which this change replaces
EVOLUTION.md:11 FIX-1538 D1: a hired seat keeps … and seats and the app's flows … Prior-intent column quoting FIX-1538's decision. The new-text column of the same row now says "hired worker"
EVOLUTION.md:12 FIX-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" Prior-intent column quoting FIX-1538's rules and two existing headings. The new-text column now says "hired worker"

The "person", "people" and "kind" hits left in place:

Where Hit Why it stays
DOCS.md:53 heading "What a seat saves for a person" Names today's durable-hire.md section, as above
DOCS.md:105 "impersonation guard" Not the term. The substring matches inside "impersonation"
EVOLUTION.md:10 FIX-735: a person's shared user data … the bare person id Prior-intent column quoting FIX-735
EVOLUTION.md:11 a person's data in its own (org, person) cell Prior-intent column quoting FIX-1538 D1
EVOLUTION.md:13 "… decides the person's cross-org data …" A verbatim quote of FIX-1538's Considered and dropped
SPEC.md:5 heading Five people, before and after The spec template's "People, before and after" section. The table under it names users
EVOLUTION.md:12 for people whose seats ran in one org Prior-intent column quoting FIX-1538 D2
SPEC.md:96 "both kinds of resource" Plain English ("types"), not a flow
DOCS.md:98 ctx.flowKind Code identifier
DOCS.md:101 `kind` in a code comment The schedule row's kind field, a code identifier
DOCS.md:156, :159, :161 flow_kind SQL column name
EVOLUTION.md:14 no kind fallback Prior-intent column quoting FIX-1323

Also worth a glance:

  • "pinned seat" became "pinned worker" (PLAN.md S4, V1, V2, invariants; BUSINESS-RULES.md BR-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.md pinned names, the sketch).

  • DOCS.md line 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.md V5), and "the person's isolated cells on that kind" became "the user's isolated cells on that flow" (DOCS.md upgrade step 2).

  • The BUSINESS-RULES.md section 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 amendment

How 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:

  • 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.

Everything else
  • Branched from fresh origin/main at 100cd278e (the spec(FIX-1790): A user's data is kept per org, for every flow #2810 merge). Only specs/issues/FIX-1790/ changes. Commits: de30827 (seat), 97805d9 (person, people, kind, and the Cursor notes), 3e59d65 (the rest of Cursor's L60 note).
  • Each edit was made one occurrence at a time, not by a bulk replace.
  • Kept as code identifiers where they appear in backticks elsewhere: none of seatId, seatAddress, seat-door.ts or hireWorkforce appears in this spec, so none needed protecting.
  • Verification: 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 per docs/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

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
@jhoffner jhoffner added the spec label Oct 6, 2026 — with Claude
@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1790

@vercel

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

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 6, 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-10-06T20:11:30.646848Z de30827 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.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

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 de30827:

  • grep -i seat specs/issues/FIX-1790 returns exactly the 8 lines the PR body lists. Each is a locator for a heading on a docs page that still exists today, or the prior-intent column quoting FIX-1538. Leaving them is correct; rewording them would make the locators miss.
  • "hired worker" matches the epic's own usage (CONCEPT.md lines 423 and 474), and the glossary maps "seat, hired seat" to Worker. So this does not introduce a second name.
  • cells.svg: the .seat → .worker rename is complete (definition plus both rects), and nothing else in the file uses the new class name.

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:

  1. Fold "person"/"kind" into this PR now. This is a larger diff, and some uses are structural, e.g. <person> in the pinned key shape, which is persisted and must not change, so each one needs a look.
  2. Land this as is and do "person"/"kind" as a single amend-2.

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 specs/ and no code, so there is no deepening opportunity to take here.


Generated by Claude Code

@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

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 → .worker in 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1790/DOCS.md Outdated
> 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.

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.

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.

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.

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

Comment thread specs/issues/FIX-1790/DOCS.md Outdated
> 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

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.

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.

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.

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

Comment thread specs/issues/FIX-1790/DOCS.md Outdated
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

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.

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.

claude added 2 commits October 6, 2026 20:15
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
@jhoffner jhoffner changed the title spec(FIX-1790): say "worker", not "seat" spec(FIX-1790): use the glossary terms worker, user and flow Oct 6, 2026
@jhoffner
jhoffner merged commit 39d7abe into main Oct 6, 2026
13 checks passed
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