Skip to content

Fill the live inventory at boot (FIX-1405 S5–S7) - #1928

Merged
jhoffner merged 4 commits into
mainfrom
fix/FIX-1405-inventory-binder
Sep 19, 2026
Merged

jhoffner merged 4 commits into
mainfrom
fix/FIX-1405-inventory-binder

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 19, 2026 •

Copy link
Copy Markdown
Collaborator

A team can be declared and hired, and at run time nothing answers which seats and channels actually exist. The three collections that hold that answer are on main, and nothing writes to them — an app that installs them is on its own to fill them, which is how two labs each grew the same private reader byte for byte. Until something writes the rows, a seat that wants to find another seat, or to know which channels it is in, has to re-walk a folder tree that a running block cannot reach.

What this does

Two things now write the inventory, and which one writes what is decided by where the live answer lives.

flowchart LR
  R["the roster:<br/>hired seats + channel records"] -->|"seat rows, straight from the roster"| I["the org's inventory"]
  R -->|"channel ids only, no member data"| B["openInventory"]
  B -->|"'register yourself'"| C["the channel, in its own session"]
  S["that channel's session state"] -->|"the live members"| C
  C -->|"channel row + membership rows"| I
  I -->|"an ordinary resource read"| F["any flow in the same org"]
Loading

A seat has no session. What it is — its id and the kind it was hired into — is the roster the process was hired from, so the binder writes those rows from what it already holds.

A channel has a session, and who is in it lives there and nowhere else. So the binder does not write a channel's row at all. It runs an action inside that channel's own session, and the channel writes its own row from its own state. The binder carries no member data, deliberately: a CHANNEL.md's members: is what a file said when it was last read, an edit to it does not reach a channel that is already open, and a binder copying it forward would publish that file-time answer under a live name.

Turning it on is two lines at boot — channelInstances(channels, { inventory: true }), then openInventory(...) after openChannels. An app that doesn't declares nothing and writes nothing, and its channels behave exactly as they do today.

What's asked of you

This implements the approved direction in spec PR #1916; nothing about the approach is reopened here.

One thing is worth a look because it touches the one item you weighed at sign-off — that this adds a call an app has to make. That call takes one more piece of wiring than the spec's snippet showed: openInventory needs to be told which flow to write the seat rows through (seatWriter: { flowKind: "channel" } for most apps).

  • Why it could not be derived. The only door onto one of these collections is a running block. The framework's resource routes carry a collection item's content, not its state, and this package deliberately does not depend on the engine — so the seat rows need a flow to run in, and the roster does not say which one.
  • The trade-off. An app that turns the inventory on writes one more option at boot. The alternative is the binder picking a flow on the app's behalf — which works until an app replaces the built-in channel kind or has no channels at all, and then fails as one line in a list nobody reads rather than at the call site.
  • Recommendation: keep it explicit. It is refused by name with the exact option to pass, so a wrong boot is loud on the first run.
  • What being wrong costs: one line of boot code per app, changeable later without touching a stored row. This is not a shape we would be stuck with.

Parts worth reviewing closely

  • openInventory's failure split (packages/workforce/src/inventory/open-inventory.ts). Two things throw — no orgId, and seats with no seatWriter — and everything else is collected into problems and returned. Worth checking that the split is the right one and that nothing that should stop a boot is quietly in the list.
  • The run door's contract. It must reject when the action fails. A door that hands a failed run back as an ordinary value would make the binder report every channel registered while writing nothing, and there is no other signal this package can read. The doc comment says so; whether that is enough is a fair question.
  • The two registration actions sit on different doors, deliberately. registerChannelInInventory is public: closed, empty input, and the row is derived from the channel's own session state, so a caller cannot make it write anything but that channel's true members. registerSeatsInInventory is in internal.actions only, because a seat has no session and its whole input is the row data, with nothing in this package to check it against. resolveEntry reads exactly one map per dispatch type with no fallback, so a caller-addressed dispatch has no path to it at all; the only way in is the binder's own runAction({ source: "internal" }). Worth checking the split is drawn in the right place, and that InventoryActionRequest.source fails closed for a run door that drops it.
  • openedAt is written create-only, so a second boot does not restamp a channel that has been open since the first. That is the one field where an upsert would otherwise lose information.

Links

Linear FIX-1405 · spec on the issue's Linear document and on closed PR #1916 · epic #1905 · follows #1920 (PR-A) and #1923 (the collections) · this one merges.


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

