Repository navigation
DO NOT MERGE: Workforce POC — static board notify (FIX-1311) #1627
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
Closed
Closed
Changes from all commits
Commits
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
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,79 @@ | ||
| # Workforce POC — static board notify (FIX-1311) | ||
|
|
||
| Throwaway lab. Proves a message-board **notify** path on today's APIs: a | ||
| topic-scoped collection, subscribers in collection state, `reactTo` fan-out | ||
| through a **router over declared dispatchers**. No Workforce package. No | ||
| TeamFlow / MessageBoard L1. No dynamic `dispatcher()` from string data. | ||
|
|
||
| **Do not merge this as product API.** Findings go on | ||
| [`fsd/workforce/pocs`](https://github.com/fixpoint-labs/agent-mailbox/pull/12). | ||
|
|
||
| ## Run | ||
|
|
||
| ```bash | ||
| pnpm --filter @flow-state-dev/workforce-poc-board-notify test | ||
| pnpm --filter @flow-state-dev/workforce-poc-board-notify demo | ||
| ``` | ||
|
|
||
| ## What was proved | ||
|
|
||
| 1. A board is a `defineResourceCollection({ pattern: "boards/*", scope: "user" })`. | ||
| Topic is the instance key. Subscribers live in instance state, including | ||
| documentary `flow` / `sessionId` / `entry` fields. | ||
| 2. A new thread row fires `reactTo.stateUpdated`. The bound sequencer iterates | ||
| subscribers and dispatches fire-and-forget through `notify-alice` / | ||
| `notify-bob` — both declared at `defineFlow` time, both targeting | ||
| `internal.actions.onNotify`. | ||
| 3. A stored `entry: "invented-from-data"` does **not** change the hop. The | ||
| fence is `packages/core/src/types/dispatch.ts`: | ||
|
|
||
| > A target chosen from data is a router over declared dispatchers, not a | ||
| > dynamic address. | ||
|
|
||
| 4. Same-flow only. Another flow kind is `session-not-addressable` at | ||
| `packages/engine/src/context/create-request-host.ts:179`. This lab does | ||
| not invent a second bus. Cross-flow waits on #1600. | ||
| 5. Existing-session create is still 409 (FIX-1246). Not papered over. | ||
| 6. Prune on `no-entry` / `session-not-found` only. Never on | ||
| `dispatch-rejected` (classifier; the live hop did not produce that | ||
| refusal — see below). Never on `session-not-addressable` until that | ||
| refusal is split. | ||
|
|
||
| Same-session notify from `reactTo` **lands**. A poster who is also a | ||
| subscriber gets `onNotify` in their own session. `concurrency: "reject"` | ||
| on the entry does not treat the originating turn as a competing holder. | ||
| Do not read that as `dispatch-rejected`, and do not prune it. | ||
|
|
||
| ## What was faked with static targets | ||
|
|
||
| Seats are a closed enum (`alice` | `bob`). A subscription **selects among** | ||
| those two declared dispatchers. Session id still comes from subscriber data | ||
| (`session: { id: (input) => input.sessionId }`) — that is today's existing | ||
| door, not a new address kind. A roster that names an arbitrary entry from | ||
| state still cannot become a dispatcher. | ||
|
|
||
| `no-entry` is untestable as a runtime prune under static addresses: | ||
| `defineFlow` refuses a dispatcher whose target is missing. The classifier | ||
| covers it; the live hop cannot name a dangling entry. | ||
|
|
||
| ## What still needs substrate | ||
|
|
||
| | Gap | Why this lab cannot close it | | ||
| |---|---| | ||
| | Dynamic addresses / addresses-as-data | A subscriber's `entry` is data. Using it as `dispatcher({ target })` is the thing the fence forbids. | | ||
| | Flow instances / multi-hire same-kind | FIX-1320–1323. One flow, two seats, session id distinguishes them. | | ||
| | Cross-flow conversation | #1600. `flowKind !== flow.kind` → `session-not-addressable`. | | ||
| | Housekeeper CAS on the brief | Two concurrent posts can each rewrite the brief. Needs the collection's version CAS — do not invent a store. Design-note only. | | ||
| | Teams / TeamFlow | FIX-1310. Out of scope. | | ||
|
|
||
| ## Brief / thread | ||
|
|
||
| Cheap split: `brief` is a current-state string, `thread` is append-only. | ||
| `post` may set the brief in the same write. No housekeeper job. | ||
|
|
||
| ## What this is not | ||
|
|
||
| - Not Lab A (factory / DM / group fan-out from a `post` sequencer). | ||
| - Not Lab B (claim / reply-storm). | ||
| - Not FIX-957 / `materializeAgent` / FIX-796. | ||
| - No changeset. Private lab. |
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 @@ | ||
| { | ||
| "name": "@flow-state-dev/workforce-poc-board-notify", | ||
| "version": "0.0.0", | ||
| "private": true, | ||
| "type": "module", | ||
| "description": "Throwaway Workforce POC: static board notify via reactTo over declared dispatchers. Never merges as product API.", | ||
| "main": "./src/index.ts", | ||
| "exports": { | ||
| ".": "./src/index.ts" | ||
| }, | ||
| "scripts": { | ||
| "typecheck": "tsc --noEmit", | ||
| "test": "vitest run --root .", | ||
| "test:watch": "vitest --root .", | ||
| "demo": "tsx src/run.ts" | ||
| }, | ||
| "dependencies": { | ||
| "@flow-state-dev/core": "workspace:*", | ||
| "@flow-state-dev/engine": "workspace:*", | ||
| "zod": "^3.25.76" | ||
| }, | ||
| "devDependencies": { | ||
| "@types/node": "^22.0.0", | ||
| "tsx": "^4.21.0", | ||
| "typescript": "^5.9.3", | ||
| "vitest": "^3.2.4" | ||
| } | ||
| } |
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,111 @@ | ||
| /** | ||
| * Host-side bootstrap through today's `create_session` route. | ||
| * | ||
| * FIX-1246 is left as a 409 — this lab does not invent around an existing session. | ||
| */ | ||
| import type { FlowInstance } from "@flow-state-dev/core/types"; | ||
| import { | ||
| createFlowState, | ||
| inMemoryStores, | ||
| runAction, | ||
| type FlowState, | ||
| type FlowStateRuntime | ||
| } from "@flow-state-dev/engine"; | ||
| import { boardNotifyFlow, otherKindFlow } from "./flow"; | ||
|
|
||
| export const USER_ID = "workforce-poc-board-notify-user"; | ||
|
|
||
| export interface LabHost { | ||
| state: FlowState; | ||
| runtime: FlowStateRuntime; | ||
| flows: Record<string, FlowInstance>; | ||
| createSession: ( | ||
| flowKind: string, | ||
| sessionId: string, | ||
| title?: string | ||
| ) => Promise<{ id: string; flowKind: string; title?: string; status: number; error?: string }>; | ||
| call: ( | ||
| flowKind: string, | ||
| action: string, | ||
| input: unknown, | ||
| sessionId: string | ||
| ) => Promise<{ output: unknown; error?: { message?: string } }>; | ||
| sessionState: (sessionId: string) => Promise<Record<string, unknown> | undefined>; | ||
| dispose: () => Promise<void>; | ||
| } | ||
|
|
||
| export async function bootLab( | ||
| flows: Record<string, FlowInstance> = { | ||
| [boardNotifyFlow.kind]: boardNotifyFlow, | ||
| [otherKindFlow.kind]: otherKindFlow | ||
| } | ||
| ): Promise<LabHost> { | ||
| const state = createFlowState({ | ||
| flows, | ||
| stores: { default: { primary: inMemoryStores() } } | ||
| }); | ||
| const runtime = await state.getRuntime(); | ||
| const router = await state.getRouter(); | ||
|
|
||
| return { | ||
| state, | ||
| runtime, | ||
| flows, | ||
| async createSession(flowKind, sessionId, title) { | ||
| const response = await router.POST( | ||
| new Request(`http://localhost/api/flows/${encodeURIComponent(flowKind)}/sessions`, { | ||
| method: "POST", | ||
| headers: { "content-type": "application/json" }, | ||
| body: JSON.stringify({ userId: USER_ID, sessionId, title }) | ||
| }), | ||
| { params: { path: [flowKind, "sessions"] } } | ||
| ); | ||
| const text = await response.text(); | ||
| if (response.status !== 201) { | ||
| return { id: sessionId, flowKind, status: response.status, error: text }; | ||
| } | ||
| const body = JSON.parse(text) as { | ||
| session: { id: string; flowKind: string; title?: string }; | ||
| }; | ||
| return { ...body.session, status: 201 }; | ||
| }, | ||
| async call(flowKind, action, input, sessionId) { | ||
| const flow = flows[flowKind]; | ||
| if (flow === undefined) { | ||
| throw new Error(`no flow registered as "${flowKind}"`); | ||
| } | ||
| const result = await runAction({ | ||
| flow: flow as never, | ||
| actionName: action as never, | ||
| input: input as never, | ||
| userId: USER_ID, | ||
| sessionId, | ||
| stores: runtime.stores, | ||
| runtimeConfig: { ...runtime.runtimeConfig } | ||
| }); | ||
| const outcome = result as { | ||
| output?: unknown; | ||
| error?: { message?: string }; | ||
| }; | ||
| return { output: outcome.output, error: outcome.error }; | ||
| }, | ||
| async sessionState(sessionId) { | ||
| const record = await runtime.stores.session.get(sessionId); | ||
| return record?.state as Record<string, unknown> | undefined; | ||
| }, | ||
| async dispose() { | ||
| await state.dispose(); | ||
| } | ||
| }; | ||
| } | ||
|
|
||
| export async function until( | ||
| predicate: () => boolean | Promise<boolean>, | ||
| label: string | ||
| ): Promise<void> { | ||
| for (let attempt = 0; attempt < 200; attempt += 1) { | ||
| if (await predicate()) return; | ||
| await new Promise((resolve) => setTimeout(resolve, 10)); | ||
| } | ||
| throw new Error(`timed out waiting for ${label}`); | ||
| } | ||
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Triple
as neveron flow/action/input erases all type safety and propagatesunknownoutputs into the spec (hence repeatedas { subscribers: ... }casts there).Since this harness can't be replaced by
testFlow(multi-session dispatch + HTTP 409), that's acceptable — but consider moving it totest/harness.tsand not exporting it from the barrel. Conductor deliberately keeps harness code out ofsrc/index.ts.