@kontourai/flow-agents 3.11.0 → 3.12.0

package/src/continuation-persistence.ts

@@ -0,0 +1,228 @@
+import * as fs from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { atomicWriteJson, ensureSafeDirectory } from "./lib/fs.js";
+import type { ContinuationAcceptedTurn, ContinuationAcceptedTurnJournal, ContinuationBarrier, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverState, ContinuationStateStore } from "./continuation-driver.js";
+
+export const MAX_CONTINUATION_TURNS = 100;
+const MAX_STATE_BYTES = 1_048_576;
+const MAX_LOCK_BYTES = 16_384;
+const MAX_EVENT_LINE_BYTES = 16_384;
+const MAX_EVENT_LINES = MAX_CONTINUATION_TURNS * 6 + 16;
+const MAX_EVENT_LOG_BYTES = MAX_EVENT_LINE_BYTES * MAX_EVENT_LINES;
+const MAX_ACCEPTED_TURN_LINE_BYTES = 196_608;
+const MAX_ACCEPTED_TURN_LOG_BYTES = MAX_ACCEPTED_TURN_LINE_BYTES * MAX_CONTINUATION_TURNS;
+
+export async function withContinuationDriverLock<T>(sessionDirInput: string, body: (lease: ContinuationDriverLockLease) => Promise<T>): Promise<T> {
+  const sessionDir = path.resolve(sessionDirInput);
+  const locksDir = path.join(sessionDir, "continuation-driver", "locks");
+  ensureSafeDirectory(sessionDir, locksDir);
+  const token = randomUUID();
+  const lockFile = path.join(locksDir, `${process.pid}-${token}.lock`);
+  const lease: ContinuationDriverLockLease = { pid: process.pid, token, created_at: new Date().toISOString() };
+  acquireDriverLock(locksDir, lockFile, { schema_version: "1.0", ...lease });
+  try { return await body(lease); }
+  finally { releaseDriverLock(lockFile, token); }
+}
+
+export function createFileContinuationStore(sessionDirInput: string): ContinuationStateStore & ContinuationAcceptedTurnJournal {
+  const sessionDir = path.resolve(sessionDirInput);
+  const driverDir = path.join(sessionDir, "continuation-driver");
+  const stateFile = path.join(driverDir, "state.json");
+  const eventsFile = path.join(driverDir, "events.jsonl");
+  const acceptedFile = path.join(driverDir, "accepted-turns.jsonl");
+  ensureSafeDirectory(sessionDir, driverDir);
+  return {
+    load(): ContinuationDriverState | null {
+      const stateBytes = readStableBoundedFile(stateFile, "continuation driver state", MAX_STATE_BYTES, false);
+      const events = readEventLog(eventsFile);
+      if (!stateBytes) {
+        if (events.length > 0) throw new Error("continuation driver state is missing while mission events exist");
+        return null;
+      }
+      const state = JSON.parse(stateBytes.toString("utf8")) as ContinuationDriverState;
+      reconcileStateWithEvents(state, events);
+      return state;
+    },
+    save(state): void {
+      if (Buffer.byteLength(JSON.stringify(state), "utf8") > MAX_STATE_BYTES) throw new Error(`continuation driver state exceeds ${MAX_STATE_BYTES} bytes`);
+      atomicWriteJson(sessionDir, stateFile, state);
+    },
+    append(event): void {
+      const events = readEventLog(eventsFile);
+      if (event.turn_id && events.some((entry) => entry.type === event.type && entry.turn_id === event.turn_id)) return;
+      appendBoundedJsonLine(sessionDir, eventsFile, event, "continuation driver event log", MAX_EVENT_LINE_BYTES, MAX_EVENT_LOG_BYTES, events.length, MAX_EVENT_LINES);
+    },
+    captureAcceptedTurn(turn): void {
+      const accepted = readAcceptedTurns(acceptedFile);
+      const prior = accepted.find((entry) => entry.turn_id === turn.turn_id);
+      if (prior) {
+        if (!isDeepStrictEqual(prior, turn)) throw new Error(`continuation accepted-turn '${turn.turn_id}' conflicts with its durable capture`);
+        return;
+      }
+      appendBoundedJsonLine(sessionDir, acceptedFile, turn, "continuation accepted-turn log", MAX_ACCEPTED_TURN_LINE_BYTES, MAX_ACCEPTED_TURN_LOG_BYTES, accepted.length, MAX_CONTINUATION_TURNS);
+    },
+    acceptedTurns(): ContinuationAcceptedTurn[] {
+      const accepted = readAcceptedTurns(acceptedFile);
+      assertAcceptedTurnCoverage(accepted, readEventLog(eventsFile));
+      return structuredClone(accepted);
+    },
+  };
+}
+
+function readEventLog(file: string): ContinuationDriverEvent[] {
+  return readBoundedJsonLines<ContinuationDriverEvent>(file, "continuation driver event log", MAX_EVENT_LOG_BYTES, MAX_EVENT_LINE_BYTES, MAX_EVENT_LINES);
+}
+
+function readAcceptedTurns(file: string): ContinuationAcceptedTurn[] {
+  return readBoundedJsonLines<ContinuationAcceptedTurn>(file, "continuation accepted-turn log", MAX_ACCEPTED_TURN_LOG_BYTES, MAX_ACCEPTED_TURN_LINE_BYTES, MAX_CONTINUATION_TURNS);
+}
+
+function readBoundedJsonLines<T>(file: string, label: string, maxFileBytes: number, maxLineBytes: number, maxLines: number): T[] {
+  const bytes = readStableBoundedFile(file, label, maxFileBytes, false);
+  if (!bytes || bytes.length === 0) return [];
+  const lines = bytes.toString("utf8").split("\n");
+  if (lines.at(-1) !== "") throw new Error(`${label} must end with a complete line`);
+  lines.pop();
+  if (lines.length > maxLines) throw new Error(`${label} exceeds ${maxLines} lines`);
+  return lines.map((line) => {
+    if (Buffer.byteLength(line, "utf8") > maxLineBytes) throw new Error(`${label} line exceeds ${maxLineBytes} bytes`);
+    return JSON.parse(line) as T;
+  });
+}
+
+function appendBoundedJsonLine(root: string, file: string, value: unknown, label: string, maxLineBytes: number, maxFileBytes: number, currentLines: number, maxLines: number): void {
+  const line = Buffer.from(`${JSON.stringify(value)}\n`, "utf8");
+  if (line.length - 1 > maxLineBytes) throw new Error(`${label} line exceeds ${maxLineBytes} bytes`);
+  if (currentLines >= maxLines) throw new Error(`${label} exceeds ${maxLines} lines`);
+  ensureSafeDirectory(root, path.dirname(file));
+  const parent = stableParent(path.dirname(file), label);
+  const fd = fs.openSync(file, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | noFollowFlag(), 0o600);
+  try {
+    const before = fs.fstatSync(fd);
+    if (!before.isFile() || before.size + line.length > maxFileBytes) throw new Error(`${label} exceeds ${maxFileBytes} bytes`);
+    fs.writeSync(fd, line, 0, line.length);
+    const after = fs.fstatSync(fd);
+    if (!sameIdentity(before, after) || after.size !== before.size + line.length) throw new Error(`${label} changed while appending`);
+    assertPathAndParentIdentity(file, after, parent, label);
+  } finally { fs.closeSync(fd); }
+}
+
+function readStableBoundedFile(file: string, label: string, maxBytes: number, required: boolean): Buffer | null {
+  let fd: number | undefined;
+  try {
+    const parent = stableParent(path.dirname(file), label);
+    fd = fs.openSync(file, fsConstants.O_RDONLY | noFollowFlag());
+    const before = fs.fstatSync(fd);
+    if (!before.isFile() || before.size > maxBytes) throw new Error(`${label} must be a regular file no larger than ${maxBytes} bytes`);
+    assertPathAndParentIdentity(file, before, parent, label);
+    const bytes = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+      if (read === 0) throw new Error(`${label} changed while reading`);
+      offset += read;
+    }
+    const after = fs.fstatSync(fd);
+    if (!sameIdentity(before, after) || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error(`${label} changed while reading`);
+    assertPathAndParentIdentity(file, after, parent, label);
+    return bytes;
+  } catch (error) {
+    if (!required && (error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+type ParentIdentity = { real: string; stat: fs.Stats };
+
+function stableParent(parentPath: string, label: string): ParentIdentity {
+  const lexical = fs.lstatSync(parentPath);
+  if (lexical.isSymbolicLink() || !lexical.isDirectory()) throw new Error(`${label} parent must be a non-symlink directory`);
+  const real = fs.realpathSync(parentPath);
+  const stat = fs.statSync(real);
+  if (!stat.isDirectory() || !sameIdentity(lexical, stat)) throw new Error(`${label} parent changed identity`);
+  return { real, stat };
+}
+
+function assertPathAndParentIdentity(file: string, opened: fs.Stats, parent: ParentIdentity, label: string): void {
+  const pathStat = fs.lstatSync(file);
+  if (pathStat.isSymbolicLink() || !sameIdentity(opened, pathStat)) throw new Error(`${label} changed identity while reading`);
+  const parentAfter = stableParent(path.dirname(file), label);
+  if (parentAfter.real !== parent.real || !sameIdentity(parentAfter.stat, parent.stat)) throw new Error(`${label} parent changed identity while reading`);
+}
+
+function assertAcceptedTurnCoverage(accepted: ContinuationAcceptedTurn[], events: ContinuationDriverEvent[]): void {
+  const acceptedIds = new Set(accepted.map((entry) => entry.turn_id));
+  if (acceptedIds.size !== accepted.length) throw new Error("continuation accepted-turn log contains duplicate turn ids");
+  const terminalEvents = events.filter((event) => event.type === "turn_completed" || event.type === "parked" || (event.type === "turn_failed" && event.turn_id));
+  if (events.some((event) => (event.type === "turn_completed" || event.type === "parked") && !event.turn_id)) {
+    throw new Error("continuation attestation coverage is incomplete for legacy accepted turns");
+  }
+  if (terminalEvents.some((event) => !event.turn_id || !acceptedIds.has(event.turn_id))) throw new Error("continuation attestation coverage is missing a persisted accepted turn");
+  const eventIds = new Set(terminalEvents.flatMap((event) => event.turn_id ? [event.turn_id] : []));
+  if (accepted.some((entry) => !eventIds.has(entry.turn_id))) throw new Error("continuation persisted accepted turn has no durable completion event");
+}
+
+function acquireDriverLock(locksDir: string, lockFile: string, owner: { schema_version: "1.0"; pid: number; token: string; created_at: string }): void {
+  const fd = fs.openSync(lockFile, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollowFlag(), 0o600);
+  try { fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8"); } finally { fs.closeSync(fd); }
+  try { reclaimDeadDriverLocks(locksDir, lockFile); }
+  catch (error) { try { fs.unlinkSync(lockFile); } catch {} throw error; }
+}
+
+function reclaimDeadDriverLocks(locksDir: string, lockFile: string): void {
+  for (const name of fs.readdirSync(locksDir).sort()) {
+    const candidate = path.join(locksDir, name);
+    if (candidate === lockFile) continue;
+    let existing: { schema_version?: unknown; pid?: unknown; token?: unknown };
+    try { existing = JSON.parse(String(readStableBoundedFile(candidate, "continuation driver lock", MAX_LOCK_BYTES, true))) as typeof existing; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw error; }
+    if (existing.schema_version !== "1.0" || typeof existing.pid !== "number" || !Number.isSafeInteger(existing.pid) || existing.pid <= 0 || typeof existing.token !== "string") throw new Error("continuation driver lock is invalid");
+    if (processAlive(existing.pid)) throw new Error(`continuation driver is already running under pid ${existing.pid}`);
+    try { fs.unlinkSync(candidate); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+}
+
+function releaseDriverLock(lockFile: string, token: string): void {
+  try {
+    const owner = JSON.parse(String(readStableBoundedFile(lockFile, "continuation driver lock", MAX_LOCK_BYTES, true))) as { token?: unknown };
+    if (owner.token === token) fs.unlinkSync(lockFile);
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+}
+
+function reconcileStateWithEvents(state: ContinuationDriverState, events: ContinuationDriverEvent[]): void {
+  if (events.length === 0) {
+    if (state.turns_started > 0) throw new Error("continuation driver event history is missing for a started mission");
+    return;
+  }
+  let highestStartedTurn = 0;
+  let eventBarrier: ContinuationBarrier | null = null;
+  for (const event of events) {
+    if (event.run_id !== state.run_id || event.definition_id !== state.definition_id) throw new Error("continuation driver event history has a foreign mission identity");
+    if (event.type === "turn_started") {
+      if (!Number.isSafeInteger(event.turns_started) || Number(event.turns_started) < 1) throw new Error("continuation driver event history has an invalid turn count");
+      highestStartedTurn = Math.max(highestStartedTurn, Number(event.turns_started));
+    }
+    if (event.type === "parked") { validateStoredBarrier(event.barrier); eventBarrier = structuredClone(event.barrier as ContinuationBarrier); }
+    if (event.type === "resumed") eventBarrier = null;
+  }
+  if (highestStartedTurn > state.turns_started) throw new Error("continuation driver state rolled back behind its event history");
+  if (state.turns_started > highestStartedTurn + 1) throw new Error("continuation driver state is ahead of its event history");
+  if (!state.pending_barrier && eventBarrier) { state.pending_barrier = eventBarrier; state.status = "waiting"; }
+}
+
+function validateStoredBarrier(value: unknown): void {
+  const barrier = value as Partial<ContinuationBarrier> | null;
+  const validPid = barrier?.kind === "pid" && Number.isSafeInteger(barrier.pid) && Number(barrier.pid) > 0;
+  const validDeadline = barrier?.kind === "deadline" && typeof barrier.at === "string" && Number.isFinite(Date.parse(barrier.at));
+  if (!validPid && !validDeadline) throw new Error("continuation driver event history has an invalid barrier");
+}
+
+function sameIdentity(left: fs.Stats, right: fs.Stats): boolean { return left.dev === right.dev && left.ino === right.ino; }
+function processAlive(pid: number): boolean { try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; } }
+function noFollowFlag(): number {
+  if (typeof fsConstants.O_NOFOLLOW !== "number") throw new Error("continuation persistence requires O_NOFOLLOW");
+  return fsConstants.O_NOFOLLOW;
+}

package/src/continuation-validation.ts

@@ -0,0 +1,107 @@
+import { MAX_CONTINUATION_TURNS } from "./continuation-persistence.js";
+import type { GateActionEnvelope, GateActionPriorProgress, GateActionProgressSnapshot } from "./builder-gate-action-envelope.js";
+import type { ContinuationAcceptedTurn, ContinuationBarrier, ContinuationDriverState, ContinuationSnapshot, ContinuationTurnResult } from "./continuation-driver.js";
+
+export const MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES = 65_536;
+export const MAX_CONTINUATION_TURN_RESULT_BYTES = 74_000;
+
+export function validateSnapshot(value: ContinuationSnapshot): ContinuationSnapshot {
+  if (!value || typeof value !== "object") throw new Error("continuation runtime returned an invalid canonical snapshot");
+  for (const field of ["run_id", "definition_id", "status", "current_step"] as const) if (typeof value[field] !== "string" || value[field].length === 0) throw new Error(`continuation snapshot ${field} must be a non-empty string`);
+  if (!new Set(["continue", "waiting", "done", "failed"]).has(value.disposition)) throw new Error("continuation snapshot disposition is invalid");
+  if (value.next_action !== null && (typeof value.next_action !== "object" || Array.isArray(value.next_action))) throw new Error("continuation snapshot next_action must be an object or null");
+  if (value.gate_action_envelope !== undefined) validateGateActionEnvelope(value.gate_action_envelope);
+  if (value.progress_snapshot !== undefined) validateProgressSnapshot(value.progress_snapshot);
+  return structuredClone(value);
+}
+
+function validateGateActionEnvelope(value: GateActionEnvelope): void {
+  if (!value || typeof value !== "object" || value.schema_version !== "1.0" || !value.flow || typeof value.flow.current_step !== "string"
+    || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts)) throw new Error("continuation snapshot gate-action envelope is malformed");
+  if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536) throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
+}
+
+export function validateTurnResult(value: ContinuationTurnResult): ContinuationTurnResult {
+  if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait")) throw new Error("continuation adapter must return status completed or wait");
+  if (value.status === "wait") validateBarrier(value.barrier);
+  if (value.summary !== undefined && typeof value.summary !== "string") throw new Error("continuation adapter summary must be a string");
+  if (value.status === "completed" && value.evidence !== undefined) validateAdapterEvidence(value.evidence);
+  if (value.status === "wait" && Object.hasOwn(value, "evidence")) throw new Error("continuation wait results must not include evidence");
+  const copy = structuredClone(value);
+  if (copy.summary) {
+    const characters = Array.from(copy.summary);
+    if (characters.length > 2_000) copy.summary = `${characters.slice(0, 1_997).join("")}...`;
+  }
+  if (Buffer.byteLength(JSON.stringify(copy), "utf8") > MAX_CONTINUATION_TURN_RESULT_BYTES) throw new Error(`continuation adapter result must not exceed ${MAX_CONTINUATION_TURN_RESULT_BYTES} bytes`);
+  return copy;
+}
+
+function validateAdapterEvidence(value: unknown): void {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("continuation adapter evidence must be a JSON object");
+  let encoded: string;
+  try { encoded = JSON.stringify(value); }
+  catch { throw new Error("continuation adapter evidence must be JSON-serializable"); }
+  if (encoded === undefined || Buffer.byteLength(encoded, "utf8") > MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES) throw new Error(`continuation adapter evidence must not exceed ${MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES} bytes`);
+  const parsed = JSON.parse(encoded) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("continuation adapter evidence must be a JSON object");
+}
+
+export function validateBarrier(barrier: ContinuationBarrier): void {
+  if (!barrier || typeof barrier !== "object") throw new Error("continuation wait result requires a barrier");
+  if (barrier.kind === "pid") {
+    if (!Number.isSafeInteger(barrier.pid) || barrier.pid <= 0) throw new Error("continuation pid barrier requires a positive integer pid");
+    return;
+  }
+  if (barrier.kind === "deadline") {
+    if (typeof barrier.at !== "string" || !Number.isFinite(Date.parse(barrier.at))) throw new Error("continuation deadline barrier requires an ISO date-time");
+    return;
+  }
+  throw new Error("continuation barrier kind must be pid or deadline");
+}
+
+export function validateState(state: ContinuationDriverState): void {
+  if (state.schema_version !== "1.0") throw new Error("continuation driver state schema_version must be 1.0");
+  assertMaxTurns(state.max_turns);
+  if (state.adapter_command_identity !== null && (typeof state.adapter_command_identity !== "string" || state.adapter_command_identity.length === 0)) throw new Error("continuation driver adapter_command_identity must be a non-empty string or null");
+  if (!Number.isSafeInteger(state.turns_started) || state.turns_started < 0 || state.turns_started > state.max_turns) throw new Error("continuation driver turns_started is outside its mission budget");
+  if (state.active_turn_step !== undefined && state.active_turn_step !== null && (typeof state.active_turn_step !== "string" || state.active_turn_step.length === 0)) throw new Error("continuation driver active_turn_step must be a non-empty string or null");
+  if (state.active_turn_public_key_digest !== undefined && state.active_turn_public_key_digest !== null && (typeof state.active_turn_public_key_digest !== "string" || !/^[a-f0-9]{64}$/.test(state.active_turn_public_key_digest))) throw new Error("continuation driver active_turn_public_key_digest must be a SHA-256 hex digest or null");
+  if (state.active_turn_phase !== undefined && state.active_turn_phase !== null && !new Set(["prepared", "started", "measured"]).has(state.active_turn_phase)) throw new Error("continuation driver active_turn_phase must be prepared, started, measured, or null");
+  if (state.active_turn_progress) validateProgressSnapshot(state.active_turn_progress);
+  if (state.active_turn_capture) validateAcceptedTurn(state.active_turn_capture);
+  if (state.active_turn_phase === "measured" && !state.active_turn_capture) throw new Error("continuation measured turn must retain its accepted capture");
+  if (state.last_progress) validateProgressSnapshot(state.last_progress);
+  if (state.prior_progress) validatePriorProgress(state.prior_progress);
+  if (!new Set(["active", "waiting", "done", "failed", "budget_exhausted"]).has(state.status)) throw new Error("continuation driver state status is invalid");
+  if (state.status === "budget_exhausted" && state.turns_started !== state.max_turns) throw new Error("continuation driver budget_exhausted state must consume max_turns");
+  if (state.pending_barrier) validateBarrier(state.pending_barrier);
+}
+
+function validateAcceptedTurn(value: ContinuationAcceptedTurn): void {
+  if (!value || typeof value !== "object" || value.schema_version !== "1.0" || typeof value.turn_id !== "string" || !Number.isSafeInteger(value.iteration)
+    || value.iteration < 1 || value.request?.iteration !== value.iteration || typeof value.captured_at !== "string" || !Number.isFinite(Date.parse(value.captured_at))) throw new Error("continuation accepted-turn capture is malformed");
+  validateTurnResult(value.result);
+  if (value.progress !== null) validatePriorProgress(value.progress);
+}
+
+function validateProgressSnapshot(value: GateActionProgressSnapshot): void {
+  if (!value || typeof value !== "object" || typeof value.current_step !== "string" || value.current_step.length === 0
+    || (value.canonical_status !== undefined && (typeof value.canonical_status !== "string" || value.canonical_status.length === 0))
+    || !Array.isArray(value.canonical_evidence) || !value.canonical_evidence.every((entry) => typeof entry === "string")
+    || !Array.isArray(value.observed_artifacts) || !value.observed_artifacts.every((entry) => typeof entry === "string")) throw new Error("continuation driver progress snapshot is malformed");
+}
+
+function validatePriorProgress(value: GateActionPriorProgress): void {
+  if (!value || typeof value !== "object" || typeof value.step_advanced !== "boolean" || typeof value.no_progress !== "boolean"
+    || !Array.isArray(value.evidence_added) || !value.evidence_added.every((entry) => typeof entry === "string")
+    || !Array.isArray(value.artifact_changes) || !value.artifact_changes.every((entry) => typeof entry === "string")
+    || !Number.isSafeInteger(value.consecutive_no_progress) || value.consecutive_no_progress < 0 || !new Set(["none", "possible", "stagnant"]).has(value.stagnation)) throw new Error("continuation driver prior progress is malformed");
+}
+
+export function assertMissionIdentity(state: Pick<ContinuationDriverState, "run_id" | "definition_id">, snapshot: ContinuationSnapshot): void {
+  if (state.run_id !== snapshot.run_id || state.definition_id !== snapshot.definition_id) throw new Error("continuation driver mission identity does not match the canonical Flow run");
+}
+
+export function assertMaxTurns(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_CONTINUATION_TURNS) throw new Error(`continuation maxTurns must be an integer from 1 through ${MAX_CONTINUATION_TURNS}`);
+}

package/src/flow-kit/action-metadata.ts

@@ -0,0 +1,155 @@
+import * as path from "node:path";
+import { PUBLIC_OPERATION_IDS } from "../cli/public-contracts.js";
+
+export interface KitFlowStepActionEntry {
+  flow_id: string;
+  step_id: string;
+  skills: string[];
+  operations: string[];
+  expectation_ids: string[];
+  artifacts: string[];
+  implementation_allowed: boolean;
+  expectation_bindings: KitFlowStepExpectationBinding[];
+  artifact_bindings: KitFlowStepArtifactBinding[];
+}
+
+export type KitFlowStepExpectationBinding = {
+  expectation_id: string;
+  interface: "workflow.evidence" | "workflow.critique" | "operation";
+  operation?: string;
+};
+
+export type KitFlowStepArtifactBinding = { artifact: string; expectation_ids: string[] };
+
+const MAX_FLOW_STEP_ACTIONS = 128;
+const MAX_FLOW_STEP_ACTION_LIST_ITEMS = 32;
+const MAX_FLOW_STEP_ACTION_SKILLS = 16;
+const MAX_FLOW_OBSERVABLE_ARTIFACTS = 128;
+const MAX_FLOW_STEP_ACTION_TEXT = 1024;
+const WORKFLOW_TRIGGER_IDENTIFIER_RE = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+export function workflowTriggerIdentifier(value: unknown): value is string {
+  return typeof value === "string" && WORKFLOW_TRIGGER_IDENTIFIER_RE.test(value);
+}
+
+export function parseKitFlowStepActions(manifest: Record<string, unknown>, manifestPath: string): { entries: KitFlowStepActionEntry[]; errors: string[] } {
+  const entries: KitFlowStepActionEntry[] = [];
+  const errors: string[] = [];
+  const raw = manifest.flow_step_actions;
+  if (raw === undefined) return { entries, errors };
+  if (!Array.isArray(raw)) return { entries, errors: [`${manifestPath}: .flow_step_actions must be a list`] };
+  if (raw.length > MAX_FLOW_STEP_ACTIONS) return { entries, errors: [`${manifestPath}: .flow_step_actions exceeds ${MAX_FLOW_STEP_ACTIONS} entries`] };
+  const seen = new Set<string>();
+  raw.forEach((rawEntry, index) => {
+    const entry = parseFlowStepActionEntry(rawEntry, manifestPath, index, errors);
+    if (!entry) return;
+    const key = `${entry.flow_id}/${entry.step_id}`;
+    if (seen.has(key)) errors.push(`${manifestPath}: flow_step_actions[${index}] duplicates '${key}'`);
+    else { seen.add(key); entries.push(entry); }
+  });
+  validateObservableArtifactBounds(entries, manifestPath, errors);
+  return { entries, errors };
+}
+
+type FlowStepActionLists = Pick<KitFlowStepActionEntry, "skills" | "operations" | "expectation_ids" | "artifacts">;
+
+function parseFlowStepActionEntry(raw: unknown, manifestPath: string, index: number, errors: string[]): KitFlowStepActionEntry | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    errors.push(`${manifestPath}: flow_step_actions[${index}] must be an object`);
+    return null;
+  }
+  const record = raw as Record<string, unknown>;
+  const supported = new Set(["flow_id", "step_id", "skills", "operations", "expectation_ids", "artifacts", "implementation_allowed", "expectation_bindings", "artifact_bindings"]);
+  const unsupported = Object.keys(record).filter((key) => !supported.has(key));
+  if (unsupported.length) { errors.push(`${manifestPath}: flow_step_actions[${index}] has unsupported field(s): ${unsupported.join(", ")}`); return null; }
+  if (!workflowTriggerIdentifier(record.flow_id) || !workflowTriggerIdentifier(record.step_id)) {
+    errors.push(`${manifestPath}: flow_step_actions[${index}] must declare valid flow_id and step_id identifiers`);
+    return null;
+  }
+  for (const field of ["expectation_ids", "artifacts", "implementation_allowed", "expectation_bindings", "artifact_bindings"] as const) {
+    if (!Object.hasOwn(record, field)) errors.push(`${manifestPath}: flow_step_actions[${index}].${field} must be explicitly declared`);
+  }
+  const lists = parseFlowStepActionLists(record, manifestPath, index, errors);
+  if (!lists || typeof record.implementation_allowed !== "boolean") {
+    if (typeof record.implementation_allowed !== "boolean") errors.push(`${manifestPath}: flow_step_actions[${index}].implementation_allowed must be a boolean`);
+    return null;
+  }
+  const expectationBindings = parseExpectationBindings(record.expectation_bindings ?? [], lists.operations, manifestPath, index, errors);
+  if (!expectationBindings || !sameStringSet(expectationBindings.map((binding) => binding.expectation_id), lists.expectation_ids)) {
+    if (expectationBindings) errors.push(`${manifestPath}: flow_step_actions[${index}].expectation_bindings must bind every expectation_id exactly once`);
+    return null;
+  }
+  const artifactBindings = parseArtifactBindings(record.artifact_bindings ?? [], lists.artifacts, lists.expectation_ids, manifestPath, index, errors);
+  return artifactBindings ? { flow_id: record.flow_id, step_id: record.step_id, ...lists, implementation_allowed: record.implementation_allowed, expectation_bindings: expectationBindings, artifact_bindings: artifactBindings } : null;
+}
+
+function parseFlowStepActionLists(record: Record<string, unknown>, manifestPath: string, index: number, errors: string[]): FlowStepActionLists | null {
+  const skills = record.skills;
+  const operations = record.operations ?? [];
+  const expectationIds = record.expectation_ids ?? [];
+  const artifacts = record.artifacts ?? [];
+  const label = `${manifestPath}: flow_step_actions[${index}]`;
+  if ([skills, operations, expectationIds, artifacts].some((list) => Array.isArray(list) && list.length > MAX_FLOW_STEP_ACTION_LIST_ITEMS)) return fail(errors, `${label} list exceeds ${MAX_FLOW_STEP_ACTION_LIST_ITEMS} entries`);
+  if (!Array.isArray(skills) || !skills.every(workflowTriggerIdentifier) || new Set(skills).size !== skills.length) return fail(errors, `${label}.skills must be an identifier list without duplicates`);
+  if (skills.length > MAX_FLOW_STEP_ACTION_SKILLS) return fail(errors, `${label}.skills exceeds ${MAX_FLOW_STEP_ACTION_SKILLS} entries`);
+  if (!Array.isArray(operations) || !operations.every(workflowTriggerIdentifier) || new Set(operations).size !== operations.length || operations.some((operation) => !PUBLIC_OPERATION_IDS.has(operation))) return fail(errors, `${label}.operations must be unique identifiers from the canonical public operation catalog`);
+  if (!Array.isArray(expectationIds) || !expectationIds.every(workflowTriggerIdentifier) || new Set(expectationIds).size !== expectationIds.length) return fail(errors, `${label}.expectation_ids must be a unique identifier list`);
+  if (!Array.isArray(artifacts) || !artifacts.every(isSafeBuilderArtifactRef) || new Set(artifacts).size !== artifacts.length) return fail(errors, `${label}.artifacts must be unique safe session-relative paths or trust.bundle#<safe-id> refs`);
+  if ([...skills, ...operations, ...expectationIds, ...artifacts].some((entry) => entry.length > MAX_FLOW_STEP_ACTION_TEXT)) return fail(errors, `${label} values must not exceed ${MAX_FLOW_STEP_ACTION_TEXT} characters`);
+  return { skills, operations, expectation_ids: expectationIds, artifacts };
+}
+
+function fail(errors: string[], message: string): null { errors.push(message); return null; }
+
+function validateObservableArtifactBounds(entries: KitFlowStepActionEntry[], manifestPath: string, errors: string[]): void {
+  const observableByFlow = new Map<string, Set<string>>();
+  for (const action of entries) {
+    const observed = observableByFlow.get(action.flow_id) ?? new Set<string>();
+    for (const artifact of action.artifacts) if (isObservableBuilderArtifactRef(artifact)) observed.add(artifact);
+    observableByFlow.set(action.flow_id, observed);
+  }
+  for (const [flowId, artifacts] of observableByFlow) if (artifacts.size > MAX_FLOW_OBSERVABLE_ARTIFACTS) errors.push(`${manifestPath}: flow_step_actions for '${flowId}' exceed ${MAX_FLOW_OBSERVABLE_ARTIFACTS} distinct observable file artifacts`);
+}
+
+function parseExpectationBindings(value: unknown, operations: string[], manifestPath: string, actionIndex: number, errors: string[]): KitFlowStepExpectationBinding[] | null {
+  if (!Array.isArray(value) || value.length > MAX_FLOW_STEP_ACTION_LIST_ITEMS) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].expectation_bindings must be a bounded list`);
+  const bindings: KitFlowStepExpectationBinding[] = [];
+  for (const [bindingIndex, entry] of value.entries()) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].expectation_bindings[${bindingIndex}] must be an object`);
+    const record = entry as Record<string, unknown>;
+    const unsupported = Object.keys(record).filter((key) => key !== "expectation_id" && key !== "interface" && key !== "operation");
+    if (unsupported.length) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].expectation_bindings[${bindingIndex}] has unsupported field(s): ${unsupported.join(", ")}`);
+    if (!workflowTriggerIdentifier(record.expectation_id) || !new Set(["workflow.evidence", "workflow.critique", "operation"]).has(String(record.interface))) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].expectation_bindings[${bindingIndex}] must declare a valid expectation_id and interface`);
+    if (record.interface === "operation") {
+      if (!workflowTriggerIdentifier(record.operation) || !operations.includes(record.operation) || !PUBLIC_OPERATION_IDS.has(record.operation)) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].expectation_bindings[${bindingIndex}].operation must name a declared canonical public operation`);
+    } else if (record.operation !== undefined) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].expectation_bindings[${bindingIndex}].operation is allowed only for operation bindings`);
+    bindings.push({ expectation_id: record.expectation_id as string, interface: record.interface as KitFlowStepExpectationBinding["interface"], ...(typeof record.operation === "string" ? { operation: record.operation } : {}) });
+  }
+  if (new Set(bindings.map((binding) => binding.expectation_id)).size !== bindings.length) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].expectation_bindings must not duplicate expectation ids`);
+  return bindings;
+}
+
+function parseArtifactBindings(value: unknown, artifacts: string[], expectationIds: string[], manifestPath: string, actionIndex: number, errors: string[]): KitFlowStepArtifactBinding[] | null {
+  if (!Array.isArray(value) || value.length > MAX_FLOW_STEP_ACTION_LIST_ITEMS) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings must be a bounded list`);
+  const bindings: KitFlowStepArtifactBinding[] = [];
+  for (const [bindingIndex, entry] of value.entries()) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings[${bindingIndex}] must be an object`);
+    const record = entry as Record<string, unknown>;
+    if (Object.keys(record).some((key) => key !== "artifact" && key !== "expectation_ids") || typeof record.artifact !== "string" || !artifacts.includes(record.artifact)
+      || !Array.isArray(record.expectation_ids) || !record.expectation_ids.every((id) => typeof id === "string" && expectationIds.includes(id)) || new Set(record.expectation_ids).size !== record.expectation_ids.length) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings[${bindingIndex}] must bind one declared artifact to declared expectation_ids`);
+    bindings.push({ artifact: record.artifact, expectation_ids: record.expectation_ids as string[] });
+  }
+  if (!sameStringSet(bindings.map((binding) => binding.artifact), artifacts)) return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings must bind every artifact exactly once`);
+  return bindings;
+}
+
+export function isSafeBuilderArtifactRef(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0 || value.includes("\0") || value.includes("\\")) return false;
+  if (value.startsWith("trust.bundle#")) return /^trust\.bundle#[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(value);
+  if (value.includes("#") || path.posix.isAbsolute(value)) return false;
+  const expanded = value.replaceAll("<slug>", "slug");
+  return expanded !== "." && !expanded.split("/").some((part) => part === "" || part === "." || part === "..");
+}
+
+export function isObservableBuilderArtifactRef(value: string): boolean { return !value.includes("#") && path.posix.normalize(value) !== "state.json"; }
+export function sameStringSet(left: string[], right: string[]): boolean { return left.length === right.length && new Set(left).size === left.length && left.every((entry) => right.includes(entry)); }