Repository navigation
feat(FIX-1381): a seat reaches the documents its file names — resources: with ro/rw - #1943
Conversation
A `WORKER.md` may declare `resources:`, a list of the file-declared documents that seat may touch. Naming a document grants read; `rw` grants write, and `ro` spells the read-only default out. The hire step resolves the list against the documents the app declared — handed over through a new `documents` option — and mints that seat with a narrowed flow-level resource map. Applied at the mint, so it sits below every worker kind and a custom kind gets it without declaring anything. The narrowed map is built by subtraction from the kind's own flow-level map, never assembled from the granted documents alone: the instance option replaces rather than merges, so a map built from grants alone would delete the app's stores and boards with nothing said. Which entries are documents is answered by the catalog the app passes, never inferred from an entry's shape. Opt-in. A seat that declares no `resources:` key is minted with no map at all and reaches exactly what it reached before. `ro` is the seat's copy of the document with both existing write flags turned off — the code write seam and the model's own write tool — rather than a new access check. Every problem with a declaration is fatal at the hire, collected so one run names every bad grant across the roster: a ref no document matches, a ref naming a document the kind was not installed with, a bad mode, a duplicate ref, `rw` on a document declaring itself unwritable, a ref colliding with a name the kind's blocks declare, and the key itself when no documents were passed. `resources` becomes a key the factory reads rather than a setting it forwards, so a kind that declared a `resources` setting of its own no longer receives an authored one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011T5Gos3ywJ4nr47Au55iwZ
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
There was a problem hiding this comment.
Simplify review (FIX-1381)
Verdict: The mint-time allowlist in a dedicated seat-resources.ts module is the right shape for what the spec signed off (D1–D4). I do not see a materially simpler design that keeps per-seat document narrowing, opt-in defaults (V5), and ro as existing write flags (D3) without opening a worse hole. Approve — the bulk of the diff is proportionate permission-boundary work, not accidental ceremony.
Did this go too far?
Most of the ~1.7k lines are doing real work:
- Subtraction in
resolveSeatResourcesis not over-engineering — it is the minimal correct construction once a flow instance’sresourcesoption replaces the definition map (V7). Building from grants alone is the red state the tests pin; collapsing that into a shorter helper would hide the hazard, not remove it. - A separate module parallel to
seat-capabilities.tsis the clean directory story: loader pass-through, hire-only refusals, nomanifest.tscross-import cycle. Folding parse/resolve intohire.tsormanifest.tswould be simpler by line count and worse by boundary clarity. - Hand-rolled
readEntryon post-YAMLunknownis appropriate. A third-party YAML parser would not run here; optional Zod for list entries could unify withworker-config, but you would still own the same refusal copy — that is a style trade, not a big simplification (I would not block on it).
What looks heavy but is mostly intentional: ~11 curated refusal sentences and long module headers — same voice as other workforce permission files, and the feature’s product promise is “fatal at hire with every bad grant named.”
Simpler approaches considered (and why I would not take them)
| Alternative | Why it is not cleaner |
|---|---|
| Runtime read/write gates instead of mint-time map | New enforcement layer on every turn; harder to answer “what can this seat touch?” and easier to drift from D3. |
Only filter documents at kind install (no per-seat list) |
Solves team-scoped catalogs, not per-seat allowlists within a kind. |
| Grant against full app catalog (ignore kind slice) | Simpler code, worse security story — your post-spec “not on this kind” refusal matches BP-031; I agree with the PR’s call unless apps routinely install one catalog on every kind. |
| Third-party package for parsing | No package replaces subtraction semantics or catalog/kind split; YAML is already parsed upstream. |
Targeted simplify follow-ups (optional, non-blocking)
- Test header vs exports — the suite says refusals are asserted “from the constants,” but message builders are module-private; tests use regex/
toContain. Either export test hooks (manifest pattern for imposed keys) or soften the header so it matches reality. - Direct
resolveSeatResourcesunit tests — most resolve logic is only reached throughhireWorkforcefixtures. A small pure block would shrink fixture duplication and make V7 cheaper to maintain (not required for merge). - Memoize
blockAccessorsper factory when many seats on one kind declareresources:— real but hire-time-only; profile before doing it. - Duplicate detection vs bad mode —
modesByRefruns before mode validation; a ref listed once with a bad mode and once as bare string can also emit a duplicate refusal. Edge-case author error; worth a one-line comment or ignoring dupes when mode already failed (your call).
Checks
Re-ran pnpm --filter @flow-state-dev/workforce test on this branch: 626 passed.
No changeset concern from this review — the PR already carries the workforce patch fragment.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — already tight. No POC.
The production delta is one permission boundary: parse three entry shapes, refuse eight distinct failures, mint by subtracting documents the seat did not name. A rewrite does not shrink that contract.
Read: packages/workforce/src/seat-resources.ts (key, modes, wordings, parseSeatResources, resolveSeatResources); packages/workforce/src/hire.ts (reserved resources, documents option, absent-key mint); packages/workforce/test/seat-resources.test.ts (V1–V8 + widening); goals/workforce-seats/a-seat-reaches-the-documents-its-file-names/run.mts (real-path legs); packages/workforce/src/seat-capabilities.ts (house essay density); packages/workforce/src/index.ts (this module is not a public export).
Rejected subtractions: strip the module / wording / blockAccessors essays (house style; you already recorded that the collision narrowing lives in that comment); inline the eight one-use wording functions (same strings, same tests — a move, not a shrink); fold parse into resolve so hire makes one call (two refuse loops stay, one type goes); drop the goal (sibling workforce-seat goals are this shape; the unit suite cannot be the HTTP path); data-drive V1–V8 (each case owns a WHY).
Not reopening D1–D4, the kind-not-catalog grant, ro as the existing write flags, or the documents option. Agent on this PR: nothing to fold.
Sent by Cursor Automation: Code Snob
The `Process guards` check refuses a spec cited by repo path: no spec file exists on main, so `spec/FIX-1381/BUSINESS-RULES.md` was dangling the moment it was written (BP-037). The rule and check numbers stay, since each case already states the rule it owns; only the link goes. Same header, second correction: it claimed every refusal is asserted "from the constants". The wording builders are private to `seat-resources.ts` and the cases assert on substrings, so the sentence oversold the coupling. It now says what the suite actually does, and why the wordings stay private. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011T5Gos3ywJ4nr47Au55iwZ
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 68d836a364
ℹ️ 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".
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. |
Two holes in the narrowing, both found in review and both reproduced before being closed. A document declared BOTH at flow level and by one of the kind's blocks is shadowed at definition time, so nothing readable off the built kind tells it apart from a document no block mentions. `defineFlow` merges the blocks' own declarations back on top of an instance's map, so the block's copy returns the moment a seat's narrowed map removes the flow-level entry hiding it: a seat declaring `resources: []` read AND wrote a document its file denied. The narrowing is now checked on the seat that was BUILT — the only place the answer exists — and the hire refuses, naming the ref and the kind. A map is an object, so an app can expose one definition under a second key. Matching document names alone left that alias on the seat's map, a writable handle on a denied document under another name. Documents are now identified by name OR by the definition itself, which can only ever recognise more of them. The `ro` half of the same hazard does not arise — a flow-level entry wins the merge, so the read-only copy holds against a block declaring the document writable. Pinned as a test rather than guarded by a branch nothing could fire. Also: `hireWorkforce refused N of M workers` counted reasons, not workers, so one worker with two bad grants printed "refused 2 of 1 worker" — the sentence a comment three screens down already says this function may not print. The architecture contract now carries `resources` as a key the hire step consumes, and the changeset is one sentence plus its migration note. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011T5Gos3ywJ4nr47Au55iwZ
…le to fail (FIX-1381) A kind that declares something OTHER than the app's document under that document's own ref made the narrowing wrong in both directions at once: the subtraction deleted the kind's store because the name matched, and a `ro` grant on that ref would have made that store read-only — which this feature promises never to do. The two readings cannot be told apart, so the hire refuses for that kind and says to rename one of them. The acceptance check's leg (f) asserted all-or-nothing by building a host from `hired ?? []` inside the branch where `hired` is undefined by construction: the registry was always empty, so the 404 was always going to arrive. It now reads the claim off the refusal itself, which is the only place it is observable — `hireWorkforce` returns its seats, so a throw leaves no array to inspect. Proved by making the refusal per-worker: leg (f) fails and nothing else does. Also from review: the changeset says what an affected kind must do rather than only what changed, and the docs example says which symbols it carries over from the kind it continues. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011T5Gos3ywJ4nr47Au55iwZ
Correction to the PR description, and what changed in reviewThe third bullet under Parts worth reviewing closely is wrong and is superseded by this comment. It says the collision rule is deliberately narrower than A document declared both at flow level and by one of the kind's blocks is shadowed at definition time — invisible on the built Three holes in the narrowing, each reproduced first and each pinned with a red state:
The first is why the fix is a post-mint check rather than the collision rule both reviews proposed: no inspection of the kind can see a shadowed block declaration, so there is nothing to refuse in advance. Reading the built instance answers it for whatever path the build takes. Two more, also from review:
Everything else in the description still holds. All thirteen review threads are answered and resolved. Generated by Claude Code |
|
FSD Architect — owner amend trail (Jake 2026-09-20). Not a reopen of D1–D3 on FIX-1381; this is a follow-on product split. Direction: Door A RO handbooks should move off the Why it touches this PR: the per-seat Tracking: Linear exploration filing under W5 (FIX-1457); soft-related this issue + FIX-1354 + FIX-1382. EM expected soon. Do not invent a References L1 type; do not dual-run Door A under both folder names forever. — FSD Architect |


