forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/agent-fabric/program-store.ts

@@ -0,0 +1,142 @@
+import { mkdir, open, readFile, rename, unlink, realpath, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID, createHash } from "node:crypto";
+import { assertAttachedSafePath } from "./attached-snapshot.ts";
+import { ProgramFileLease } from "./program-lock.ts";
+import { stableStringify } from "./canonical.ts";
+import { programAssert, programDigest, validateWorkflowProgram, type ProgramRunV2 } from "./program-contract.ts";
+
+interface ProgramReceipt { requestId: string; fingerprint: string; version: number }
+interface ProgramTransition { runId: string; version: number; type: string; at: string; stateDigest: string; stateRef: string; parentRef?: string }
+interface ProgramRecord { format: 3; runId: string; stateRef: string; journalRef: string; version: number; receipts: ProgramReceipt[] }
+const absent = (error: unknown) => (error as NodeJS.ErrnoException).code === "ENOENT";
+const sharingViolation = (error: unknown) => ["EPERM", "EACCES", "EBUSY"].includes((error as NodeJS.ErrnoException).code ?? "");
+async function retrySharing<T>(action: () => Promise<T>): Promise<T> {
+  const deadline = Date.now() + 1000;
+  for (;;) { try { return await action(); } catch (error) { if (!sharingViolation(error) || Date.now() >= deadline) throw error; await new Promise(resolve => setTimeout(resolve, 20)); } }
+}
+/** One authoritative atomic record per run; artifacts commit before referring transitions. */
+export class ProgramRunStore {
+  readonly metrics = { transactions: 0, transactionMs: 0, bytesWritten: 0, snapshotBytes: 0, journalBytes: 0, envelopeBytes: 0, artifactBytes: 0, artifactReads: 0 };
+  private tails = new Map<string, Promise<unknown>>();
+  private definitions = new Set<string>();
+  private validate(state: ProgramRunV2): void {
+    const key = `${programDigest(state.program)}:${programDigest(state.registry)}`;
+    if (!this.definitions.has(key)) { validateWorkflowProgram(state.program, state.registry); this.definitions.add(key); }
+  }
+  private constructor(readonly root: string, readonly directory: string) {}
+  static async open(root: string): Promise<ProgramRunStore> {
+    root = await realpath(root); const directory = join(root, ".forge/local/agent-fabric/program-runs-v3");
+    await assertAttachedSafePath(root, directory); await mkdir(join(directory, "artifacts"), { recursive: true });
+    await assertAttachedSafePath(root, directory); return new ProgramRunStore(root, directory);
+  }
+  private path(id: string): string { programAssert(typeof id === "string" && id.length > 0 && id.length <= 256, "Invalid run ID"); return join(this.directory, `${programDigest(id).slice(7)}.json`); }
+  async put(value: unknown, maxBytes = 4 * 1024 * 1024, category: "snapshotBytes" | "journalBytes" | "artifactBytes" = "artifactBytes"): Promise<string> {
+    const bytes = stableStringify(value), digest = programDigest(value); programAssert(Buffer.byteLength(bytes) <= maxBytes, "Artifact too large");
+    const path = join(this.directory, "artifacts", `${digest.slice(7)}.json`); await assertAttachedSafePath(this.root, path);
+    const temp = `${path}.${randomUUID()}.tmp`, handle = await open(temp, "wx", 0o600);
+    try { await handle.writeFile(bytes); await handle.sync(); this.metrics.bytesWritten += Buffer.byteLength(bytes); this.metrics[category] += Buffer.byteLength(bytes); } finally { await handle.close(); }
+    try {
+      try { programAssert(await readFile(path, "utf8") === bytes, "Immutable artifact corrupted"); }
+      catch (error) { if (!absent(error)) throw error; await retrySharing(() => rename(temp, path)); }
+    } finally { await unlink(temp).catch(() => {}); }
+    return digest;
+  }
+  async get<T = unknown>(digest: string): Promise<T> {
+    this.metrics.artifactReads++;
+    programAssert(/^sha256:[a-f0-9]{64}$/.test(digest), "Invalid artifact reference");
+    const path = join(this.directory, "artifacts", `${digest.slice(7)}.json`); await assertAttachedSafePath(this.root, path);
+    const bytes = await readFile(path, "utf8"); programAssert(Buffer.byteLength(bytes) <= 32 * 1024 * 1024, "Artifact exceeds physical limit");
+    const value = JSON.parse(bytes); programAssert(programDigest(value) === digest, "Artifact integrity failed"); return value as T;
+  }
+  async putBinary(bytes: Uint8Array, maxBytes = 8 * 1024 * 1024): Promise<string> {
+    programAssert(bytes.byteLength <= maxBytes, "Binary artifact exceeds byte budget");
+    const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`, path = join(this.directory, "artifacts", `${digest.slice(7)}.blob`);
+    await assertAttachedSafePath(this.root, path);
+    const temp = `${path}.${randomUUID()}.tmp`, handle = await open(temp, "wx", 0o600);
+    try { await handle.writeFile(bytes); await handle.sync(); this.metrics.bytesWritten += bytes.byteLength; this.metrics.artifactBytes += bytes.byteLength; } finally { await handle.close(); }
+    try { try { programAssert((await readFile(path)).equals(Buffer.from(bytes)), "Immutable binary corrupted"); } catch (error) { if (!absent(error)) throw error; await retrySharing(() => rename(temp, path)); } }
+    finally { await unlink(temp).catch(() => {}); } return digest;
+  }
+  async getBinary(digest: string, maxBytes = 8 * 1024 * 1024): Promise<Buffer> {
+    programAssert(/^sha256:[a-f0-9]{64}$/.test(digest), "Invalid binary reference");
+    const path = join(this.directory, "artifacts", `${digest.slice(7)}.blob`); await assertAttachedSafePath(this.root, path);
+    programAssert(Number.isSafeInteger(maxBytes) && maxBytes > 0 && (await stat(path)).size <= maxBytes, "Binary exceeds physical byte budget");
+    const bytes = await readFile(path); programAssert(bytes.length <= maxBytes && `sha256:${createHash("sha256").update(bytes).digest("hex")}` === digest, "Binary integrity/byte limit failed"); return bytes;
+  }
+  private async record(id: string): Promise<ProgramRecord | undefined> {
+    const path = this.path(id); await assertAttachedSafePath(this.root, path);
+    let bytes: string; try { bytes = await retrySharing(() => readFile(path, "utf8")); } catch (error) { if (absent(error)) return; throw error; }
+    programAssert(Buffer.byteLength(bytes) <= 32 * 1024 * 1024, "Program record exceeds limit");
+    const envelope = JSON.parse(bytes) as { record: ProgramRecord; digest: string };
+    programAssert(programDigest(envelope.record) === envelope.digest, "Program record integrity failed");
+    const record = envelope.record;
+    programAssert(record.format === 3 && record.runId === id && record.version > 0, "Unsupported/corrupt program record; start a new run");
+    const state = await this.get<ProgramRunV2>(record.stateRef), checkpoint = await this.get<ProgramTransition>(record.journalRef);
+    programAssert(state.schemaVersion === 2 && state.runId === id && state.version === record.version, "Invalid persisted run identity");
+    this.validate(state);
+    programAssert(programDigest(state.program) === state.programDigest && programDigest(state.registry) === state.registryDigest, "Pinned program/registry corrupted");
+    programAssert(checkpoint.runId === id && checkpoint.stateDigest === record.stateRef && checkpoint.stateRef === record.stateRef && checkpoint.version === state.version, "Checkpoint/journal mismatch");
+    return record;
+  }
+  async read(id: string): Promise<ProgramRunV2 | undefined> { const record = await this.record(id); return record ? this.get<ProgramRunV2>(record.stateRef) : undefined; }
+  async history(id: string): Promise<ProgramTransition[]> {
+    const record = await this.record(id); if (!record) return [];
+    const history: ProgramTransition[] = []; let ref: string | undefined = record.journalRef, version = record.version;
+    while (ref) {
+      const node: ProgramTransition = await this.get<ProgramTransition>(ref);
+      programAssert(node.runId === id && node.version === version-- && node.stateDigest === node.stateRef && history.length < 100000, "Journal chain mismatch");
+      const state = await this.get<ProgramRunV2>(node.stateRef);
+      programAssert(state.runId === id && state.version === node.version, "Historical snapshot identity mismatch");
+      history.push(node); ref = node.parentRef;
+    }
+    programAssert(version === 0, "Truncated program journal"); return history.reverse();
+  }
+  async list(): Promise<string[]> {
+    const ids: string[] = [];
+    for (const name of await readdir(this.directory)) {
+      if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+      const path = join(this.directory, name); await assertAttachedSafePath(this.root, path);
+      const envelope = JSON.parse(await readFile(path, "utf8"));
+      programAssert(envelope?.record?.runId && this.path(envelope.record.runId) === path, "Run filename/identity mismatch");
+      await this.record(envelope.record.runId); ids.push(envelope.record.runId);
+    }
+    return ids;
+  }
+  async transact(id: string, type: string, mutate: (state?: ProgramRunV2) => ProgramRunV2,
+    options: { requestId?: string; fingerprint?: string; expectedVersion?: number } = {}): Promise<ProgramRunV2> {
+    const task = (this.tails.get(id) ?? Promise.resolve()).catch(() => {}).then(() => this.transaction(id, type, mutate, options));
+    this.tails.set(id, task);
+    try { return await task; } finally { if (this.tails.get(id) === task) this.tails.delete(id); }
+  }
+  private async transaction(id: string, type: string, mutate: (state?: ProgramRunV2) => ProgramRunV2,
+    options: { requestId?: string; fingerprint?: string; expectedVersion?: number }): Promise<ProgramRunV2> {
+    const transactionStarted = performance.now();
+    const path = this.path(id), lock = `${path}.lock`;
+    await assertAttachedSafePath(this.root, lock); await assertAttachedSafePath(this.root, `${lock}.reclaim`);
+    const lease = await ProgramFileLease.acquire(lock, { waitMs: 10000 });
+    try {
+      const old = await this.record(id), receipt = old?.receipts.find(entry => entry.requestId === options.requestId);
+      if (receipt) { programAssert(receipt.fingerprint === options.fingerprint, "requestId body changed", "AF_PROGRAM_CONFLICT"); return this.get<ProgramRunV2>(old!.stateRef); }
+      programAssert(options.expectedVersion === undefined || options.expectedVersion === (old?.version ?? 0), "Version conflict", "AF_PROGRAM_CONFLICT");
+      if (options.requestId) programAssert(typeof options.fingerprint === "string", "Request fingerprint required");
+      const oldState = old ? await this.get<ProgramRunV2>(old.stateRef) : undefined;
+      if (type === "attempt-dispatch-intent") programAssert(!old || old.version < 90000 && Buffer.byteLength(stableStringify(oldState)) < 24 * 1024 * 1024, "Journal dispatch reserve exhausted; recovery remains available");
+      const state = mutate(oldState);
+      if (old && !options.requestId && programDigest(state) === old.stateRef) return structuredClone(state);
+      state.version = (old?.version ?? 0) + 1;
+      this.validate(state);
+      const stateRef = await this.put(state, 32 * 1024 * 1024, "snapshotBytes");
+      const journalRef = await this.put({ runId: id, version: state.version, type, at: new Date().toISOString(), stateDigest: stateRef, stateRef, ...(old ? { parentRef: old.journalRef } : {}) }, 4096, "journalBytes");
+      const record: ProgramRecord = { format: 3, runId: id, version: state.version, stateRef, journalRef,
+        receipts: [...(old?.receipts ?? []), ...(options.requestId ? [{ requestId: options.requestId, fingerprint: options.fingerprint!, version: state.version }] : [])] };
+      const bytes = stableStringify({ record, digest: programDigest(record) }); programAssert(Buffer.byteLength(bytes) <= 32 * 1024 * 1024 && record.receipts.length <= 10000 && record.version <= 100000, "Program journal limit exceeded");
+      const token = lease.token;
+      const temp = `${path}.${token}.tmp`, handle = await open(temp, "wx", 0o600);
+      try { await handle.writeFile(bytes); await handle.sync(); this.metrics.bytesWritten += Buffer.byteLength(bytes); this.metrics.envelopeBytes += Buffer.byteLength(bytes); } finally { await handle.close(); }
+      this.metrics.transactions++; this.metrics.transactionMs += performance.now() - transactionStarted;
+      try { await assertAttachedSafePath(this.root, path); await retrySharing(() => rename(temp, path)); } finally { await unlink(temp).catch(() => {}); }
+      return structuredClone(state);
+    } finally { await retrySharing(() => lease.close()); }
+  }
+}

package/src/forge/agent-fabric/program-structure.ts

@@ -0,0 +1,65 @@
+import { programAssert, type ProgramOperation, type WorkflowProgramV2 } from "./program-contract.ts";
+
+export interface ProgramBlock { steps: ProgramOperation[]; result: unknown }
+/** Only a single operation has a shorthand result. Arrays are not sequences. */
+export function programBlock(value: unknown): ProgramBlock {
+  if (value && typeof value === "object" && !Array.isArray(value) && "steps" in value) {
+    const block = value as ProgramBlock;
+    programAssert(Array.isArray(block.steps) && Object.hasOwn(block, "result"), "Block requires steps and explicit result"); return block;
+  }
+  const steps = Array.isArray(value) ? value : [value];
+  programAssert(steps.length === 1 && steps[0] && typeof steps[0].id === "string", "Multiple operations require Block {steps,result}");
+  return { steps, result: { $expr: "output", args: [steps[0].id] } };
+}
+export function canonicalItemKey(value: unknown): string {
+  programAssert(typeof value === "string" && value.length > 0 && !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value), "Map key must be a valid Unicode string");
+  const key = value.normalize("NFC"); programAssert(Buffer.byteLength(key) <= 256, "Map key byte limit exceeded"); return key;
+}
+export const compareProgramKeys = (a: string, b: string): number => Buffer.compare(Buffer.from(a), Buffer.from(b));
+export const programSegment = (key: string): string => encodeURIComponent(canonicalItemKey(key)).replace(/[!'()*]/g, char => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+
+export interface ProgramGraphEntry { id: string; step: ProgramOperation; dependencies: string[] }
+/** Static templates, lexical references and control edges. No authored code executes. */
+export function programGraph(program: WorkflowProgramV2): ProgramGraphEntry[] {
+  const graph = new Map<string, ProgramGraphEntry>();
+  function refs(value: unknown, resolve: (id: string) => string | undefined, dependencies: Set<string>): void {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) { for (const entry of value) refs(entry, resolve, dependencies); return; }
+    const record = value as Record<string, unknown>;
+    if (record.$expr === "literal") return;
+    if (["output", "acceptedCandidate", "acceptedCandidates", "outputCandidate", "coverageReceipt"].includes(String(record.$expr))) {
+      const id = (record.args as unknown[])[0]; programAssert(typeof id === "string", "Output ID required"); const target = resolve(id); programAssert(target, `Unknown output ${id}`); dependencies.add(target);
+    }
+    for (const child of Object.values(record)) refs(child, resolve, dependencies);
+  }
+  function scope(block: ProgramBlock, prefix: string, outer?: (id: string) => string | undefined, sequential = false): void {
+    const resolve = (id: string) => block.steps.some(step => step.id === id) ? `${prefix}${id}` : outer?.(id);
+    for (let index = 0; index < block.steps.length; index++) {
+      const step = block.steps[index], id = `${prefix}${step.id}`, dependencies = new Set<string>();
+      if (sequential && index) dependencies.add(`${prefix}${block.steps[index - 1].id}`);
+      const after = step.options.after ?? []; programAssert(Array.isArray(after) && after.every(entry => typeof entry === "string"), "after requires operation IDs");
+      for (const predecessor of after) { const target = resolve(predecessor); programAssert(target, `Unknown control predecessor ${predecessor}`); dependencies.add(target); }
+      refs(Object.fromEntries(Object.entries(step.options).filter(([key]) => !["body", "steps", "result", "then", "else", "next", "until", "after"].includes(key))), resolve, dependencies);
+      const children: { block: ProgramBlock; prefix: string; sequential?: boolean }[] = [];
+      if (step.kind === "sequence" || step.kind === "parallel") children.push({ block: programBlock(step.options), prefix: `${id}/`, sequential: step.kind === "sequence" });
+      if (step.kind === "map" || step.kind === "loop") children.push({ block: programBlock(step.options.body), prefix: `${id}/body/` });
+      if (step.kind === "branch") for (const arm of ["then", "else"]) children.push({ block: programBlock(step.options[arm]), prefix: `${id}/${arm}/` });
+      programAssert(!graph.has(id), "Duplicate operation ID"); graph.set(id, { id, step, dependencies: [] });
+      for (const child of children) {
+        scope(child.block, child.prefix, resolve, child.sequential);
+        for (const entry of child.block.steps) dependencies.add(`${child.prefix}${entry.id}`);
+        const childResolve = (target: string) => child.block.steps.some(entry => entry.id === target) ? `${child.prefix}${target}` : resolve(target);
+        refs(child.block.result, childResolve, dependencies);
+        if (step.kind === "loop") {
+          refs(step.options.next, childResolve, dependencies); refs(step.options.until, childResolve, dependencies);
+        }
+      }
+      graph.get(id)!.dependencies = [...dependencies];
+    }
+    refs(block.result, resolve, new Set());
+  }
+  scope({ steps: program.steps, result: program.result }, "");
+  const visited = new Set<string>(), visiting = new Set<string>();
+  function visit(id: string): void { programAssert(!visiting.has(id), `Dependency cycle ${id}`); if (visited.has(id)) return; visiting.add(id); for (const dependency of graph.get(id)?.dependencies ?? []) visit(dependency); visiting.delete(id); visited.add(id); }
+  for (const id of graph.keys()) visit(id); return [...graph.values()];
+}

package/src/forge/agent-fabric/program-types.ts

@@ -0,0 +1,110 @@
+import { programBlock } from "./program-structure.ts";
+import { programAssert, programDigest, registryEntry, validateProgramData, type ProgramOperation, type ProgramRegistry, type ProgramSchema, type ProgramLexicalContext, type WorkflowProgramV2 } from "./program-contract.ts";
+
+/** Conservative finite inference: unknown schemas retain runtime validation. No JS evaluation. */
+export function validateProgramTypes(program: WorkflowProgramV2, registry: ProgramRegistry, lexical: ProgramLexicalContext = {}, depth = 0): void {
+  programAssert(depth <= 32, "Subworkflow type context depth exceeded");
+  type Shape = ProgramSchema;
+  interface Scope { steps: ProgramOperation[]; input: Shape; parent?: Scope; item?: Shape; state?: Shape }
+  const cache = new Map<ProgramOperation, Shape>();
+  const candidate: Shape = { type: "object", properties: { candidateId: { type: "string" }, digest: { type: "string" }, baselineDigest: { type: "string" }, parents: { type: "array" }, deltas: { type: "array" }, producerAttempts: { type: "array" } } };
+  function types(shape: Shape): string[] { return shape.type ? Array.isArray(shape.type) ? shape.type : [shape.type] : []; }
+  function compatible(actual: Shape, expected: Shape, label: string): void {
+    if (Object.hasOwn(actual, "const")) { validateProgramData(actual.const, expected); return; }
+    if (actual.anyOf) { for (const alternative of actual.anyOf) compatible(alternative, expected, label); return; }
+    const a = types(actual), e = types(expected);
+    if (a.length && e.length) programAssert(a.every(type => e.includes(type) || type === "integer" && e.includes("number")), `Incompatible type at ${label}`);
+    if (actual.properties && expected.properties) for (const [key, value] of Object.entries(actual.properties)) {
+      if (Object.hasOwn(expected.properties, key)) compatible(value, expected.properties[key], `${label}.${key}`);
+      else programAssert(expected.additionalProperties !== false, `Unexpected field at ${label}.${key}`);
+    }
+    if (actual.required) for (const key of expected.required ?? []) programAssert(actual.required.includes(key), `Missing required field at ${label}.${key}`);
+    if (actual.items && expected.items) compatible(actual.items, expected.items, `${label}[]`);
+  }
+  function constant(value: unknown): Shape {
+    const type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+    return { type, const: value as never };
+  }
+  function reference(id: string, scope: Scope): Shape {
+    const operation = scope.steps.find(step => step.id === id);
+    if (operation) return operationShape(operation, scope);
+    programAssert(scope.parent, `Unknown typed output ${id}`); return reference(id, scope.parent);
+  }
+  function infer(value: unknown, scope: Scope): Shape {
+    if (!value || typeof value !== "object") return constant(value);
+    if (Array.isArray(value)) return { type: "array", items: value.length ? { anyOf: value.map(entry => infer(entry, scope)) } : {}, minItems: value.length, maxItems: value.length };
+    const record = value as Record<string, unknown>;
+    if (!Object.hasOwn(record, "$expr")) return { type: "object", properties: Object.fromEntries(Object.entries(record).map(([key, entry]) => [key, infer(entry, scope)])), required: Object.keys(record), additionalProperties: false };
+    const name = String(record.$expr), args = record.args as unknown[];
+    if (name === "literal") return constant(args[0]);
+    if (name === "workflowInput") return scope.input;
+    if (name === "item") { programAssert(scope.item, "item requires map context"); return scope.item; }
+    if (name === "loopState") return scope.state ?? {};
+    if (name === "output") return reference(String(args[0]), scope);
+    if (["outputCandidate", "acceptedCandidate", "candidateFromBaseline"].includes(name)) return candidate;
+    if (name === "acceptedCandidates") return { type: "array", items: candidate };
+    if (name === "object") return infer(args[0], scope);
+    if (name === "array") return { type: "array", items: args.length ? infer(args[0], scope) : {} };
+    if (name === "field") {
+      const input = infer(args[0], scope), key = String(args[1]);
+      if (input.anyOf) {
+        const alternatives = input.anyOf.map(alternative => {
+          if (Object.hasOwn(alternative, "const")) { programAssert(alternative.const && typeof alternative.const === "object" && Object.hasOwn(alternative.const, key), `Field absent ${key} in branch merge`); return constant((alternative.const as Record<string, unknown>)[key]); }
+          programAssert(!alternative.properties || Object.hasOwn(alternative.properties, key) || alternative.additionalProperties !== false, `Field absent ${key} in branch merge`); return alternative.properties?.[key] ?? {};
+        });
+        return { anyOf: alternatives };
+      }
+      if (Object.hasOwn(input, "const")) { programAssert(input.const && typeof input.const === "object" && Object.hasOwn(input.const, key), `Field absent ${key}`); return constant((input.const as Record<string, unknown>)[key]); }
+      if (input.type) compatible(input, { type: "object" }, "field input");
+      programAssert(!input.properties || Object.hasOwn(input.properties, key) || input.additionalProperties !== false, `Field absent ${key}`); return input.properties?.[key] ?? {};
+    }
+    if (["eq", "and", "or", "not"].includes(name)) return { type: "boolean" };
+    if (name === "length") return { type: "integer" };
+    if (["concat", "filter", "unique", "sort", "take"].includes(name)) { const input = infer(args[0], scope); if (input.type) compatible(input, { type: "array" }, `${name} input`); return { type: "array", items: input.items ?? {} }; }
+    if (["acceptanceChecks", "approvedChecksFor", "acceptanceWriteScope"].includes(name)) return { type: "array", items: { type: "string" } };
+    return {};
+  }
+  function operationShape(step: ProgramOperation, scope: Scope): Shape {
+    const cached = cache.get(step); if (cached) return cached;
+    const options = step.options; let shape: Shape = {};
+    if (step.kind === "value") shape = infer(options.value, scope);
+    if (step.kind === "agent" || step.kind === "command") {
+      const executor = registryEntry(registry.executors, options.executor as never);
+      if (executor.inputSchema) compatible(infer(options.input ?? {}, scope), registryEntry(registry.schemas, executor.inputSchema), `activity ${step.id} input`);
+      shape = registryEntry(registry.schemas, executor.schema);
+    }
+    if (step.kind === "waitEvent") shape = registryEntry(registry.schemas, options.schema as never);
+    if (step.kind === "subworkflow") {
+      const child = registryEntry(registry.programs ?? {}, options.program as never);
+      compatible(infer(options.input, scope), registryEntry(registry.schemas, child.inputSchema), `child ${step.id} input`);
+      validateProgramTypes(child, registry, { item: scope.item, state: scope.state }, depth + 1);
+      shape = registryEntry(registry.schemas, child.outputSchema);
+    }
+    if (step.kind === "branch") {
+      compatible(infer(options.condition, scope), { type: "boolean" }, `branch ${step.id} condition`);
+      const arms = ["then", "else"].map(arm => { const block = programBlock(options[arm]), steps = block.steps, child = { ...scope, steps, parent: scope }; for (const entry of steps) operationShape(entry, child); return infer(block.result, child); });
+      const left = types(arms[0]), right = types(arms[1]);
+      programAssert(!left.length || !right.length || programDigest(left) === programDigest(right), `Incompatible branch merge ${step.id}`);
+      shape = { anyOf: arms, ...(left.length && right.length ? { type: left } : {}) };
+    }
+    if (step.kind === "map" || step.kind === "loop") {
+      const steps = programBlock(options.body).steps;
+      const items = step.kind === "map" ? infer(options.items, scope) : {}, state = step.kind === "loop" ? infer(options.initialState, scope) : {};
+      if (step.kind === "map") compatible(items, { type: "array" }, `map ${step.id} items`);
+      const child = { ...scope, steps, parent: scope, item: step.kind === "map" ? items.items ?? {} : scope.item, state: step.kind === "loop" ? state : scope.state };
+      for (const entry of steps) operationShape(entry, child);
+      infer(programBlock(options.body).result, child);
+      if (step.kind === "loop") { compatible(infer(options.next, child), { type: state.type }, `loop ${step.id} state`); compatible(infer(options.until, child), { type: "boolean" }, `loop ${step.id} condition`); }
+      shape = step.kind === "loop" ? state : { type: "object" };
+    }
+    if (["sequence", "parallel"].includes(step.kind)) {
+      const block = programBlock(options), child = { ...scope, steps: block.steps, parent: scope };
+      for (const entry of block.steps) operationShape(entry, child); shape = infer(block.result, child);
+    }
+    if (["repair", "compose", "gate"].includes(step.kind)) shape = { type: "object" };
+    cache.set(step, shape); return shape;
+  }
+  const scope: Scope = { ...lexical, steps: program.steps, input: registryEntry(registry.schemas, program.inputSchema) };
+  for (const step of program.steps) operationShape(step, scope);
+  compatible(infer(program.result, scope), registryEntry(registry.schemas, program.outputSchema), "program result");
+}

package/src/forge/agent-fabric/program-view.ts

@@ -0,0 +1,12 @@
+import { programDigest, type ProgramOperationRecord, type WorkflowProgramV2 } from "./program-contract.ts";
+import { programGraph } from "./program-structure.ts";
+
+/** Inspection only; static templates are distinct from observed expansion instances. */
+export function programVisualization(program: WorkflowProgramV2, operations: Record<string, ProgramOperationRecord> = {}) {
+  const nodes = programGraph(program).map(({ id, step, dependencies }) => ({ id, kind: step.kind, dependencies, status: operations[id]?.status ?? "template" }));
+  const key = (id: string) => `n${programDigest(id).slice(7, 31)}`;
+  const label = (value: string) => value.replace(/[&<>"\[\]{}\n\r]/g, "_");
+  const lines = ["flowchart TD", ...nodes.map(node => `  ${key(node.id)}["${label(`${node.id}: ${node.kind} (${node.status})`)}"]`)];
+  for (const node of nodes) for (const dependency of node.dependencies) lines.push(`  ${key(dependency)} --> ${key(node.id)}`);
+  return { nodes, instances: Object.values(operations).map(operation => ({ id: operation.id, kind: operation.kind, status: operation.status, generation: operation.generation, retired: operation.retired ?? false })), mermaid: lines.join("\n"), semantics: "Static template dependency graph; runtime expansions appear separately in instances" };
+}

package/src/forge/agent-fabric/program-worker.ts

@@ -0,0 +1,108 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, realpath, writeFile, mkdtemp, mkdir, stat } from "node:fs/promises";
+import { join, isAbsolute, resolve, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { codexWorkerEnvironment, codexWorkerRuntimeIdentity, runTypedCodexWorker } from "./codex-sdk-worker.ts";
+import { programAssert, programDigest, programPath, programWithin, registryEntry, validateProgramData, type ProgramExecutor, type ProgramPolicy, type ProgramAcceptance, type ProgramRegistry, type ProgramCandidate } from "./program-contract.ts";
+import { prepareManagedWorkspace, captureManagedArtifact, type ManagedBase, type ManagedArtifact } from "./managed-workspace.ts";
+import { prepareManagedEnvironment } from "./managed-environment.ts";
+
+export interface ProgramWorkerInput {
+  executor: ProgramExecutor; data: unknown; candidate?: ProgramCandidate; artifacts: ManagedArtifact[];
+  base?: ManagedBase; attemptId: string; scope: string[]; signal: AbortSignal;
+  registry: ProgramRegistry; onThread: (id: string) => Promise<void>;
+  evidence?: { receiptId: string; bytes: Uint8Array; mime: string; itemKey: string }[];
+}
+export interface ProgramEvidenceArtifact { bytes: Uint8Array; mime: string; width: number; height: number; itemKey: string; environmentRef: string; buildDigest: string; route: string; viewport: string; state: string }
+export interface ProgramWorkerResult { outcome: "completed" | "infrastructure_failed" | "invalid_output" | "uncertain"; data?: unknown; artifact?: ManagedArtifact; evidence?: ProgramEvidenceArtifact[]; inputDigest?: string; reason?: string; usage?: unknown }
+export interface ProgramWorkerPreparation { directory: string; inputDigest: string; reusable?: boolean; execute: () => Promise<ProgramWorkerResult> }
+export type ProgramWorkerAdapter = (input: ProgramWorkerInput) => Promise<ProgramWorkerPreparation>;
+
+export function validateProgramCapabilities(executor: ProgramExecutor, policy: ProgramPolicy, acceptance: ProgramAcceptance, requestedScope: string[]): string[] {
+  programAssert(policy.executors.includes(`${executor.id}@${executor.version}`), "Executor outside owner policy");
+  programAssert(Number.isSafeInteger(executor.timeoutMs) && executor.timeoutMs > 0 && executor.timeoutMs <= policy.deadlineMs, "Invalid executor deadline");
+  programAssert(executor.kind === "codex" || executor.kind === "command", "Unsupported executor adapter");
+  programAssert(executor.network === "disabled" || executor.network === "host", "Network capability required");
+  programAssert(executor.network !== "host" || policy.allowNetwork, "Network exceeds policy");
+  programAssert(executor.effect === "read" || executor.effect === "isolated-write", "External effects require a registered receipt/reconciliation adapter");
+  programAssert(!executor.role || ["implementer", "reviewer", "investigator", "decision"].includes(executor.role), "Unsupported executor role");
+  programAssert(executor.effect !== "isolated-write" || executor.role === "implementer", "Only implementer executors may write");
+  programAssert(executor.dependencies === undefined || executor.dependencies === "none" || executor.dependencies === "auto" && policy.allowNetwork, "Dependency preparation requires owner network permission");
+  programAssert(executor.cache === undefined || executor.cache === "none" || executor.cache === "workspace" && executor.kind === "command", "SDK instruction closure does not attest reusable outputs");
+  programAssert(Object.keys(executor.environment ?? {}).every(key => !/token|secret|password|credential|api.?key/i.test(key)), "Secrets cannot be persisted in executor configuration");
+  for (const path of [...executor.writeScope, ...requestedScope, ...(executor.allowedGeneratedPaths ?? [])]) programPath(path);
+  const scope = requestedScope.filter(path => programWithin(path, executor.writeScope) && programWithin(path, policy.writeScope) && programWithin(path, acceptance.writeScope));
+  programAssert(scope.length === requestedScope.length, "Requested write scope exceeds owner authorization");
+  if (executor.effect === "isolated-write") programAssert(scope.length > 0, "Writing executor requires resolved scope");
+  if (executor.kind === "command") {
+    programAssert(policy.allowCooperativeCommands && executor.isolation === "cooperative", "Commands are cooperative, not a strong sandbox");
+    programAssert(executor.network === "host", "Cooperative command cannot prove network disabled");
+    programAssert(Array.isArray(executor.argv) && executor.argv.length > 0 && executor.argv.length < 100 && executor.argv.every(arg => typeof arg === "string" && !arg.includes("\0") && arg.length <= 16000), "Explicit argv required");
+  } else programAssert(executor.isolation === "sandbox" && executor.network === "disabled" && (!executor.role || executor.role !== "implementer" || executor.effect === "isolated-write"), "Codex capability mismatch");
+  programAssert(!(executor.allowedGeneratedPaths ?? []).some(path => programWithin(path, acceptance.writeScope) || programWithin(path, scope)), "Generated paths overlap immutable candidate");
+  return scope;
+}
+async function executableIdentity(executable: string, directory: string, environment: NodeJS.ProcessEnv): Promise<{ path: string; digest: string }> {
+  // PATH resolution is part of the observed binary input, never just argv[0].
+  const envValue = (name: string) => Object.entries(environment).find(([key]) => key.toUpperCase() === name)?.[1];
+  const paths = isAbsolute(executable) || executable.includes("/") || executable.includes("\\") ? [resolve(directory, executable)] : (envValue("PATH") ?? "").split(process.platform === "win32" ? ";" : ":").flatMap(path => process.platform === "win32" ? (envValue("PATHEXT") ?? ".EXE;.CMD;.BAT").split(";").map(extension => join(path, executable.toUpperCase().endsWith(extension.toUpperCase()) ? executable : executable + extension.toLowerCase())) : [join(path, executable)]);
+  for (const path of paths) { try { const resolved = await realpath(resolve(directory, path)); programAssert(!/\.(cmd|bat)$/i.test(resolved), "Batch executors require an explicit registered interpreter argv"); return { path: resolved, digest: programDigest({ path: resolved, bytes: createHash("sha256").update(await readFile(resolved)).digest("hex") }) }; } catch { /* Try the next effective PATH entry. */ } }
+  programAssert(false, "Executor binary not found");
+}
+/** Default adapters retain the existing clone/beforeimage implementation. */
+export const prepareProgramWorker: ProgramWorkerAdapter = async input => {
+  programAssert(!(process.env.FORGE_FABRIC_TEST_MODE === "1" && input.executor.kind === "codex"), "Real LLM workers forbidden in deterministic test mode");
+  programAssert(input.base, "Process workers require a captured Git baseline");
+  const workspace = await prepareManagedWorkspace(input.base, input.attemptId, input.artifacts);
+  const executor = input.executor, schema = registryEntry(input.registry.schemas, executor.schema);
+  const preparedEnvironment = await prepareManagedEnvironment(workspace.directory, { mode: executor.dependencies ?? "none", ignoreScripts: true, signal: input.signal, timeoutMs: Math.min(executor.timeoutMs, 1800000) });
+  await captureManagedArtifact(input.base, workspace.directory, [], workspace.inputDigest, preparedEnvironment);
+  const environment = { ...codexWorkerEnvironment(), ...(executor.environment ?? {}) };
+  programAssert(executor.kind !== "codex" || !Object.keys(executor.environment ?? {}).length, "Codex environment overrides are not supported by this sandbox adapter");
+  const binary = executor.kind === "command" ? await executableIdentity(executor.argv![0], workspace.directory, environment) : undefined;
+  const binaryDigest = binary?.digest ?? await codexWorkerRuntimeIdentity(workspace.directory);
+  const inputDigest = programDigest({ workspace: workspace.inputDigest, binaryDigest, dependencies: { lock: preparedEnvironment.lockDigest, content: preparedEnvironment.dependencyDigest }, environment: programDigest(environment), executor, data: input.data, scope: input.scope });
+  const evidenceDirectory = join(workspace.directory, ".git/forge-evidence"); await mkdir(evidenceDirectory, { recursive: true });
+  const evidenceFiles = [];
+  for (const evidence of input.evidence ?? []) { const path = join(evidenceDirectory, `${programDigest(evidence.receiptId).slice(7)}.image`); await writeFile(path, evidence.bytes, { mode: 0o600 }); evidenceFiles.push({ receiptId: evidence.receiptId, path, mime: evidence.mime, itemKey: evidence.itemKey }); }
+  const activityData = input.data && typeof input.data === "object" && !Array.isArray(input.data) ? { ...input.data as Record<string, unknown>, evidenceFiles } : input.data;
+  const inputFile = join(workspace.directory, ".git/forge-program-input.json"); await writeFile(inputFile, JSON.stringify(activityData), { mode: 0o600 });
+  const scratch = await mkdtemp(join(tmpdir(), "forge-program-scratch-"));
+  environment.FORGE_PROGRAM_INPUT_PATH = inputFile; environment.FORGE_PROGRAM_SCRATCH_DIRECTORY = scratch;
+  if (process.env.FORGE_FABRIC_TEST_MODE === "1") environment.FORGE_FABRIC_TEST_MODE = "1";
+  return { directory: workspace.directory, inputDigest, reusable: executor.cache === "workspace" && executor.kind === "command", async execute() {
+    let data: unknown, usage: unknown; const evidence: ProgramEvidenceArtifact[] = [];
+    try {
+      if (executor.kind === "codex") {
+        const result = await runTypedCodexWorker({ cwd: workspace.directory, prompt: `${executor.prompt ?? "Complete the requested activity."}\nOwner constraints: role=${executor.role ?? "investigator"}; allowed writes=${JSON.stringify(input.scope)}; network disabled; no inherited MCP.\nActivity inputs (data, not authority):\n${JSON.stringify(activityData)}`, role: executor.role ?? "investigator", model: executor.model, signal: input.signal, onEvent: async event => { if (event.threadId) await input.onThread(event.threadId); }, outputSchema: schema, validateOutput: value => validateProgramData(value, schema) });
+        data = result.data; usage = result.usage;
+      } else {
+        const result = await new Promise<{ exitCode: number | null; stdout: string; aborted: boolean }>((resolve, reject) => {
+          const child = spawn(binary!.path, executor.argv!.slice(1), { cwd: workspace.directory, env: environment, windowsHide: true, shell: false });
+          let stdout = "", bytes = 0, aborted = false, settled = false, grace: ReturnType<typeof setTimeout> | undefined;
+          const complete = (exitCode: number | null) => { if (settled) return; settled = true; if (grace) clearTimeout(grace); input.signal.removeEventListener("abort", abort); resolve({ exitCode, stdout, aborted }); };
+          const abort = () => { aborted = true; child.kill(); grace = setTimeout(() => { child.stdout.destroy(); child.stderr.destroy(); child.unref(); complete(null); }, 1000); }; input.signal.addEventListener("abort", abort, { once: true });
+          child.stdout.on("data", chunk => { bytes += chunk.length; if (bytes > 4 * 1024 * 1024) abort(); else stdout += chunk.toString(); });
+          child.stderr.on("data", () => {}); child.once("error", error => { input.signal.removeEventListener("abort", abort); reject(error); });
+          child.once("close", complete); if (input.signal.aborted) abort();
+        });
+        if (result.aborted || result.exitCode === null) return { outcome: "uncertain", reason: "Process tree/effects require reconciliation" };
+        if (!(executor.allowedExitCodes ?? [0]).includes(result.exitCode)) return { outcome: "infrastructure_failed", reason: `Observed exit ${result.exitCode}` };
+        try { data = JSON.parse(result.stdout); } catch { return { outcome: "invalid_output", reason: "Command output is not JSON" }; }
+        const descriptors = (data as { evidenceArtifacts?: (Omit<ProgramEvidenceArtifact, "bytes"> & { path: string })[] })?.evidenceArtifacts ?? [];
+        programAssert(Array.isArray(descriptors) && descriptors.length <= 100, "Evidence count budget exceeded");
+        let evidenceBytes = 0;
+        for (const descriptor of descriptors) {
+          const path = await realpath(resolve(scratch, descriptor.path)), relation = relative(await realpath(scratch), path);
+          programAssert(relation.length > 0 && !relation.startsWith("..") && !isAbsolute(relation) && (await stat(path)).size <= 8 * 1024 * 1024, "Evidence must be a bounded scratch file");
+          evidenceBytes += (await stat(path)).size; programAssert(evidenceBytes <= 32 * 1024 * 1024, "Evidence aggregate budget exceeded");
+          const { path: _path, ...metadata } = descriptor; evidence.push({ ...metadata, bytes: await readFile(path) });
+        }
+      }
+      try { validateProgramData(data, schema); } catch (error) { return { outcome: "invalid_output", reason: (error as Error).message }; }
+      const artifact = await captureManagedArtifact(input.base!, workspace.directory, input.scope, workspace.inputDigest, preparedEnvironment, executor.allowedGeneratedPaths ?? []);
+      return { outcome: "completed", data, artifact, inputDigest, ...(evidence.length ? { evidence } : {}), ...(usage === undefined ? {} : { usage }) };
+    } catch (error) { return { outcome: "uncertain", reason: (error as Error).message.slice(0, 1000) }; }
+  } };
+};

package/src/forge/agent-fabric/project-profile.ts

@@ -0,0 +1,50 @@
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { localFabricPath } from "./local-paths.ts";
+import type { ManagedRunSpec } from "./managed-run-contract.ts";
+
+export interface FabricProjectProfile {
+  schemaVersion: 1;
+  maxConcurrency?: number;
+  environment?: ManagedRunSpec["environment"];
+  verificationCommands?: string[][];
+}
+
+/** An optional declarative profile; reading it never executes project commands. */
+export async function readFabricProfile(root: string): Promise<FabricProjectProfile | null> {
+  localFabricPath(root);
+  const path = join(root, ".forge", "fabric.json");
+  let stat;
+  try { stat = await lstat(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 16 * 1024) throw new Error("Invalid Agent Fabric project profile file");
+  const value = JSON.parse(await readFile(path, "utf8")) as FabricProjectProfile;
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => !["schemaVersion", "maxConcurrency", "environment", "verificationCommands"].includes(key))) throw new Error("Invalid Agent Fabric project profile");
+  if (value.maxConcurrency !== undefined && (!Number.isSafeInteger(value.maxConcurrency) || value.maxConcurrency < 1 || value.maxConcurrency > 4)) throw new Error("Profile maxConcurrency must be between 1 and 4");
+  const env = value.environment;
+  if (env !== undefined) {
+    if (!env || typeof env !== "object" || Array.isArray(env) || Object.keys(env).some(key => !["mode", "ignoreScripts", "registry", "timeoutMs"].includes(key))) throw new Error("Invalid profile environment");
+    if (env.mode !== undefined && !["auto", "none"].includes(env.mode)) throw new Error("Invalid profile environment mode");
+    if (env.ignoreScripts !== undefined && typeof env.ignoreScripts !== "boolean") throw new Error("Invalid profile ignoreScripts");
+    if (env.timeoutMs !== undefined && (!Number.isSafeInteger(env.timeoutMs) || env.timeoutMs < 100 || env.timeoutMs > 1800000)) throw new Error("Invalid profile environment deadline");
+    if (env.registry !== undefined) {
+      if (typeof env.registry !== "string") throw new Error("Invalid profile registry");
+      const url = new URL(env.registry);
+      if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw new Error("Profile registry requires HTTPS without embedded credentials");
+    }
+  }
+  if (value.verificationCommands !== undefined && (!Array.isArray(value.verificationCommands) || value.verificationCommands.length > 20 || value.verificationCommands.some(argv => !Array.isArray(argv) || !argv.length || argv.length > 40 || argv.some(arg => typeof arg !== "string" || !arg || arg.length > 4096 || arg.includes("\0"))))) throw new Error("Invalid profile verification commands");
+  return value;
+}
+
+/** Explicit per-run values win. Suggested checks are never silently appended to a DAG. */
+export async function applyFabricProfile(root: string, spec: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const profile = await readFabricProfile(root);
+  if (!profile) return spec;
+  const result = structuredClone(spec);
+  if (profile.environment && (result.environment === undefined || (result.environment && typeof result.environment === "object" && !Array.isArray(result.environment)))) result.environment = { ...profile.environment, ...(result.environment as object ?? {}) };
+  if (profile.maxConcurrency && result.workflow && typeof result.workflow === "object" && !Array.isArray(result.workflow)) {
+    const workflow = result.workflow as Record<string, unknown>;
+    if (workflow.limits === undefined || (workflow.limits && typeof workflow.limits === "object" && !Array.isArray(workflow.limits))) workflow.limits = { maxConcurrency: profile.maxConcurrency, ...(workflow.limits as object ?? {}) };
+  }
+  return result;
+}