Repository navigation
feat(FIX-1381): a seat reaches the documents its file names — resources: with ro/rw
#1943
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
68d836a
feat: a seat reaches the documents its file names (FIX-1381)
claude 669f900
fix: drop the dangling spec path from the test header (FIX-1381)
claude 435623c
fix: a denied document cannot come back through a block (FIX-1381)
claude 792c8e1
fix: a document's ref must hold that document, and leg (f) must be ab…
claude File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| "@flow-state-dev/workforce": minor | ||
| --- | ||
|
|
||
| A `WORKER.md` can declare `resources:`, the documents that seat may touch — naming one grants read, `rw` grants write — and the app supplies its documents through a new `documents` option on `hireWorkforce` (FIX-1381). | ||
|
|
||
| Migration: `resources` is now read by the hire step rather than passed on as a setting, so a worker kind that declared a `resources` setting of its own must rename that setting before upgrading — it no longer receives an authored value. A seat that declares no `resources:` key keeps the reach it has today. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
135 changes: 135 additions & 0 deletions
135
goals/workforce-seats/a-seat-reaches-the-documents-its-file-names/fixtures/flows.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,135 @@ | ||
| /** | ||
| * One worker kind, built the way an app builds one: the documents its | ||
| * `resources/` folder declared, spread into a flow-level map beside a store of | ||
| * its own. | ||
| * | ||
| * A factory rather than a module-level constant, because the documents come off | ||
| * disk. That is also what makes the fixture honest: the flow-level map holds a | ||
| * `${STORE}` the allowlist must never touch, beside documents it must narrow. | ||
| * A fixture whose flow-level map held nothing but documents would be green for | ||
| * a resolver that silently deletes the app's own machinery. | ||
| * | ||
| * No model, no generator. What is graded is which resources reached a running | ||
| * block and which of them it could write. | ||
| */ | ||
| import { defineFlow, defineResource, handler, sequencer } from "@flow-state-dev/core"; | ||
| import type { DeclaredResources } from "@flow-state-dev/core"; | ||
| import type { ResourceDoc } from "@flow-state-dev/workforce"; | ||
| import { resourcesFromDocs, workerConfigSchema } from "@flow-state-dev/workforce"; | ||
| import { z } from "zod"; | ||
|
|
||
| export const DESK_KIND = "desk"; | ||
|
|
||
| /** The app's own store, declared at flow level beside the documents. Not a document. */ | ||
| export const STORE = "audit-log"; | ||
|
|
||
| const auditLog = defineResource({ | ||
| ref: STORE, | ||
| scope: "org", | ||
| stateSchema: z.object({ entries: z.array(z.string()).default([]) }), | ||
| default: { entries: [] }, | ||
| writable: true | ||
| }); | ||
|
|
||
| const inputSchema = z.object({ note: z.string() }); | ||
|
|
||
| /** What the seat records about what it could actually touch. */ | ||
| const seatState = z.object({ | ||
| /** Every resource key the block resolved, sorted. */ | ||
| reach: z.array(z.string()).nullable().default(null), | ||
| /** Every one of those it could also write, sorted. */ | ||
| wrote: z.array(z.string()).nullable().default(null), | ||
| runs: z.number().default(0) | ||
| }); | ||
|
|
||
| const start = handler({ | ||
| name: "desk-start", | ||
| inputSchema, | ||
| execute: async (_input, ctx) => { | ||
| await ctx.session.incState({ runs: 1 }); | ||
| } | ||
| }); | ||
|
|
||
| /** | ||
| * The nested read — what this seat can reach, and what it can write. | ||
| * | ||
| * Both halves are probed by DOING them, never by reading a flag: `ro` is only | ||
| * worth anything if the write actually refuses at the seam, and a check that | ||
| * asserted `writable === false` would pass for a flag nothing consults. | ||
| */ | ||
| function probe(keys: readonly string[]) { | ||
| return handler({ | ||
| name: "desk-probe", | ||
| inputSchema, | ||
| outputSchema: z.void(), | ||
| // Every document is org-scoped, and a flow collects `requiresOrg` from its | ||
| // blocks rather than from its resource map. Without this the request is | ||
| // admitted with no org, no org registry is built, and every document reads | ||
| // as unregistered — a green `reach: []` for the wrong reason. | ||
| requireOrg: true, | ||
| sessionStateSchema: seatState, | ||
| execute: async (_input, ctx) => { | ||
| const reach: string[] = []; | ||
| const wrote: string[] = []; | ||
| for (const key of keys) { | ||
| let ref: { setState(next: Record<string, unknown>): Promise<void> } | undefined; | ||
| try { | ||
| ref = ctx.resources.get(key) as unknown as typeof ref; | ||
| } catch { | ||
| continue; | ||
| } | ||
| if (ref === undefined) continue; | ||
| reach.push(key); | ||
| try { | ||
| await ref.setState({ touched: true }); | ||
| wrote.push(key); | ||
| } catch { | ||
| // A refused write is the point of the `ro` half, not an error here. | ||
| } | ||
| } | ||
| await ctx.session.patchState({ reach: reach.sort(), wrote: wrote.sort() }); | ||
| } | ||
| }); | ||
| } | ||
|
|
||
| const clientView = { | ||
| derived: { | ||
| ran: (ctx: { state: { reach?: string[] | null; wrote?: string[] | null; runs?: number } }) => ({ | ||
| reach: ctx.state.reach ?? null, | ||
| wrote: ctx.state.wrote ?? null, | ||
| runs: ctx.state.runs ?? 0 | ||
| }) | ||
| } | ||
| }; | ||
|
|
||
| /** | ||
| * Build the kind from the documents the loader found. | ||
| * | ||
| * Returns the catalog too, because that is the same map the app hands | ||
| * `hireWorkforce` as `documents` — one list, spread into the flow and passed to | ||
| * the hire step, never built twice. | ||
| */ | ||
| export function buildDesk(documents: ResourceDoc[]): { | ||
| deskFlow: ReturnType<typeof defineFlow>; | ||
| catalog: DeclaredResources; | ||
| probedKeys: string[]; | ||
| } { | ||
| const catalog = resourcesFromDocs(documents); | ||
| const probedKeys = [...Object.keys(catalog), STORE].sort(); | ||
|
|
||
| const deskFlow = defineFlow({ | ||
| kind: DESK_KIND, | ||
| cardinality: "collection", | ||
| configSchema: workerConfigSchema(), | ||
| resources: { ...catalog, [STORE]: auditLog } as DeclaredResources, | ||
| actions: { | ||
| run: { | ||
| inputSchema, | ||
| block: sequencer({ name: "desk-work", inputSchema }).tap(start).tap(probe(probedKeys)) | ||
| } | ||
| }, | ||
| session: { stateSchema: seatState, client: clientView } | ||
| }); | ||
|
|
||
| return { deskFlow, catalog, probedKeys }; | ||
| } |
28 changes: 28 additions & 0 deletions
28
goals/workforce-seats/a-seat-reaches-the-documents-its-file-names/fixtures/input.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| { | ||
| "userId": "u_seat_resource_allowlist_goal", | ||
| "note": "Who is allowed to read payroll?", | ||
| "documents": ["handbook", "payroll"], | ||
| "store": "audit-log", | ||
| "seats": { | ||
| "lead": { | ||
| "id": "engineering.lead", | ||
| "reaches": ["handbook"], | ||
| "writes": [] | ||
| }, | ||
| "cfo": { | ||
| "id": "engineering.cfo", | ||
| "reaches": ["payroll"], | ||
| "writes": ["payroll"] | ||
| }, | ||
| "chief": { | ||
| "id": "engineering.chief", | ||
| "reaches": ["handbook", "payroll"], | ||
| "writes": ["handbook", "payroll"] | ||
| } | ||
| }, | ||
| "control": { | ||
| "dir": "typo", | ||
| "id": "engineering.typo", | ||
| "ref": "hanbdook" | ||
| } | ||
| } |
8 changes: 8 additions & 0 deletions
8
...documents-its-file-names/fixtures/typo/teams/engineering/workers/typo/WORKER.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| description: The same desk, with one character wrong in its grant. | ||
| flow: desk | ||
| resources: | ||
| - hanbdook | ||
| --- | ||
|
|
||
| You meant the handbook. |
9 changes: 9 additions & 0 deletions
9
...aches-the-documents-its-file-names/fixtures/workforce/org/resources/handbook.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| description: How the engineering team works — on-call, review, escalation. | ||
| llmReadable: true | ||
| llmWritable: true | ||
| --- | ||
|
|
||
| # Engineering handbook | ||
|
|
||
| Escalate anything customer-visible within 15 minutes. |
9 changes: 9 additions & 0 deletions
9
...eaches-the-documents-its-file-names/fixtures/workforce/org/resources/payroll.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| description: What every seat on the roster is paid. | ||
| llmReadable: true | ||
| llmWritable: true | ||
| --- | ||
|
|
||
| # Payroll | ||
|
|
||
| Not everybody's business. |
8 changes: 8 additions & 0 deletions
8
...ments-its-file-names/fixtures/workforce/teams/engineering/workers/cfo/WORKER.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| description: Holds anything about money. | ||
| flow: desk | ||
| resources: | ||
| - payroll: rw | ||
| --- | ||
|
|
||
| You keep payroll current. |
6 changes: 6 additions & 0 deletions
6
...nts-its-file-names/fixtures/workforce/teams/engineering/workers/chief/WORKER.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| --- | ||
| description: The seat that was here before any of this and declares no resources. | ||
| flow: desk | ||
| --- | ||
|
|
||
| You see everything this app declared, as you always did. |
8 changes: 8 additions & 0 deletions
8
...ents-its-file-names/fixtures/workforce/teams/engineering/workers/lead/WORKER.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| description: Holds the engineering board and breaks work into tasks. | ||
| flow: desk | ||
| resources: | ||
| - handbook | ||
| --- | ||
|
|
||
| You are the engineering lead. You consult the handbook; you do not rewrite it. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.