Skip to content

spec(FIX-1549): Workforce's roster policy is enforced from Core's generic defineResourceCollection - #2178

Merged
jhoffner merged 2 commits into
mainfrom
spec/FIX-1549
Sep 24, 2026
Merged

jhoffner merged 2 commits into
mainfrom
spec/FIX-1549

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 24, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Someone who… Today After
builds an app without Workforce and declares workforce/roster/[owner]/notes defineResourceCollection throws: "can read user-owned roster rows" Defines and registers like any other pattern
builds an app without Workforce and declares [tenant]/** or [a]/[b]/[c]/[d] The app refuses to start, naming user-owned roster rows Registers
runs Workforce with user-owned seats, and some flow declares an overlapping pattern Refused Refused, same message, whichever flow registered first
owns a user-owned seat, or is another member of the org Only the owner reaches the seat or its row Unchanged
runs a process over a store holding user-owned rows, without the private writer (a split worker, an app that dropped Workforce, a second app on the same store) Overlaps refused there too Overlaps register, and cannot read or write any user-owned row: the rows are fenced by their key in every process

Today every app passes a roster check at definition and at registration; after, definition runs none, registration refuses overlaps only where Workforce's private roster writer is registered, and in every app a user-owned row is readable only by its owner through that writer

Top row, today: two unconditional checks. Bottom rows, after: none at definition, a startup refusal armed by the writer, and a fence on the rows themselves that needs no arming.

How: Core's defineResourceCollection drops the roster call. Engine's hire-plane module, which already holds the pin and the caller-only read, becomes the one owner. Its key predicate keeps any key under workforce/roster/~ away from every collection but the branded writer, on every read path and in every process. The registry arms the startup refusal when the writer is registered. Measured, not argued: on main, 8 of 12 patterns are refused in an app with no Workforce (poc/characterize); and arming alone lets a process without the writer read another member's row (poc/unarmed-leak).

Sign off

  1. A user-owned roster row is fenced by its key in every process; the startup refusal arms per registry once Workforce's private roster writer is registered, in either order, and stays armed. Changed in review round 1: the first draft relied on arming alone, and a POC showed a process without the writer reading another member's row. If wrong: every app reserves keys under workforce/roster/~ for the writer, and a read path the fence misses is exposed only in processes without the writer.
  2. The fence lives in one place, Engine's hire-plane admission; Core's defineResourceCollection runs no roster policy. If wrong: Engine keeps Workforce's roster names until a generic hook exists, and a minor bump drops one export only Engine calls.

Open: none. Number 1 is the one to weigh, and it changed since the head you may have read. Reasoning and what lost: DECISIONS.md. The cases: BUSINESS-RULES.md.

Reviewers · look here

  • Decisions → D1. The key fence is now the guarantee and arming only gates the loud startup refusal. Is reserving workforce/roster/~ in every app acceptable?
  • Plan → S3k, S3r, V7. Every collection read path must ask the key predicate. A missed path is the one way this is weaker than today.
  • Rules → BR-5 and BR-9. Order independence and never disarming. A fence that depends on boot order is one a refactor turns off.
  • Plan → V4. The corpus replayed in an armed registry, complete messages asserted, is the proof that what the fence refuses did not change.

Not here: changing what the fence allows or forbids; moving it into Workforce (needs a generic registration hook, flagged as a follow-up).

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1549 · no epic · builds on FIX-1529 (#2091) · merges after human approval and required checks

How to review this — altitude, what's in scope, what's deliberately unsettled

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 problem framing in SPEC.md — are we solving the right thing, for the people named?
  • 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.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

POC — two runnable commands, throwaway

bash specs/issues/FIX-1549/poc/characterize/run.sh (after pnpm install and pnpm --filter @flow-state-dev/core build). Answers: what does the roster fence cost an app with no Workforce today? 14 passed on 55c9581; a planted wrong row goes red.

bash specs/issues/FIX-1549/poc/unarmed-leak/run.sh answers: can a registry that never saw the writer leak a user-owned row? Yes on 01a9d43, through [a]/[b]/[c]/[d]; the [a]/[b]/[c] control goes red. Retained evidence, outside default discovery.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VZYLbMRNDkNp68tSBgftDN


Generated by Claude Code

…dmission

Retained spec set: Core's defineResourceCollection runs no roster policy;
Engine's hire-plane admission owns the fence, armed per registry once
Workforce's branded private roster writer is registered. Includes a
characterization POC of today's cost to apps without Workforce.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VZYLbMRNDkNp68tSBgftDN
@jhoffner jhoffner added the spec label Sep 24, 2026 — with Claude
@jhoffner jhoffner self-assigned this Sep 24, 2026
@vercel

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

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 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-09-24T20:16:14.590667Z 01a9d43 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.

@linear-code

linear-code Bot commented Sep 24, 2026

Copy link
Copy Markdown

FIX-1549

@jhoffner jhoffner left a comment

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.

FSD Architect — coherence stamp only. Not owner approval / not the merge gate. Shared login looks like Jake; this is approach/coherence, not product-owner sign-off. Never-merge record until human approval.

Stream: Soft follow-on factoring from Done FIX-1529 / #2091 (cut C depth guard). Matches EM fences already on Linear FIX-1549 (2026-09-24): L2 roster opinion off Core’s generic defineResourceCollection; preserve FIX-1529 acceptance (5) + depth guard wherever Workforce’s roster is in play; invent-kill weaken-fence / second hire store / soft-mix planes / baking roster policy into Core / unowned Core “exclusive key” primitive.

D1 / D2: Align. Arming on the branded private writer (not always-on, not app opt-in) and owning admission in Engine’s hire-plane module (already pin + caller-only read) is the smallest move that restores package-agnostic Core and keeps one enforcer. Rejecting “move into Workforce” because Workforce has no runtime Engine seam is correct given today’s package graph. Rejecting a new Core exclusive-key primitive without an owner lock matches the invent-kill.

Not a two-direction fork vs open siblings: FIX-1546/#2176 (schedule index identity) is orthogonal; FIX-1480/#2074 remains explore/not-ship Door B. No competing open spec that relocates or softens the roster fence.

Weigh with Jake (already the PR’s sign-off #1): D1’s per-process arming is honestly weaker than today’s unconditional scan for a split deployment that serves app flows over the same store without registering the writer in every process. Spec documents that as deployment rule — fine if that shape is not shipping; if it is, the DECISIONS.md “what would change my mind” path (arm from other roster collection / boot reload) is the reopen, not a silent fork.

Soft: Keep “no epic” + soft under FIX-1528 if an EM wants a parent; do not reopen F2 acceptance. V4 corpus equivalence is the right proof that armed refuse-set is unchanged.

— FSD Architect

@jhoffner jhoffner left a comment

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.

Second-look + improve-codebase-architecture pass

second-look (restraint) verdict: no findings. Scope matches the fix. D1/D2 already argue down the alternatives a less disciplined version of this issue would have shipped — an app-level opt-in flag, a new generic "exclusive key space" primitive in Core, moving the fence into Workforce — each with a stated, specific reason in DECISIONS.md's "Considered and dropped" table. Nothing here reads as premature abstraction or unjustified surface; if anything the spec did its own cutting before reaching review.

improve-codebase-architecture: one gap worth closing, one thing confirmed sound.

  • Confirmed: relocating admission into packages/engine/src/context/hire-plane.ts doesn't duplicate an existing generic gating mechanism — assertRosterCollectionIsNotDeep is Workforce-specific already, and D2's rejection of a generic Core primitive (new Layer-1 vocabulary, one consumer) holds up against the actual code, not just the spec's telling of it.
  • Confirmed: D1's "arms once, never disarms" isn't a novel pattern being introduced ad hoc — it's explicitly modeled on FlowRegistry's existing participants-map precedent (indexParticipant, flow-registry.ts:141-220), and DECISIONS.md says so. Good reuse of a shape the registry already has, not a second one invented independently.
  • Gap: that precedent lives in docs/architecture/state-and-scopes.md, and this PR's second instance of the same invariant class doesn't get a mention there — see the inline comment on DOCS.md's "Publication ownership" section for the specific ask.

No findings on the sketch, POC, or file/module-layout specifics — out of scope per this PR's own review contract.


Generated by Claude Code

Comment thread specs/issues/FIX-1549/DOCS.md Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 01a9d4395b

ℹ️ 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".

Comment thread specs/issues/FIX-1549/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1549/PLAN.md Resolved
Comment thread specs/issues/FIX-1549/DOCS.md Resolved
Comment thread specs/issues/FIX-1549/DOCS.md Resolved
…es only the startup refusal

Review round 1 on #2178. Codex's P1 held on the real path: with the
roster admission check a no-op (an unarmed registry), an org-scoped
[a]/[b]/[c]/[d] collection listed another member's user-owned row
(poc/unarmed-leak, control red). D1 now fences keys under
workforce/roster/~ in every process through Engine's hire-plane
predicate, on the handle, the browser resource routes and the debug
endpoints; the writer still arms the startup refusal, unchanged. The
per-process deployment rule is gone.

Also: V4 asserts complete refusal messages; the changeset is one
sentence naming FIX-1549; the fence is published in
state-and-scopes.md and architecture-reference.md.

Re-draft: D1 direction pivot; baseline 01a9d43

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VZYLbMRNDkNp68tSBgftDN
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