@taicho-ai/graph 0.1.0

package/README.md

@@ -0,0 +1,4 @@
+# @taicho-ai/graph
+
+A deterministic workflow graph for agent, check, human-gate, branch, and parallel nodes. Model and
+UI effects are injected. The optional file journal provides append-only runs and durable gate resume.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@taicho-ai/graph",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": "./src/index.ts",
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@taicho-ai/contracts": "0.1.0",
+    "zod": "^4.4.3"
+  },
+  "description": "Deterministic workflow schema and executor for taicho, with an optional filesystem journal.",
+  "license": "MIT",
+  "homepage": "https://taicho.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taicho-ai/taicho.git",
+    "directory": "packages/graph"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/executor.ts

@@ -0,0 +1,255 @@
+/** Plan 25: the workflow DRIVER — a sixth caller above executeRun.
+ *
+ *  It holds the edge state (an artifact-name → handle map), walks a cursor over the steps, and dispatches
+ *  per node kind. The engine owns step status: no node writes its own `done` — the driver writes it from
+ *  the step-runner's real outcome, the checker verdict, or the human's choice. State flows step→step by
+ *  artifact REFERENCE (a step's `produces` becomes the next step's `consumes` input), exactly as delegation
+ *  hands work down today.
+ *
+ *  The step-runner, checker, gate, and classifier are INJECTED so the orchestration is unit-testable without
+ *  a live model; run.ts wires them to executeRun / runChecker / requestApproval.
+ *
+ *  DURABLE SUSPENSION (Ph6): in `parkGates` mode a human gate PARKS instead of blocking — a marker persists,
+ *  the run stops with status "parked", and `resumeWorkflow` later rebuilds the edge state FROM THE EVENTS
+ *  (each done step's produced handle) and drives the rest. That is what lets an unattended/scheduled workflow
+ *  wait for the captain across a restart. */
+import {
+  reserveWorkflowRun, appendWorkflowEvent, foldWorkflowRun,
+  parkGate, readParkedGate, clearParkedGate,
+} from "./file-journal";
+import type { WorkflowDef, WorkflowNode, WorkflowRunState, StepStatus } from "./schema";
+
+export type RunOutcome = "completed" | "blocked" | "failed" | "interrupted";
+export interface AgentStepRun {
+  childRunId: string;
+  outcome: RunOutcome;
+  produced?: string;
+}
+type AgentNode = Extract<WorkflowNode, { kind: "agent" }>;
+type CheckNode = Extract<WorkflowNode, { kind: "check" }>;
+type HumanNode = Extract<WorkflowNode, { kind: "human" }>;
+type BranchNode = Extract<WorkflowNode, { kind: "branch" }>;
+
+export interface ReviewPacketItem { name: string; handle: string; }
+/** What a human gate lays in front of the captain — handles + names, never bodies. */
+export interface ReviewPacket { primary?: string; items: ReviewPacketItem[]; }
+export interface GateDecision { choice: string; note?: string; }
+
+/** The agent-step SHAPE runAgent receives — a top-level agent node, a parallel branch (no `kind`), or a
+ *  synthetic join. Untagged, so all three are assignable without normalizing branches. */
+export type AgentStepInput = { id: string; run: string; brief?: string; consumes: string[]; produces?: string; criteria?: string };
+
+export interface WorkflowExecDeps {
+  ws: string;
+  /** Run one agent step to completion. run.ts wires this to executeRun; tests inject a recorder. */
+  runAgent: (a: { step: AgentStepInput; brief: string; inputs: string[]; runId: string; triggeredBy: string }) => Promise<AgentStepRun>;
+  /** Verify an artifact against criteria (run.ts wires to runChecker). Required if the def has a check. */
+  runCheck?: (a: { node: CheckNode; target?: string; attempt: number }) => Promise<{ pass: boolean; reasons: string[] }>;
+  /** Ask the captain (run.ts wires to requestApproval). Returns null when cancelled. Required for ATTENDED human gates. */
+  requestGate?: (a: { node: HumanNode; packet: ReviewPacket; runId: string }) => Promise<GateDecision | null>;
+  /** Classify the input into one of a branch's route labels. Required if the def has a branch. */
+  classify?: (a: { node: BranchNode; target?: string }) => Promise<string>;
+  /** Read a list artifact into its items — required for a `parallel over:` (map) step. */
+  listItems?: (handle: string) => Promise<string[]>;
+  /** Ph6: park a human gate (persist + stop) instead of blocking — for UNATTENDED (scheduled/headless) runs. */
+  parkGates?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface WorkflowInput {
+  artifacts?: { name: string; handle: string }[];
+}
+
+const present = (h: string | undefined): h is string => !!h;
+
+function composeBrief(def: WorkflowDef, node: { brief?: string }): string {
+  return [def.brief, node.brief].filter((s): s is string => !!s && s.trim().length > 0).join("\n\n");
+}
+
+function statusFor(outcome: RunOutcome): StepStatus {
+  switch (outcome) {
+    case "completed": return "done";
+    case "interrupted": return "interrupted";
+    default: return "failed"; // blocked | failed
+  }
+}
+
+function buildPacket(node: HumanNode, edge: Map<string, string>, lastProduced?: string): ReviewPacket {
+  const names = node.shows ?? [...edge.keys()];
+  const items = names.filter((n) => edge.has(n)).map((n) => ({ name: n, handle: edge.get(n)! }));
+  return { primary: lastProduced ?? items[items.length - 1]?.handle, items };
+}
+
+/** Rebuild the edge state (artifact NAME → handle) from a run's PERSISTED events — the key to resuming a
+ *  parked run in a fresh process: each done agent/parallel step's produced handle re-maps to its name. */
+function rebuildEdge(ws: string, def: WorkflowDef, runId: string): Map<string, string> {
+  const edge = new Map<string, string>();
+  for (const s of foldWorkflowRun(ws, def, runId).steps) {
+    if (!s.produced) continue;
+    const node = def.steps.find((n) => n.id === s.id);
+    const name = node && (node.kind === "agent" || node.kind === "parallel") ? node.produces : undefined;
+    if (name) edge.set(name, s.produced);
+  }
+  return edge;
+}
+
+interface DriveState {
+  runId: string;
+  edge: Map<string, string>;
+  cursor: string | null;
+  attempts: Map<string, number>;
+  lastProduced?: string;
+}
+
+/** The shared loop. Both a fresh run (executeWorkflow) and a resumed one (resumeWorkflow) call this. */
+async function drive(deps: WorkflowExecDeps, def: WorkflowDef, state: DriveState): Promise<WorkflowRunState> {
+  const { ws } = deps;
+  const { runId, edge, attempts } = state;
+  const emit = (e: Parameters<typeof appendWorkflowEvent>[3]) => appendWorkflowEvent(ws, def.id, runId, e);
+  const inputsFor = (names: string[]) => names.map((n) => edge.get(n)).filter(present);
+  const indexById = new Map(def.steps.map((s, i) => [s.id, i] as const));
+  const successor = (idx: number): string | null => def.steps[idx + 1]?.id ?? null;
+
+  let cursor = state.cursor;
+  let lastProduced = state.lastProduced;
+  let ended: "completed" | "failed" | "interrupted" | "parked" = "completed";
+
+  while (cursor) {
+    const idx = indexById.get(cursor);
+    if (idx === undefined) throw new Error(`workflow "${def.id}" routes to unknown step "${cursor}"`);
+    const node = def.steps[idx]!;
+
+    if (deps.signal?.aborted) { emit({ step: node.id, status: "interrupted", runId }); ended = "interrupted"; break; }
+    emit({ step: node.id, status: "running", runId });
+
+    if (node.kind === "agent") {
+      const res = await deps.runAgent({
+        step: node, brief: composeBrief(def, node), inputs: inputsFor(node.consumes),
+        runId, triggeredBy: `workflow:${def.id}:${node.id}`,
+      });
+      if (node.produces && res.produced) { edge.set(node.produces, res.produced); lastProduced = res.produced; }
+      const status = statusFor(res.outcome);
+      emit({ step: node.id, runId: res.childRunId, produced: res.produced, status, note: res.outcome === "completed" ? undefined : `agent run ${res.outcome}` });
+      if (status !== "done") { ended = status === "interrupted" ? "interrupted" : "failed"; cursor = null; break; }
+      cursor = successor(idx);
+      continue;
+    }
+
+    if (node.kind === "check") {
+      if (!deps.runCheck) throw new Error(`workflow "${def.id}" has a check step "${node.id}" but no checker is wired`);
+      const attempt = (attempts.get(node.id) ?? 0) + 1;
+      attempts.set(node.id, attempt);
+      const target = node.of ? edge.get(node.of) : lastProduced;
+      const v = await deps.runCheck({ node, target, attempt });
+      if (v.pass) { emit({ step: node.id, status: "done", runId, attempt }); cursor = successor(idx); }
+      else if (node.on_fail && attempt < node.max_attempts) { emit({ step: node.id, status: "failed", runId, attempt, note: v.reasons.join("; ") || "check failed" }); cursor = node.on_fail; }
+      else { emit({ step: node.id, status: "failed", runId, attempt, note: v.reasons.join("; ") || "check failed, no attempts left" }); ended = "failed"; cursor = null; }
+      continue;
+    }
+
+    if (node.kind === "human") {
+      const packet = buildPacket(node, edge, lastProduced);
+      if (deps.parkGates) { // UNATTENDED — persist + stop; resumeWorkflow continues later.
+        parkGate(ws, def.id, runId, { step: node.id, title: node.human, choices: node.choices });
+        ended = "parked"; cursor = null; break;
+      }
+      if (!deps.requestGate) throw new Error(`workflow "${def.id}" has a human step "${node.id}" but no gate is wired`);
+      const d = await deps.requestGate({ node, packet, runId });
+      if (!d) { emit({ step: node.id, status: "interrupted", runId }); ended = "interrupted"; cursor = null; break; }
+      emit({ step: node.id, status: "done", runId, choice: d.choice, note: d.note });
+      cursor = node.routes[d.choice] ?? successor(idx);
+      continue;
+    }
+
+    if (node.kind === "branch") {
+      if (!deps.classify) throw new Error(`workflow "${def.id}" has a branch step "${node.id}" but no classifier is wired`);
+      const label = await deps.classify({ node, target: node.of ? edge.get(node.of) : lastProduced });
+      const next = node.routes[label];
+      emit({ step: node.id, status: "done", runId, choice: label, note: next ? undefined : `no route for "${label}", falling through` });
+      cursor = next ?? successor(idx);
+      continue;
+    }
+
+    if (node.kind === "parallel") {
+      // Build the fan-out: explicit `branches`, OR `over` a list artifact mapped through the `as` step.
+      let fan: { step: AgentStepInput; brief: string; inputs: string[]; tag: string }[];
+      if (node.over) {
+        if (!deps.listItems) throw new Error(`workflow "${def.id}": parallel 'over' needs a list reader (step "${node.id}")`);
+        if (!node.as) throw new Error(`workflow "${def.id}": parallel 'over' needs an 'as' step (step "${node.id}")`);
+        const src = edge.get(node.over);
+        const items = src ? await deps.listItems(src) : [];
+        const asStep = node.as;
+        fan = items.map((item, i) => ({
+          step: { ...asStep, id: `${node.id}_${i}` },
+          brief: `${composeBrief(def, asStep)}\n\nITEM ${i + 1}/${items.length}: ${item}`,
+          inputs: inputsFor(asStep.consumes),
+          tag: String(i),
+        }));
+      } else {
+        fan = (node.branches ?? []).map((b) => ({ step: b, brief: composeBrief(def, b), inputs: inputsFor(b.consumes), tag: b.id }));
+      }
+      const results = await Promise.all(fan.map((f) =>
+        deps.runAgent({ step: f.step, brief: f.brief, inputs: f.inputs, runId, triggeredBy: `workflow:${def.id}:${node.id}:${f.tag}` })));
+      const producedHandles: string[] = [];
+      fan.forEach((f, i) => {
+        const r = results[i]!;
+        if (r.produced) {
+          producedHandles.push(r.produced);
+          lastProduced = r.produced;
+          if (!node.over && f.step.produces) edge.set(f.step.produces, r.produced);
+        }
+      });
+      if (results.some((r) => r.outcome !== "completed")) { emit({ step: node.id, status: "failed", runId, note: "a parallel run failed" }); ended = "failed"; cursor = null; continue; }
+      if (node.join) {
+        const joinInputs = node.over ? producedHandles : (node.branches ?? []).map((b) => b.produces).filter(present).map((n) => edge.get(n)).filter(present);
+        const joinStep: AgentNode = { kind: "agent", id: `${node.id}__join`, run: node.join, consumes: [], produces: node.produces };
+        const jr = await deps.runAgent({ step: joinStep, brief: composeBrief(def, {}), inputs: joinInputs, runId, triggeredBy: `workflow:${def.id}:${node.id}:join` });
+        if (node.produces && jr.produced) { edge.set(node.produces, jr.produced); lastProduced = jr.produced; }
+        if (jr.outcome !== "completed") { emit({ step: node.id, status: "failed", runId, note: "the parallel join failed" }); ended = "failed"; cursor = null; continue; }
+      }
+      emit({ step: node.id, status: "done", runId, produced: node.produces ? edge.get(node.produces) : undefined });
+      cursor = successor(idx);
+      continue;
+    }
+
+    throw new Error(`workflow "${def.id}" reached an unhandled step kind`);
+  }
+
+  // A clean end (ran off the last step, or a branch/route/human sent the cursor to null) leaves any
+  // untaken steps `pending` — mark them `skipped` so the fold reads `done`, not stuck `running`. A parked/
+  // failed/interrupted run leaves them as-is.
+  if (ended === "completed") {
+    for (const s of foldWorkflowRun(ws, def, runId).steps) {
+      if (s.status === "pending") emit({ step: s.id, status: "skipped", runId });
+    }
+  }
+  return foldWorkflowRun(ws, def, runId);
+}
+
+export async function executeWorkflow(deps: WorkflowExecDeps, def: WorkflowDef, input?: WorkflowInput): Promise<WorkflowRunState> {
+  const runId = reserveWorkflowRun(deps.ws, def.id);
+  const edge = new Map<string, string>();
+  for (const a of input?.artifacts ?? []) edge.set(a.name, a.handle);
+  return drive(deps, def, { runId, edge, cursor: def.steps[0]?.id ?? null, attempts: new Map() });
+}
+
+/** Ph6: answer a parked human gate and drive the rest. Rebuilds the edge state from the persisted events
+ *  (so it works in a fresh process after a restart), settles the gate with the choice, and continues. */
+export async function resumeWorkflow(
+  deps: WorkflowExecDeps,
+  def: WorkflowDef,
+  runId: string,
+  choice: string,
+  note?: string,
+): Promise<WorkflowRunState> {
+  const parked = readParkedGate(deps.ws, def.id, runId);
+  if (!parked) throw new Error(`workflow run "${runId}" is not parked`);
+  const idx = def.steps.findIndex((n) => n.id === parked.step);
+  const node = def.steps[idx];
+  if (!node || node.kind !== "human") throw new Error(`parked step "${parked.step}" is not a human gate`);
+  clearParkedGate(deps.ws, def.id, runId);
+  appendWorkflowEvent(deps.ws, def.id, runId, { step: node.id, status: "done", runId, choice, note });
+  const edge = rebuildEdge(deps.ws, def, runId);
+  const cursor = node.routes[choice] ?? (def.steps[idx + 1]?.id ?? null);
+  return drive(deps, def, { runId, edge, cursor, attempts: new Map() });
+}

package/src/file-journal.ts

@@ -0,0 +1,171 @@
+/** Plan 25: workflow RUN state — the append-only event log, one directory per run.
+ *
+ *    workflows/<wfId>/runs/<runId>/events.jsonl   append-only step transitions, engine-written
+ *
+ *  Current state = fold(events): the last event per step wins; a step with no event is pending. This is
+ *  the Plan 18 plan discipline, minus the model-attempt/`rejected` split — the engine writes every event,
+ *  so there is nothing to lie. reconcileWorkflowRuns is the boot half: a step left `running` means the
+ *  process died in flight, so append `interrupted` (never rewrite history) and report it. */
+import { mkdirSync, appendFileSync, readFileSync, writeFileSync, rmSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  WorkflowEvent, TERMINAL_STEP_STATUS,
+  type WorkflowDef, type FoldedStep, type WorkflowRunState, type WorkflowRunStatus, type StepStatus,
+} from "./schema";
+
+const workflowPaths = {
+  workflowsDir: (ws: string) => join(ws, "workflows"),
+  workflowRunsDir: (ws: string, id: string) => join(ws, "workflows", id, "runs"),
+  workflowRunDir: (ws: string, id: string, runId: string) => join(ws, "workflows", id, "runs", runId),
+};
+
+const eventsFile = (ws: string, wfId: string, runId: string) =>
+  join(workflowPaths.workflowRunDir(ws, wfId, runId), "events.jsonl");
+
+/** Mint a unique run id and create its directory. Exclusive-create the dir, retrying on collision — the
+ *  same race-free idiom as writePlan/saveArtifact, so two concurrent runs can't claim one id. */
+export function reserveWorkflowRun(ws: string, wfId: string): string {
+  const runsDir = workflowPaths.workflowRunsDir(ws, wfId);
+  mkdirSync(runsDir, { recursive: true });
+  for (let n = 1; n < 100_000; n++) {
+    const runId = `wr_${wfId}_${n}`;
+    try {
+      mkdirSync(join(runsDir, runId)); // no recursive: fails with EEXIST if taken
+      return runId;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+    }
+  }
+  throw new Error(`could not reserve a workflow run id for "${wfId}" (100000 collisions)`);
+}
+
+/** Append one step transition. Stamps `ts` if absent. */
+export function appendWorkflowEvent(
+  ws: string,
+  wfId: string,
+  runId: string,
+  event: Omit<WorkflowEvent, "ts"> & { ts?: string },
+): WorkflowEvent {
+  const e = WorkflowEvent.parse({ ...event, ts: event.ts ?? new Date().toISOString() });
+  mkdirSync(workflowPaths.workflowRunDir(ws, wfId, runId), { recursive: true });
+  appendFileSync(eventsFile(ws, wfId, runId), JSON.stringify(e) + "\n");
+  return e;
+}
+
+export function readWorkflowEvents(ws: string, wfId: string, runId: string): WorkflowEvent[] {
+  const f = eventsFile(ws, wfId, runId);
+  if (!existsSync(f)) return [];
+  const out: WorkflowEvent[] = [];
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try { out.push(WorkflowEvent.parse(JSON.parse(line))); }
+    catch { /* tolerate a partial final JSONL line after process interruption */ }
+  }
+  return out;
+}
+
+/** Last event per step wins. */
+function foldEvents(events: WorkflowEvent[]): Map<string, WorkflowEvent> {
+  const byStep = new Map<string, WorkflowEvent>();
+  for (const e of events) byStep.set(e.step, e);
+  return byStep;
+}
+
+function overallStatus(steps: FoldedStep[]): WorkflowRunStatus {
+  if (steps.some((s) => s.status === "failed")) return "failed";
+  if (steps.some((s) => s.status === "interrupted")) return "interrupted";
+  if (steps.some((s) => s.status === "running" || s.status === "pending")) return "running";
+  return "done";
+}
+
+/** Current state = fold(events) over the definition's steps. A run with a parked human gate reads as
+ *  `parked` (not `running`) so the boot reconcile + the /workflows UI can distinguish "waiting on you"
+ *  from "executing". */
+export function foldWorkflowRun(ws: string, def: WorkflowDef, runId: string): WorkflowRunState {
+  const latest = foldEvents(readWorkflowEvents(ws, def.id, runId));
+  const steps: FoldedStep[] = def.steps.map((s) => {
+    const e = latest.get(s.id);
+    return e
+      ? { id: s.id, kind: s.kind, status: e.status, produced: e.produced, choice: e.choice, note: e.note, updated: e.ts }
+      : { id: s.id, kind: s.kind, status: "pending" as StepStatus };
+  });
+  const done = steps.filter((s) => s.status === "done").length;
+  const failed = steps.filter((s) => s.status === "failed" || s.status === "interrupted").length;
+  const open = steps.filter((s) => !TERMINAL_STEP_STATUS.has(s.status)).length;
+  let status = overallStatus(steps);
+  if (status === "running" && readParkedGate(ws, def.id, runId)) status = "parked";
+  return { wfId: def.id, runId, steps, status, counts: { total: steps.length, done, open, failed } };
+}
+
+// ── durable gate suspension (Plan 25 Ph6) ─────────────────────────────────────────────────────────
+// A workflow that reaches a human gate in an UNATTENDED run can't block on an in-memory Promise (the
+// process may exit). Instead it PARKS: this marker persists next to the run's events, the run stops, and
+// resumeWorkflow (core/workflow.ts) rebuilds the edge state from the events and continues once answered.
+
+export interface ParkedGate {
+  step: string;
+  title: string;
+  choices: string[];
+  note?: string;
+  at: string;
+}
+
+const parkedFile = (ws: string, wfId: string, runId: string) => join(workflowPaths.workflowRunDir(ws, wfId, runId), "parked.json");
+
+export function parkGate(ws: string, wfId: string, runId: string, gate: Omit<ParkedGate, "at">): ParkedGate {
+  const g: ParkedGate = { ...gate, at: new Date().toISOString() };
+  mkdirSync(workflowPaths.workflowRunDir(ws, wfId, runId), { recursive: true });
+  writeFileSync(parkedFile(ws, wfId, runId), JSON.stringify(g, null, 2));
+  return g;
+}
+
+export function readParkedGate(ws: string, wfId: string, runId: string): ParkedGate | null {
+  const f = parkedFile(ws, wfId, runId);
+  if (!existsSync(f)) return null;
+  try { return JSON.parse(readFileSync(f, "utf8")) as ParkedGate; }
+  catch { return null; }
+}
+
+export function clearParkedGate(ws: string, wfId: string, runId: string): void {
+  const f = parkedFile(ws, wfId, runId);
+  if (existsSync(f)) rmSync(f);
+}
+
+/** Every workflow run currently parked at a human gate — for the boot notice + the /workflows UI. */
+export function listParkedGates(ws: string): { wfId: string; runId: string; gate: ParkedGate }[] {
+  const out: { wfId: string; runId: string; gate: ParkedGate }[] = [];
+  for (const wfId of subdirs(workflowPaths.workflowsDir(ws))) {
+    for (const runId of listWorkflowRunIds(ws, wfId)) {
+      const gate = readParkedGate(ws, wfId, runId);
+      if (gate) out.push({ wfId, runId, gate });
+    }
+  }
+  return out;
+}
+
+const subdirs = (dir: string): string[] =>
+  existsSync(dir) ? readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort() : [];
+
+export function listWorkflowRunIds(ws: string, wfId: string): string[] {
+  return subdirs(workflowPaths.workflowRunsDir(ws, wfId));
+}
+
+/** Boot reconcile: a step left `running` means the process died in flight. Append `interrupted` and report
+ *  it, without touching the definition — the step is still what the workflow meant to do. */
+export function reconcileWorkflowRuns(ws: string): { wfId: string; runId: string; step: string }[] {
+  const interrupted: { wfId: string; runId: string; step: string }[] = [];
+  for (const wfId of subdirs(workflowPaths.workflowsDir(ws))) {
+    for (const runId of listWorkflowRunIds(ws, wfId)) {
+      const latest = foldEvents(readWorkflowEvents(ws, wfId, runId));
+      for (const [step, e] of latest) {
+        if (e.status !== "running") continue;
+        appendWorkflowEvent(ws, wfId, runId, {
+          step, status: "interrupted", runId: "boot",
+          note: "the process exited while this step was in flight",
+        });
+        interrupted.push({ wfId, runId, step });
+      }
+    }
+  }
+  return interrupted;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./schema";
+export * from "./executor";
+export * from "./file-journal";

package/src/schema.ts

@@ -0,0 +1,185 @@
+/** Plan 25: the structured, engine-executed team workflow.
+ *
+ *  Lives in the YAML frontmatter of teams/<id>/workflow.md — the slot Plan 23's parseWorkflow already
+ *  reserves and strips. The prose `## seat` lanes below it are untouched (Plan 23). A file with no
+ *  `steps:` block is a prose-only Plan 23 workflow and loadWorkflowDefText returns null for it.
+ *
+ *  A step is one of five KINDS, distinguished in YAML by which key it carries — a step with `run:` is an
+ *  agent node, `check:` a check node, and so on. normalizeNode() detects the kind and rejects a step that
+ *  carries more than one kind-key (or none), naming the id. The engine (core/workflow.ts) walks the steps;
+ *  the model never routes. */
+import { z } from "zod";
+import { YAML } from "bun";
+
+/** A step id — stable across versions, exactly like a Plan 18 PlanItem id. */
+const StepId = z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, "step id must be lowercase letters, digits, _ or -");
+
+/** run one agent (or a team id, resolved by team-routing). */
+const AgentNode = z.object({
+  id: StepId,
+  run: z.string(),
+  brief: z.string().optional(),
+  consumes: z.array(z.string()).default([]),
+  produces: z.string().optional(),
+  criteria: z.string().optional(),
+});
+
+/** an automatic gate — verify an artifact against criteria (Plan 06 runChecker). */
+const CheckNode = z.object({
+  id: StepId,
+  check: z.string(),
+  of: z.string().optional(),
+  on_fail: StepId.optional(),
+  max_attempts: z.number().int().positive().default(2),
+});
+
+/** a human gate — pause, present a packet, route on the chosen option. */
+const HumanNode = z.object({
+  id: StepId,
+  human: z.string(),
+  present: z.string().optional(),
+  shows: z.array(z.string()).optional(),
+  choices: z.array(z.string()).min(1).default(["approve", "reject"]),
+  routes: z.record(z.string(), StepId).default({}),
+});
+
+/** fan-out then optional join. `over` maps each item of an artifact list; `branches` is explicit steps. */
+const ParallelNode = z.object({
+  id: StepId,
+  over: z.string().optional(),
+  branches: z.array(AgentNode).optional(),
+  as: AgentNode.optional(),
+  join: z.string().optional(),
+  produces: z.string().optional(),
+});
+
+/** classify the input and jump to a labelled step. */
+const BranchNode = z.object({
+  id: StepId,
+  branch: z.string(),
+  of: z.string().optional(),
+  routes: z.record(z.string(), StepId),
+});
+
+export type WorkflowNode =
+  | ({ kind: "agent" } & z.infer<typeof AgentNode>)
+  | ({ kind: "check" } & z.infer<typeof CheckNode>)
+  | ({ kind: "human" } & z.infer<typeof HumanNode>)
+  | ({ kind: "parallel" } & z.infer<typeof ParallelNode>)
+  | ({ kind: "branch" } & z.infer<typeof BranchNode>);
+export type NodeKind = WorkflowNode["kind"];
+
+export interface WorkflowDef {
+  id: string;
+  team: string;
+  version: number;
+  brief?: string;
+  steps: WorkflowNode[];
+}
+
+const WorkflowHead = z.object({
+  id: z.string().min(1),
+  team: z.string().min(1),
+  version: z.number().int().positive(),
+  brief: z.string().optional(),
+});
+
+/** Which kind-key(s) a raw step carries. `parallel` is signalled by `over` or `branches`. */
+function discriminate(raw: Record<string, unknown>): NodeKind[] {
+  const kinds: NodeKind[] = [];
+  if ("run" in raw) kinds.push("agent");
+  if ("check" in raw) kinds.push("check");
+  if ("human" in raw) kinds.push("human");
+  if ("branch" in raw) kinds.push("branch");
+  if ("over" in raw || "branches" in raw) kinds.push("parallel");
+  return kinds;
+}
+
+function normalizeNode(raw: Record<string, unknown>): WorkflowNode {
+  const id = typeof raw.id === "string" ? raw.id : "?";
+  const kinds = discriminate(raw);
+  if (kinds.length === 0)
+    throw new Error(`workflow step "${id}" has no kind — it needs one of run/check/human/parallel/branch`);
+  if (kinds.length > 1)
+    throw new Error(`workflow step "${id}" carries more than one kind (${kinds.join(", ")}) — a step is exactly one`);
+  const kind = kinds[0]!;
+  switch (kind) {
+    case "agent": return { kind, ...AgentNode.parse(raw) };
+    case "check": return { kind, ...CheckNode.parse(raw) };
+    case "human": return { kind, ...HumanNode.parse(raw) };
+    case "parallel": return { kind, ...ParallelNode.parse(raw) };
+    case "branch": return { kind, ...BranchNode.parse(raw) };
+  }
+}
+
+/** Validate + normalize a raw workflow object (head fields already mapped: id/team/version/brief/steps). */
+export function parseWorkflowDef(raw: unknown): WorkflowDef {
+  const r = (raw ?? {}) as Record<string, unknown>;
+  const head = WorkflowHead.parse(r);
+  const rawSteps = z.array(z.record(z.string(), z.unknown())).min(1, "a workflow needs at least one step").parse(r.steps);
+  const steps = rawSteps.map(normalizeNode);
+  const ids = new Set<string>();
+  for (const s of steps) {
+    if (ids.has(s.id)) throw new Error(`workflow "${head.id}" has a duplicate step id "${s.id}"`);
+    ids.add(s.id);
+  }
+  return { ...head, steps };
+}
+
+// ── run state ───────────────────────────────────────────────────────────────────────────────────
+// A workflow RUN is an append-only event log; current state = fold(events). This mirrors Plan 18's plan
+// event log, but SIMPLER: the ENGINE writes every event (a workflow step is never model-ticked), so there
+// is no `by`/`rejected` split — no attempt can lie because no model attempt exists.
+
+export const StepStatus = z.enum(["pending", "running", "done", "failed", "skipped", "interrupted"]);
+export type StepStatus = z.infer<typeof StepStatus>;
+
+/** Terminal for "is this step still open". */
+export const TERMINAL_STEP_STATUS: ReadonlySet<StepStatus> = new Set<StepStatus>([
+  "done", "failed", "skipped", "interrupted",
+]);
+
+export const WorkflowEvent = z.object({
+  step: z.string(),
+  status: StepStatus,
+  runId: z.string(), // the executeRun (or "boot") that wrote this event
+  produced: z.string().optional(), // artifact handle the step emitted (id@vN)
+  choice: z.string().optional(), // human/branch: the path taken
+  attempt: z.number().int().optional(),
+  note: z.string().optional(),
+  ts: z.string().datetime(),
+});
+export type WorkflowEvent = z.infer<typeof WorkflowEvent>;
+
+export interface FoldedStep {
+  id: string;
+  kind: NodeKind;
+  status: StepStatus;
+  produced?: string;
+  choice?: string;
+  note?: string;
+  updated?: string;
+}
+
+export type WorkflowRunStatus = "running" | "done" | "failed" | "interrupted" | "parked";
+
+export interface WorkflowRunState {
+  wfId: string;
+  runId: string;
+  steps: FoldedStep[];
+  status: WorkflowRunStatus;
+  counts: { total: number; done: number; open: number; failed: number };
+}
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+/** Parse the structured workflow out of a workflow.md's text. `team` is injected from the file location
+ *  (teams/<team>/workflow.md). Returns null for a Plan 23 prose-only file — one with no frontmatter, or
+ *  frontmatter that carries no `steps:` block. The frontmatter key `workflow:` names the workflow (its id). */
+export function loadWorkflowDefText(text: string, team: string): WorkflowDef | null {
+  const m = FRONTMATTER.exec(text);
+  if (!m) return null;
+  const fm = YAML.parse(m[1]!) as Record<string, unknown> | null;
+  if (!fm || !("steps" in fm)) return null;
+  return parseWorkflowDef({ id: fm.workflow, team, version: fm.version, brief: fm.brief, steps: fm.steps });
+}