Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions knip.json
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,9 @@
"labs/conductor": {
"entry": ["fsdev.config.ts", "test/**/*.spec.ts", "test/harness.ts"]
},
"labs/workforce-poc-board-notify": {
"entry": ["src/index.ts", "src/run.ts", "test/**/*.spec.ts"]
},
"plugins/flow-state-dev": {
"entry": ["test/**/*.test.mjs", "skills/install-fsd/detect/detect.mjs"],
"project": ["test/**/*.mjs", "skills/**/*.mjs"]
Expand Down
79 changes: 79 additions & 0 deletions labs/workforce-poc-board-notify/README.md
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.
28 changes: 28 additions & 0 deletions labs/workforce-poc-board-notify/package.json
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"
}
}
111 changes: 111 additions & 0 deletions labs/workforce-poc-board-notify/src/bootstrap.ts
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,

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.

Triple as never on flow/action/input erases all type safety and propagates unknown outputs into the spec (hence repeated as { subscribers: ... } casts there).

Since this harness can't be replaced by testFlow (multi-session dispatch + HTTP 409), that's acceptable — but consider moving it to test/harness.ts and not exporting it from the barrel. Conductor deliberately keeps harness code out of src/index.ts.

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}`);
}
Loading
Loading