Requested by Jake · project thread
The problem
Every seat in an org reaches every document that org declared, and can write all of them. A support seat can read the payroll doc and rewrite it. There is no way to hand a seat a handbook to consult without also handing it the pen, and no way to answer "what can this seat actually touch?" except by reading the app's whole resource map and assuming the answer is all of it.
What this does
A seat's
WORKER.mdnames the documents it may touch. The hire step resolves those names against the documents the app declared and mints that seat with a narrowed map.Naming a document grants read;
rwgrants write.rospells the default out. The grant is applied at the mint, below every worker kind, so a custom kind gets it without declaring anything.Three things it deliberately does not do:
resources:key is untouched — same documents, same access, byte for byte. This is opt-in, so an org that changes nothing is exactly as exposed as it is today.roadds no new access check. It is the seat's copy of the document with both existing write flags turned off — the one at the code write seam and the one gating the model's own write tool.Everything that can go wrong with a declaration is fatal at the hire, with every bad grant across the roster named in one message and nothing hired.
What's asked of you
This implements the approved spec on #1935 — D1, D2 and D3 are signed off and nothing here reopens them. One thing is new since approval and is yours if you disagree with the call:
A grant selects from what its seat's kind holds, or from everything the app declared?
The spec's sketch was ambiguous. The README already tells people to filter documents before installing them on a kind, which is how you give a team's seats only its team's documents. If a grant could name anything in the app's catalog, a seat file would reach past that filter — a seat widening itself past its own kind, on the say-so of an author-editable file. I made it refuse, loudly, at the hire.
What would change my mind: evidence that apps install one catalog on every kind, in which case the refusal is a boot error nobody needed. What being wrong costs either way: refusing wrongly is a clear boot message and a one-line fix; allowing wrongly is a filter that silently does not hold, and nobody finds out.
Parts worth reviewing closely
seat-resources.ts→resolveSeatResources. The narrowed map is built by subtraction from the kind's flow-level map, never assembled from the granted documents alone. The instance option replaces rather than merges, so a map built from grants alone deletes the app's own stores with no warning.V7runs both constructions; the second is the red state.hire.ts→ the mint. Absent and present-and-empty must stay distinct end to end. A seat that declared nothing is minted with no map — not an empty one, not a reconstructed one. That isV5, and it is the check a flipped default takes silently.BR-8's wording, and deliberately. A block declaration the kind also declares at flow level is already shadowed before any seat file exists and cannot be read off a built flow at all. Every case where honouring a grant would newly take a name from the kind's wiring is covered; the case left out is not a hazard. The reasoning is in the comment aboveblockAccessors.resourcesis now a key the factory reads, not a setting it forwards. A kind that declared aresourcessetting of its own would no longer receive an authored one. Nothing in this repo does; it is in the changeset.Spec PR #1935 · Linear FIX-1381 · epic FIX-1407 (W4) · builds on D-11 (FIX-1380)
How to review this — altitude, what's in scope, what's settled
How to review this. This implements an approved spec — the approach and the numbered decisions in its
DECISIONS.mdare already signed off by a human, so please review the code against that direction, not the direction itself. The spec lives on the issue's Linear document (the durable copy) and on the spec PR (#1935), which keeps its review history. Don't expectspec/FIX-1381/to be in this diff — the spec never lands onmain(BP-037).Most valuable here: correctness on the second path (the seat that declares nothing, the present-and-empty list, the kind that declares no documents), anything deriving access from caller-controllable input, and a behaviour the tests assert around rather than on.
Already settled upstream: the approach and every decision in the spec's
DECISIONS.md— opt-in (D1), bare-ref-means-read (D2),roas the existing unwritable flag rather than a new gate (D3), and the hire step being told which resources are documents (D4). If one is wrong, say so as a spec finding; don't re-argue it inline. Also settled: the conventions indocs/contributing/best-practices.md.Engineering calls — decided while building, not the product owner's
seat-resources.ts), and the wordings are module-private. A permission boundary with two construction sites is a second placerocan be forgotten.documentsoption onHireOptions, typed as theDeclaredResourcesmapresourcesFromDocsalready returns. The spec required a new option; this is the smallest one that adds no second table.resources:is refused with a message naming the list form. The near miss an author writes is an indented mapping, which is valid YAML and reads as the obvious thing.resources: []parses to zero grants, not to a problem. Present-and-empty is how a file says "no documents", matchingseatSkillsandseatTools.Verification
Rule checks —
packages/workforce/test/seat-resources.test.ts, V1–V8 plus the widening case. 28 cases.Every check was watched go red. Four mutations, each caught by exactly the check that owns it and by no other:
rono longer closes the model's write toolAcceptance, on the real path —
goals/workforce-seats/a-seat-reaches-the-documents-its-file-names/. Three seats of one kind, hired from files by the real loader, run through the real HTTP router; the stores are closed and the host rebuilt before anything is read back, and a block nested inside the action probes reach and writability by actually reading and actually writing.Its three negative controls each fail at their own leg, which is what makes the pass mean anything:
audit-logrogrant minted writablewrote ["handbook"], its file grants []Second path (BP-035). The one real
hireWorkforcecaller in this repo (apps/kitchen-sink/workforce/hire.ts) installs no documents and passes nodocuments; noWORKER.mdin the repo declaresresources:. Both hire exactly as before, and V5's third case pins the no-documents-at-all call.pnpm --filter @flow-state-dev/workforce typecheck,pnpm --filter @flow-state-dev/goals typecheck,guard:control-shapeandvalidate-package-boundariesall pass.apps/docsbuilds clean.Files
packages/workforce/src/seat-resources.tspackages/workforce/src/hire.tsresourcesbecomes a key the factory reads; thedocumentsoption; the narrowed map at the mintpackages/workforce/test/seat-resources.test.tsgoals/workforce-seats/a-seat-reaches-the-documents-its-file-names/**packages/workforce/README.mdresources:key, thedocumentsoption, the refusalsapps/docs/docs/workforce/workers-on-disk.mdtools:, and how an app supplies its documentsapps/docs/docs/workforce/documents-on-disk.md.changeset/seat-resource-allowlist.mdminor🤖 Generated with Claude Code
https://claude.ai/code/session_011T5Gos3ywJ4nr47Au55iwZ
Generated by Claude Code
Note
Medium Risk
Introduces a permission boundary at hire/mint time for document reach and writability; default rosters are unchanged, but misconfigured grants or resolver bugs could lock seats out or over-expose documents.
Overview
Adds per-seat document access from
WORKER.md: aresources:list names which file-declared documents that seat may use—bare ref orrofor read-only,rwfor write. Apps pass the sameresourcesFromDocsmap as a newdocumentsoption onhireWorkforce; hire parses grants inseat-resources.ts, validates them against the catalog and what the kind installed, and mints each seat with a narrowed flow-level resource map (non-document flow resources and block machinery are kept via subtraction, not a grants-only rebuild).resourcesis now hire-owned, likeflowanddescription—it is stripped from seat config so it cannot collide with a kind setting. Seats with noresources:key behave as before;resources: []means no documents. Bad grants fail the whole roster at hire with collected errors.Ships docs, a minor changeset, unit tests (V1–V8), and an HTTP goal that probes reach/write from nested blocks after store rebuild.
Reviewed by Cursor Bugbot for commit 68d836a. Configure here.
The PR is not safe to merge until catalog-key collisions can no longer strip or alter non-document resources, and the explicit changeset and test-quality requirements are satisfied.
Summary
This PR adds opt-in per-seat document grants to
WORKER.md, resolvingroandrwdeclarations during hiring and minting each restricted seat with a narrowed resource map.seat-resources.ts.hireWorkforce.Diagram
%%{init: {'theme': 'neutral'}}%% flowchart LR W["WORKER.md resources"] --> P["Parse ro/rw grants"] D["hireWorkforce documents catalog"] --> R["Resolve seat resources"] K["Kind resources and flow-level keys"] --> R P --> R R --> M["Preserve non-documents and add granted documents"] M --> I["Mint restricted flow instance"] A["No resources key"] --> N["Do not pass a replacement map"] N --> IReviews (1) · Last reviewed commit: "feat: a seat reaches the documents its f..."