How to review this. This implements an approved spec — the approach and the numbered
decisions in its DECISIONS.md are 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 closed spec PR (#1916), which keeps
its review history. Don't expect spec/FIX-1405/ to be in this diff — the spec PR closes
unmerged at approval and the spec never lands on main (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null
boundary, the concurrent case, the cancel path), anything deriving an auth or routing
decision 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
(human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't
re-argue it inline), and the conventions in docs/contributing/best-practices.md.

Deviations from the spec — where the landed code won

The spec was written against main at d8e4c99, before FIX-1385's channel boards and this issue's own collections merged. Two of its assumptions did not survive.

1. openInventory takes a seatWriter. The spec's boot snippet is openInventory({ seats, channels }, { run, userId, orgId }), and PLAN.md → Write moments says the seat rows are written by the binder "directly", with "no flow run, no dispatch". That is not reachable. Checked before deviating:

  • ResourceCollectionRef — the only API that writes a collection's state — is reached through ctx.resources inside a running block and nowhere else.
  • createResourceClient (packages/client/src/resource-client/resources.ts) is session-scoped and its createCollectionItem takes { topic, content }. It writes an item's content body, not its state. There is no resource route that writes row state.
  • @flow-state-dev/engine is a devDependency of this package, so the store registry is reachable from a test and not from shipped code — which PLAN.md itself states about runAction.

So the seat rows must go through a flow, and a flow has to be named. The binder therefore dispatches once for all seats (not once per seat — that part of the plan's cost claim holds) and once per channel. The channel half is exactly as specified: the channel's own kind, the channel's own session, no member data in the payload.

2. The defineChannelFlow merge is one actions map, not one widened resources map. PLAN.md → At implement time says S5 "adds to all three" of FIX-1385's resources, actions and internal.actions. The inventory collections are declared on the blocks that write them instead, which is how the shipped collections' own tests already install them and which is sufficient for the rows to resolve — a block's resources bubbles up through mergeDeclaredResources. boardResources stays on defineFlow because the board blocks resolve their ledger by a dynamic id and cannot declare it. Declaring the same collections in both places would be redundant, so the merge is: boardResources untouched on the flow, the two inventory entries appended to actions, and internal.actions untouched — nothing dispatches the registration internally.

3. The inventory flag reaches the built-in kind only. channelInstances({ inventory: true }) rebuilds the built-in carrying the writer. A kind passed under kinds is zero-arg by contract, so there is nowhere to hand it the flag — the same reason boards cannot reach one. A hand-rolled kind carries the writer by spreading inventoryWriterActions("<its kind>"), which is what makes "every open channel has a row" true for a custom kind rather than aspirational. A kind that carries neither is a named entry in problems, never a silent gap.

Engineering calls — decided along the way, no product sign-off needed
  • The seat-write action lives on the channel kind (alongside the channel registration, from one inventoryWriterActions(kind) call). Any flow carrying it can host the seat write; putting it on the kind the app already has is what keeps seatWriter to one field. Wrong call costs a second export an app has to install somewhere.
  • The row's kind is closed over at build time, not taken from the action's input. A block cannot read its own flow's kind — ctx.flow is narrowed to the create-time config bag — so the alternative was the binder passing it as input, which puts a row field on caller-controllable input for no gain. Wrong call means a hand-rolled kind that passes the wrong string writes a row that mislabels itself, in the same way a wrong cardinality does.
  • The membership index prunes nothing. One write produces the channel row and its index rows from one read of one session state, so they cannot drift — and no path in this change alters an open channel's members, so there is no stale row to prune. A prune path would be speculative code for a state that cannot occur yet; it arrives with the reconcile verb, which is already a follow-up.
  • kindOf and orderedById are exported from channel-binder.ts for the inventory binder, not re-exported from the package root. A second derivation of "which flow is this channel on" would silently diverge from the one openChannels uses.
  • The binder returns problems rather than throwing them, matching the declared-roster reader beside it: the caller decides what is fatal. An app that ignores the return value loses rows silently, which is the cost.
Verification — what was checked, and what would have made it fail

The new cases live in packages/workforce/test/inventory-binder.test.ts and all run on the real path: a registered kind, a session opened by openChannels, and a real action run. The reader in every case is a flow that is not a channel and that declares its own instances of the three collections, so nothing is green merely because the writer read back its own objects.

Every assertion was then shown to discriminate. Each red state below was applied to the source, the case it targets was run, and it failed — then the red state was reverted.

Red state applied Case it broke
The binder passes the roster's members and the channel writes them BR-10 — the row holds the session's members
The write put behind a kind === "channel" branch BR-22 — a custom kind's channels get rows
openedAt written on every upsert instead of create-only BR-9 — a second boot is a no-op
The collections and actions declared unconditionally BR-13 — the off state declares and writes nothing
The no-orgId guard removed BR-11 — refuses rather than writing where nothing reads
The second boot given its own storage BR-23 — rows outlive a roster that drops them

Beyond the red states, three cases carry a live control in the same process: the off-state case runs the identical roster one flag apart; the custom-kind case registers a third hand-rolled kind that deliberately omits the registration, so "the row is there" is an assertion about the writer and not about the roster; and the membership-index case seeds eng.leadership alongside eng.lead so a prefix read without the segment boundary would drag the wrong channel in.

Run:

  • pnpm --filter @flow-state-dev/workforce test — green, and the pre-existing channel suites are untouched, which is the off-state claim at suite scale.
  • pnpm --filter @flow-state-dev/workforce typecheck, pnpm --filter @flow-state-dev/fsdev typecheck, pnpm --filter @flow-state-dev/goals typecheck — clean.
  • pnpm --filter @flow-state-dev/docs build — clean, no broken-link warnings, run as the last action on the docs.
  • pnpm --filter kitchen-sink typecheck reports 13 errors, all in packages/tools/src/bash/adapters/moat.ts, a package this branch does not touch at all — nothing in this diff is under packages/tools. Pre-existing, not introduced by this PR.
Files
File What changed
packages/workforce/src/inventory/open-inventory.ts New. openInventory, its roster/options/result types, and the seat-writer session constant.
packages/workforce/src/channel/channel-flow.ts inventoryWriterActions(kind) — the two registration blocks and the collections they write — plus the inventory? option on defineChannelFlow, which spreads them into actions.
packages/workforce/src/channel/channel-binder.ts inventory? on channelInstances, which seeds the built-in kind rebuilt holding the writer; kindOf and orderedById exported for the inventory binder.
packages/workforce/src/channel/index.ts, src/inventory/index.ts The new public surface.
packages/workforce/test/inventory-binder.test.ts New. The cases above.
packages/workforce/README.md The live-inventory section gains the writer: the boot wiring, the new exports, the two refusals and the collected problems, and the limits. The channels section's re-bind limitation is unchanged and still scoped to the three settings written at create.
apps/docs/docs/workforce/inventory.md New page, after Channels — the two layers, which question goes where, the boot wiring, what is and is not written.
apps/docs/sidebars.ts, documents-on-disk.md, capabilities-on-disk.md Registration and the two sidebar_position bumps the insertion needs.
.changeset/inventory-binder.md patch for @flow-state-dev/workforce, as the plan pins.

The user-facing prose was written and revised by docs-writer from the public surface and the tests, and reviewed by docs-editor (SHIP; four prose nits, applied by the writer). Neither saw the spec or this diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T

``<source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/RetriggerDark.svg?v=2"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2"><img alt="Retrigger" src="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2" align="right">``Confidence Score: 2/5

The PR is not safe to merge until the public seat writer is protected, channel registration cannot leave contradictory inventory after partial failure, and the explicit documentation-rule violations are corrected.

Findings

  1. &lt;img alt="P1" src="https://greptile-static-assets.s3.amazonaws.com/badges/p1.svg?v=9" align="top"&gt; &lt;img alt="Security" src="https://greptile-static-assets.s3.amazonaws.com/badges/Security.svg?v=2" align="top"&gt; Public action forges seats ▶
  2. &lt;img alt="P1" src="https://greptile-static-assets.s3.amazonaws.com/badges/p1.svg?v=9" align="top"&gt; Registration can partially commit ▶
  3. &lt;img alt="P2" src="https://greptile-static-assets.s3.amazonaws.com/badges/p2.svg?v=9" align="top"&gt; API table contradicts exports ▶
  4. &lt;img alt="P2" src="https://greptile-static-assets.s3.amazonaws.com/badges/p2.svg?v=9" align="top"&gt; Changeset includes internal rationale ▶

Summary

This PR adds opt-in boot-time population of workforce seat, channel, and membership inventory, including public writer actions, binder orchestration, tests, and user documentation.

  • Seat rows are dispatched through an explicitly selected writer flow.
  • Each channel publishes its row and membership index from its own session state.
  • The implementation currently exposes an unrestricted seat writer and can leave partially committed channel inventory after a failed membership write.
  • The README API table and changeset also require corrections to satisfy repository documentation rules.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Caller["Public action caller"] -->|"registerSeatsInInventory\ncaller-supplied seats"| SeatWriter["Public seat writer"]
  Binder["openInventory"] -->|"trusted roster seats"| SeatWriter
  SeatWriter --> SeatInventory["Org seat inventory"]

  ChannelSession["Open channel session"] --> ChannelWriter["Channel registration action"]
  ChannelWriter -->|"1. commit channel row"| ChannelInventory["Org channel inventory"]
  ChannelWriter -->|"2. sequential membership writes"| MembershipInventory["Org membership index"]
  MembershipInventory -. "failure does not roll back step 1" .-> Inconsistent["Partially populated inventory"]
Loading

Reviews (1) · Last reviewed commit: "FIX-1405: document the live inventory's ..."


Generated by Claude Code

A channel built with `inventory: true` carries the writer half: the three
collections and two actions. `openInventory` runs them — one per open channel,
in that channel's own session so the row's members come from the session state
the post fence reads, and one for the roster's seats.

The binder carries no member data. A roster's `members:` is what a file said
when it was last read, and an edit to it does not reach an open channel, so a
binder copying it forward would publish a file-time answer under a live name.

Deviation from the spec's boot snippet: `openInventory` takes a `seatWriter`
naming the flow the seat rows are written through. A collection can only be
written from inside a running block — the resource routes carry an item's
content, not its state — so the seat rows need a flow, and the roster does not
say which.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
A new `apps/docs` page for the two layers — what the declared tree answers,
what the inventory answers, and the boot wiring — plus the package README's
writer half: the boot call, the new exports, the two refusals and the collected
`problems`, and the limits.

Prose written and revised by docs-writer against the public surface and the
tests, reviewed by docs-editor (SHIP, four nits, applied by the writer).
Docusaurus build clean with no broken-link warnings.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@vercel

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

Request Review

@linear-code

linear-code Bot commented Sep 19, 2026

Copy link
Copy Markdown

FIX-1405

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

Code Snob — outcome 3: already tight. No POC.

Read: packages/workforce/src/inventory/open-inventory.ts (the walker), packages/workforce/src/channel/channel-flow.ts (inventoryWriterActions and the inventory? spread), packages/workforce/src/channel/channel-binder.ts (the inventoryChannelFlow memo, exported kindOf / orderedById), the two barrels, packages/workforce/src/inventory/collections.ts (the floor the rows land on), and packages/workforce/test/inventory-binder.test.ts.

The new contract is two dispatches and two handlers: seats in one run through a named seatWriter, each channel writing its own row from its own session. A rewrite does not shrink that. Sharing kindOf / orderedById with openChannels is the one derivation that had to stay single; putting the seat writer on the channel kind is the recorded way to keep seatWriter to one field.

Rejected as not a different shape: orderedById(roster.seats) instead of the inline sort; dropping the { id, kind } rematerialize; a shared messageOf; deleting the factory memo; moving inventoryWriterActions to its own file; collapsing InventorySeatWriter into an inline type; stripping the essay comments (density matches openChannels / defineChannelFlow). Folding this into openChannels or deriving seatWriter would change the two-call boot that was already signed off.

Leftovers left alone: membership prune / reconcile (filed as follow-up).

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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 (FIX-1405)

Parallel read-only passes (code quality, performance, reuse) on the PR diff.

Verdict: The core approach is the right tradeoff, not an over-engineered detour. Approve from a simplify lens, with nits below.

Did this go too far?

The two-writer split is doing real work:

  • Seats: one batched action (no session).
  • Channels: per-channel registerChannelInInventory with empty input so members come from live session state, not roster files.

Upserting channel rows from ChannelManifest would be less code but would republish file-time members: under a live name (the PR invariant; tests encode it). The app-supplied run door and pinned action names are awkward DX but match openChannels (no client package in workforce, multi-flowKind at boot). I would not simplify by bypassing flow actions for org-scoped collections.

Complexity that does not change the model:

  1. ~190 lines of inventory writer actions inside already-large channel-flow.ts — consider inventory/inventory-writer-actions.ts.
  2. Inventory imports kindOf / orderedById from channel-binder — consider a neutral shared module.
  3. Triplicated messageOf across boot binders — small DRY win.
  4. Inline seat sort while channels use orderedById — reuse orderedById for seats.

Alternatives considered

  • fast-glob/chokidar: boot is action-driven, not a disk walk.
  • Single openWorkforceBoot() helper: DX only; does not remove the two writer paths.
  • Parallel per-channel run calls: optional boot perf; needs concurrency policy + tests.
  • Batch membership upserts: valid follow-up for wide channels.

Performance

Serial run per channel and per-member membership upserts are O(N) at boot — fine for typical rosters.

Docs

README API table has two mismatches with code (inline).

Please fix README drift; channel-flow extract can be this PR or a quick follow-up.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/workforce/README.md Resolved
Comment thread packages/workforce/README.md Resolved
* reach; there is no undoing a row that should not have been removed.
*/

import { kindOf, orderedById } from "../channel/channel-binder";

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.

Layer coupling: inventory imports kindOf / orderedById from channel-binder. Consider channel/manifest-kinds.ts or a deliberate public export so inventory does not depend on binder internals.

* actions: { ...myActions, ...inventoryWriterActions("briefing") }
* });
*/
export function inventoryWriterActions(kind: string) {

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.

Structure: consider extracting inventoryWriterActions to inventory/inventory-writer-actions.ts — same API, easier navigation than growing this 1k+ line file.

// The index is a projection of the row above, written from the same read
// of the same session state in the same run. It is never written alone,
// which is what stops the two from ever disagreeing.
for (const seatId of members) {

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.

Boot perf (optional): one memberships.upsert per member; batch or bounded parallelism only if wide channels become common.

Copy link
Copy Markdown
Collaborator Author

second-look: PR #1928

Verdict: Appropriately scoped — no candidate here clears the bloat calibration gate; the surface tracks the already-approved spec's decisions, with real consumers (tests, docs, custom-kind path) for every abstraction added.
Scope: +1611 / −38 across 12 files → production code ~+584/−8 (open-inventory.ts new, channel-flow.ts, channel-binder.ts, two index.ts re-export files), tests +664, docs (README + docs site) +358/−30, changeset +5.

Went through the five lenses (premise, requirement origin, YAGNI, 80/20, hindsight) plus a check for a while-you're-here improve-codebase-architecture opportunity. Nothing produced a finding with a Δlines number worth a row — see below for what was examined and why it was kept as-is.

Considered & deemed justified

  • Two-writer split (seats via one flow-run dispatch, channels via their own session) — the PR's own "Deviations from spec" section already shows the simpler single-writer plan in PLAN.md isn't reachable (no non-flow door writes collection state); this is the smallest shape that is.
  • Membership index collection, written but never pruned — a real second consumer (seat→channels lookup by prefix) exists in the docs/tests, and "no prune yet" is deliberately scoped to the reconcile follow-up rather than speculative code for a state that can't occur yet.
  • inventoryWriterActions(kind) as a factory rather than inlined once — exercised by two real call sites in this diff (defineChannelFlow's built-in, and the test's hand-rolled briefingKind), not built for a hypothetical second caller.
  • Per-block ctx.org === undefined guards duplicating openInventory's own orgId check — not redundant defense against an impossible case: the actions are public and reachable independent of openInventory (the PR body flags this itself), so the block-level guard covers a real second path the binder's guard doesn't reach.
  • apps/docs/docs/workforce/inventory.md reads as a near-duplicate of the README's new section — this matches the existing per-feature pattern already in this package (e.g. channels.md beside the README's Channels section), not something this PR introduced.

One optional, non-blocking note (didn't clear the gate, flagging since it's cheap)

open-inventory.ts:166 adds a third private copy of messageOf (error instanceof Error ? error.message : String(error)) — one already exists in channel-binder.ts:199 and hire.ts:166, both pre-existing. CLAUDE.md's Coding Conventions say common helpers like this belong in a shared file, not duplicated per-file. Small enough on its own that it doesn't earn a scored finding (net line change is roughly a wash once you add the import), but since this PR is the third instance in the same package, it's a cheap spot to introduce one shared messageOf in a small lib file if whoever picks this up wants to. Not asking for a change — noting it since another look at this package will hit the same duplication a fourth time otherwise.

No action needed from this comment alone — informational second-look pass, not a review verdict.


Generated by Claude Code

Comment thread packages/workforce/README.md Resolved
"@flow-state-dev/workforce": patch
---

`openInventory` fills the live workforce inventory at boot: one row per hired seat, and one per open channel written by that channel itself from its own session state. `channelInstances({ inventory: true })` builds the built-in channel kind carrying the writer, and `inventoryWriterActions(kind)` puts the same two actions on a hand-rolled channel kind (FIX-1405).

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.

P2 Changeset includes internal rationale

The release note names FIX-1405, but it also explains internal writer placement, session ownership, and hand-rolled kind construction. The repository requires changesets to be concise, consumer-facing sentences and excludes implementation rationale. Reduce this to what consumers can now do and any wiring they must add before merging.

Rule Used: For changeset reviews in this repository, require at least a one-sentence user-facing description naming the Linear issue. Flag additional material when it is implementation rationale, decision lineage, file paths, exact test counts, out-of-scope sec... (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Cursor

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

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 4cd4f13. Configure here.

…oid partial commit, document the seat-write exposure

- packages/workforce/README.md: correct two wrong lines in the exports
  table (INVENTORY_SEAT_WRITER_SESSION's real value, InventoryBinding's
  real shape) found by a doc-vs-source sweep of the whole "live inventory"
  section; add a callout that registerSeatsInInventory is a public action
  whose input is unvalidated row data, with the app-level mitigation
  (authentication.resolvePrincipal keyed on envelope.action).
- channel-flow.ts: write membership rows before the channel row they are
  named from, so a member id that can never become a valid membership key
  fails before anything is written instead of leaving a channel row with
  no matching index row (regression test added); replace the explicit
  `ctx: BlockContext` annotations on the two inventory-writer blocks with
  inferred ctx, matching every other block in the file, which drops the
  `as Record<string, any>` cast; rewrite the "public rather than internal"
  comment, which claimed a safety property that only held for one of the
  two actions, to say plainly what registerSeatsInInventory does and does
  not guard against.
- open-inventory.ts: reuse the already-imported orderedById instead of an
  inline copy of the same comparator.
- collections.ts: seat row id/kind reject the empty string.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T

jhoffner commented Sep 19, 2026 •

Copy link
Copy Markdown
Collaborator Author

Pushed 4b0e25e7c covering this round's findings (Cursor Automation, Greptile, Cursor Bugbot), then f8673a51d closing the seats-forging exposure for real (see the update at the bottom — the paragraph below is left as originally posted, since it's what I tried first and why). Verified everything at source before changing anything; here's what changed and why.

Fixed

README/exports drift (Cursor Automation, Greptile). INVENTORY_SEAT_WRITER_SESSION's table row said "__inventory_seat_writer__"; the actual constant is "inventory-binder" (open-inventory.ts:95). InventoryBinding's row said { channelId, ok, error? }; the actual shape is { seats, channels, problems } (open-inventory.ts:153, and correctly stated two rows above by openInventory's own row). Both fixed.

Full sweep of the rest of the section, as asked. I checked every factual claim (name, literal value, type shape, signature, default, return) the PR's new prose makes in README.md's "The live inventory" section and the new apps/docs/docs/workforce/inventory.md against the actual exported source — collection patterns/schemas, openInventory/inventoryWriterActions/channelInstances signatures, membershipKey/membershipPrefix behavior, the error-semantics rows, the code samples. Result: 2 wrong, both already named above. Nothing else in the sweep was wrong.

Registration can partially commit (Greptile P1 + Cursor Bugbot, converging). Real, and Bugbot's addition was the constraint that mattered: a malformed member id fails membershipKey the same way on every boot, so retry alone doesn't fix it. Fix: membership rows are now written before the channel row that names them, and every member's key is validated up front, before any write — so a permanently-bad member id (or a store failure) leaves nothing behind instead of a channel row with no matching index row. Added a regression test (inventory-binder.test.ts) that reproduces the old bug: red before the fix (channel row + one membership row landed despite the throw), green after (nothing lands, on repeated attempts). What this doesn't buy, and I said so in the comment: a membership row from an earlier successful boot can still outlive a later failed boot's channel-row update — stale, not contradictory, and this system already doesn't prune stale rows by design (documented elsewhere in the same PR). Full atomicity across independent resource-collection writes isn't available without engine-level transaction support, which is out of this package's and this round's scope.

Public action forges seats (Greptile P1, security) — documented closed. Original assessment, superseded below: Confirmed real: registerSeatsInInventory was a public action (flow.actions, HTTP/MCP-reachable by any authorized principal), its whole input was caller-supplied {id, kind} rows, and — unlike registerChannel, which takes an empty input and derives everything from the channel's own already-open session state — there was nothing in this package to validate a seat row against. I first shipped a documentation-only mitigation (an accurate comment, a README callout, and an app-level authentication.resolvePrincipal gate as the available-today workaround) because I'd read both real closures as out of this round's scope. That's not where it landed — see Update: the exposure is now actually closed below.

orderedById(roster.seats) (Cursor Automation). Took it — it's not a shape disagreement, the inline comparator was byte-for-byte the same body as the already-imported, already-used-two-lines-below orderedById. Matches CLAUDE.md's "no duplicate copies" convention directly.

ctx.resources as Record<string, any> (Cursor Automation). Removed on both blocks. Every other block in channel-flow.ts leaves ctx untyped and gets ctx.resources.X correctly typed from handler(...)'s generics; the two new blocks were the only ones annotating ctx: BlockContext explicitly, which threw that inference away and forced the cast. Confirmed by just removing the annotations — clean typecheck, no cast needed.

Declined, with reasons

  • Extract inventoryWriterActions to its own file (Cursor Automation). Reviewer offered "this PR or a follow-up." Pure file-organization, no correctness stake, and I'd already touched this file for the P1 fix — declining to widen the diff further; restraint over structure churn.
  • kindOf/orderedById layer coupling (Cursor Automation). The PR body already records this as a deliberate call: a second derivation of "which flow is this channel on" would silently diverge from openChannels's own. Re-checked both call sites — the reasoning still holds; not re-litigating a settled call.
  • Batch memberships.upsert (Cursor Automation). Reviewer marked it optional, conditional on wide channels becoming common. No evidence that's the case yet.
  • Changeset includes internal rationale (Greptile P2). Read it against AGENTS.md's changeset guidance and against sibling changesets in .changeset/ (channel-boards.md, custom-tools-authoring.md, olive-rings-tap.md). Every line in inventory-binder.md names public API (openInventory, channelInstances({inventory:true}), inventoryWriterActions(kind)) and what it does — no file paths, no test counts, no decision lineage. That's the established house style, not a violation.

Update: the exposure is now actually closed (f8673a51d)

Went back to the seats-forging finding and did the thing I'd ruled out as too big for a review round: built the internal.actions + runAction({ source: "internal" }) split, ran the suite, and found out empirically what it costs. It works, cleanly, with no engine changes.

What changed. inventoryWriterActions(kind) still returns its two blocks by action name, but the built-in channel kind (defineChannelFlow) now spreads them across two different maps instead of one:

  • registerChannelInInventory stays in flow.actions (public) — it takes no input and derives its row entirely from the channel's own already-open session state, so it's harmless from any caller, same as before.
  • registerSeatsInInventory moves to flow.internal.actions — its whole input is caller-supplied row data, with nothing to validate it against, so it no longer has a public entry at all.

resolveEntry reads exactly one action map per dispatch type with no fallback between them (packages/engine/src/execution/resolve-action-core.ts). A caller-addressed HTTP or MCP request always dispatches as public and can now never resolve registerSeatsInInventory — there's no code path from a request to that map. The only way in is the direct, trusted runAction({ source: "internal", ... }) call openInventory makes for it.

InventoryActionRequest gained an optional source?: string field; openInventory sets it to "internal" on the seat-write request, and an app's run door forwards it straight into runAction's own source option. Updated the README, the docs page, and the test harness's run() to show/do this.

Evidence, not just "tests pass":

  • Added registerSeatsInInventory cannot be reached through the public door to inventory-binder.test.ts. Verified genuinely red first: with the two-map split reverted (both actions back in the flat actions spread), the test's forged-seat call succeeded and inventory/seats/attacker.fake was written. Restored the split: the same call now gets does not define action "registerSeatsInInventory" and nothing is written.
  • pnpm --filter @flow-state-dev/workforce test — 597/597 passing (596 from the prior round + this one).
  • pnpm --filter @flow-state-dev/workforce typecheck — clean.
  • pnpm --filter @flow-state-dev/docs build — clean (this round touches apps/docs/docs/workforce/inventory.md).

The one real cost. InventoryActionRequest has a new field that a run() door must forward for the seat write to land at all. This is additive and fails closed, not open: a door that doesn't know about source yet gets runAction's default ("http"), the seat write becomes unreachable the same way a forged call would be, and openInventory reports it in problems instead of silently succeeding. No app breaks; an app that upgrades and doesn't touch its run() just stops getting seat rows until it forwards the field, which is visible immediately rather than a latent security gap.

The README callout and app-level mitigation from the first pass are replaced with a plain description of where the action lives and why (see packages/workforce/README.md's "Where the seat rows go" and the docs page's "Writing from your own kind"), since there's no longer a live exposure to mitigate around.

Threads addressed by either push are resolved below.


Generated by Claude Code

registerSeatsInInventory now lives only in the channel kind's
internal.actions map, not its public actions map. resolveEntry reads
exactly one map per dispatch type with no fallback, so a caller-addressed
HTTP or MCP request can never resolve into it — only the trusted, direct
runAction({ source: "internal" }) call openInventory makes for it.
registerChannelInInventory stays public; it takes no input and derives
its row from the channel's own already-open session state, so it is
harmless from any caller.

InventoryActionRequest gains an optional `source` field that openInventory
sets to "internal" on the seat write; an app's `run` door must forward it
into runAction's own `source` option for the write to land. Dropping it
fails closed (the write becomes unreachable, named in `problems`), not
insecure.

Adds a regression test proving the seat-write action cannot be reached
through the public door, verified RED (forged row written) against the
prior single-actions-map shape before the split, GREEN after. Updates the
README and the live-inventory docs page to describe the split and show
`run` forwarding `source`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
jhoffner pushed a commit that referenced this pull request Sep 19, 2026
Folds the two settled child PRs and the findings they carried back up:

- #1928 (FIX-1405 S5-S7) and #1929 (FIX-1430) are open, green and mergeable;
  the set table, the dependency read and the path figure all move.
- ER-20 stays OPEN with its row at NOT RUN: the acceptance goal calls a real
  model and no environment here has an inference key. The wrap term is
  enforced against the rule as written, in all three places it is stated.
- Drain width is 1 - work queues behind a busy seat. Closes FIX-1408's
  auto-scale wall on FIX-1430's evidence; citable at DECISIONS.md#drain-width.
- BR-5 and BR-11 of FIX-1430 had their stated mechanism refuted by the code.
  Both rules stand; the corrected mechanisms are recorded at
  DECISIONS.md#refuted-mechanisms and sharpen ER-4's "checked at".
- The sub-agent-on-a-board-row question is recorded unowned and named out at
  the wrap, beside ER-19's repo-wide pass and the unminted-board-id residue,
  so none can close as a pass nobody ran.
- ER-14 is contested and UNRESOLVED: #1928 is a ship PR by the fence's letter
  while FIX-1435 is still Todo, and the overlap is empty by file. Written as a
  pending re-gate with the recommendation named as the epic's, not the owner's.
  ER-14's own row is untouched.

Editorial pass alongside: derivation cut, the three phrases the EDITING NOTEs
protect held deliberately. Prose words SPEC 2065->1579, DECISIONS 3516->3120,
BUSINESS-RULES 1803->1710, PLAN 1908->1577.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxDE76gD3BxXnPPjT7BT1T
@jhoffner
jhoffner merged commit 8428614 into main Sep 19, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Sep 19, 2026
Four of five children are now complete. The gate is not.

- FIX-1405 terminal: #1920, #1923 and #1928 all merged (#1928 merged by the
  owner at 15:08:04Z, merge commit 8428614).
- FIX-1430 terminal: #1929 merged (15:11:47Z, merge commit 45ef6d7) off head
  78bc4f8.
- FIX-1394 is the only child still open; its matrix #1921 never merges and its
  ratify waits on the documents question.

ER-20 is unchanged and still reads NOT RUN. Merging the proof did not run the
proof. The spec now says plainly that every child of the set can be complete
while the thing the set exists to prove has never been observed, so nobody
reads "everything merged" as "the epic is done". The wrap stays enforced
against the rule as written, and the two things in front of it are both the
owner's: the documents question, and a machine with an inference key.

ER-14, recorded precisely and deliberately narrowly:

- The owner merged #1928 through a live fence - FIX-1435 has no branch and no
  PR at all, verified here, not remembered. That act SETTLES #1928. It is not
  a breach and nothing about it needs remediation.
- It is NOT an answer about the rule. He has said nothing. The re-gate keeps
  stating the narrowing recommendation as the epic's and unanswered, and the
  merge is not cited as approval anywhere.
- What is recorded as decided is only the epic's own OPERATING DEFAULT
  (DECISIONS.md#fence-default): treat the fence as narrowed to per-PR file
  overlap, read from his action rather than his words, countermandable by him
  at any time.
- ER-14's row text is byte-identical again. Only the note around it moved.
- ER-14's remaining bite is named: FIX-1394's eventual ship PR, and the wrap.

Path figure redrawn and looked at in both themes: FIX-1405 and FIX-1430 become
merged bars, and FIX-1430's runs straight into the red ER-20 NOT RUN gate -
which is the picture worth having right now.

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