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

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

@@ -0,0 +1,283 @@
+import { createHash } from "node:crypto";
+import { stableStringify } from "./canonical.ts";
+import { programGraph } from "./program-structure.ts";
+import { validateVisualPopulation } from "./program-evidence.ts";
+import { validateProgramTypes } from "./program-types.ts";
+
+export type ProgramValue = null | boolean | number | string | ProgramValue[] | { [key: string]: ProgramValue };
+export interface ProgramRef { id: string; version: string }
+export interface ProgramExpr { $expr: string; args: unknown[] }
+export interface ProgramOperation { kind: string; id: string; options: Record<string, unknown> }
+export interface WorkflowProgramV2 {
+  operatorVersion?: 2;
+  mode?: "data" | "candidate";
+  schemaVersion: 2; id: string; version: number; inputSchema: ProgramRef; outputSchema: ProgramRef;
+  acceptance: ProgramRef; population?: ProgramRef; policy: ProgramRef; steps: ProgramOperation[]; result: unknown;
+}
+export type ProgramSchema = { type?: string | string[]; enum?: ProgramValue[]; const?: ProgramValue;
+  properties?: Record<string, ProgramSchema>; required?: string[]; additionalProperties?: boolean;
+  items?: ProgramSchema; minItems?: number; maxItems?: number; minLength?: number; maxLength?: number;
+  minimum?: number; maximum?: number; anyOf?: ProgramSchema[] };
+export interface ProgramLexicalContext { item?: ProgramSchema; state?: ProgramSchema }
+export interface ProgramExecutor {
+  id: string; version: string; kind: "command" | "codex"; effect: "read" | "isolated-write" | "idempotent-effect" | "non-idempotent-effect";
+  argv?: string[]; prompt?: string; role?: "implementer" | "reviewer" | "investigator" | "decision";
+  model?: string; timeoutMs: number; writeScope: string[]; allowedGeneratedPaths?: string[];
+  network: "disabled" | "host"; isolation: "cooperative" | "sandbox"; schema: ProgramRef;
+  allowedExitCodes?: number[]; environment?: Record<string, string>;
+  inputSchema?: ProgramRef;
+  dependencies?: "none" | "auto";
+  cache?: "none" | "workspace";
+}
+export interface ProgramPolicy {
+  allowFencedReplan?: boolean;
+  captureScope?: string[];
+  id: string; version: string; maxItems: number; concurrency: number; maxAttempts: number;
+  maxOperations: number; maxDepth: number; deadlineMs: number; maxOutputBytes: number;
+  writeScope: string[]; executors: string[]; allowCooperativeCommands: boolean; allowNetwork: boolean;
+}
+export interface ProgramAcceptance {
+  id: string; version: string; criteria: string[]; writeScope: string[];
+  requiredChecks: string[]; requireReview: boolean; allowNoWork: boolean;
+  requiredChecksByScope?: { item: string[]; final: string[] };
+  assessmentBindings?: Record<string, "item" | "final">;
+  obligations?: { id: string; scope: "item" | "final"; criteria: string[]; requiredEvidence?: string[] }[];
+  allowPartial?: boolean;
+  requireHumanApproval?: boolean;
+}
+export interface ProgramVisualCase { itemKey: string; route: string; viewport: string; state: string; width: number; height: number }
+export interface ProgramPopulation {
+  visualCases?: ProgramVisualCase[];
+  inventoryRoots?: string[]; extensions?: string[];
+  id: string; version: string; members: string[]; exclusions: { id: string; reason: string }[];
+  baselineDigest: string; evidence: string; allowNoWork: boolean;
+}
+export interface ProgramRegistry {
+  schemas: Record<string, ProgramSchema>; executors: Record<string, ProgramExecutor>;
+  policies: Record<string, ProgramPolicy>; acceptance: Record<string, ProgramAcceptance>;
+  populations: Record<string, ProgramPopulation>; programs?: Record<string, WorkflowProgramV2>;
+}
+export interface ProgramAssessment {
+  receiptId?: string; generation?: number; operationId?: string;
+  semanticDigest?: string; inputDigest?: string;
+  phase?: "item" | "final"; obligationIds?: string[]; satisfiedObligationIds?: string[]; unsatisfiedObligationIds?: string[];
+  environmentRef?: string; evidenceRefs?: string[]; contractDigest?: string;
+  candidateDigest: string; verdict: "approved" | "changes_requested" | "inconclusive";
+  findings: unknown[]; checks: { id: string; passed: boolean }[]; attemptIds: string[];
+}
+export interface ProgramCandidate {
+  candidateId: string; digest: string; baselineDigest: string; parents: string[];
+  deltas: string[]; producerAttempts: string[];
+}
+export type ProgramRepairResult =
+  | { status: "accepted"; acceptedCandidate: ProgramCandidate; assessment: ProgramAssessment }
+  | { status: "exhausted" | "stalled" | "uncertain" | "canceled"; lastCandidate: ProgramCandidate; reason: string };
+export interface ProgramAttempt {
+  attemptId: string; operationId: string; generation: number; inputDigest: string;
+  executorDigest: string; startedAt: string; completedAt?: string;
+  outcome: "running" | "completed" | "infrastructure_failed" | "invalid_output" | "uncertain" | "canceled_confirmed";
+  outputRef?: string; threadId?: string; reason?: string;
+  reservation?: { scopes: { id: string; limit: number }[]; status: "held" | "released"; ownerEpoch: string };
+  usage?: unknown;
+}
+export interface ProgramOperationRecord {
+  kind?: string;
+  retired?: boolean;
+  dependencies?: string[];
+  id: string; semanticDigest: string; inputDigest: string; generation: number;
+  status: "declared" | "ready" | "running" | "waiting" | "completed" | "skipped" | "needs-attention" | "uncertain";
+  outputRef?: string; attempts: string[]; reason?: string; reusedFromGeneration?: number;
+}
+export interface ProgramSignal {
+  id: string; target: string; generation: number; type: string; correlation: string;
+  payloadRef: string; authorization?: string; subjectDigest?: string; expiresAt?: string; status: "pending" | "consumed" | "pending-after-apply" | "stale";
+}
+export interface ProgramApplyIntent {
+  requestId: string; requestDigest: string;
+  id: string; candidateDigest: string; gateRef: string; semanticVersion: number;
+  programDigest: string; acceptanceDigest: string; policyDigest: string; populationDigest: string;
+  sealRefs: string[]; authorization: string; expectedDigest: string; changedFiles: string[];
+}
+export interface ProgramRunV2 {
+  schemaVersion: 2; runId: string; requestId: string; requestDigest: string;
+  program: WorkflowProgramV2; registry: ProgramRegistry; programDigest: string; registryDigest: string;
+  inputRef: string; baselineDigest: string; baseRef?: string; createdAt: string; deadlineAt: string;
+  version: number; semanticVersion: number; revision: number; planRevision: number;
+  status: "executing" | "waiting" | "paused" | "needs-attention" | "completed" | "acceptance-ready" | "applying" | "applied" | "apply-uncertain" | "canceled";
+  operations: Record<string, ProgramOperationRecord>; attempts: Record<string, ProgramAttempt>;
+  seals: Record<string, string>; signals: ProgramSignal[]; candidates: Record<string, ProgramCandidate>;
+  assessments: Record<string, ProgramAssessment>; coverageReceipts: Record<string, { populationDigest: string; baselineDigest: string; ids: string[]; status: string }>;
+  deltas: Record<string, { artifactRef: string; inputCandidateDigest: string; outputCandidateDigest: string; producerAttemptId: string }>;
+  waits: Record<string, { generation: number; deadlineAt?: string; signalId?: string; outputRef?: string }>;
+  repairs: Record<string, { semanticDigest: string; inputDigest: string; candidate: ProgramCandidate; rounds: number; assessments: number; infrastructure: number; unchanged: number; repeated: number; priorFindings: string; feedback: unknown; phase: "implement" | "implementation-active" | "assess" | "assessment-active" | "decide" | "accepted" | "exhausted" | "stalled"; assessment?: ProgramAssessment }>;
+  collections: Record<string, { seal: string; coverageReceiptId: string | null; generation: number; ids: string[]; acceptedAssessmentIds: string[]; acceptedCandidateIds: string[]; obligationsSatisfied: boolean }>;
+  resultRef?: string; gateRef?: string; intent?: ProgramApplyIntent; receiptRef?: string;
+  acceptedCandidate?: ProgramCandidate;
+  scopeResults?: Record<string, { outcomes: { id: string; status: string; reason?: string }[]; status: "completed" | "waiting" | "failed"; resultRef?: string }>;
+  artifactRecords?: Record<string, ProgramCaptureReceipt>;
+  queue?: { id: string; generation: number; at: string }[];
+  totalAttempts: number; reason?: string;
+}
+export interface ProgramAssessmentContext {
+  visualCases?: ProgramVisualCase[];
+  runId: string; invocationId: string; assessmentId: string; phase: "item" | "final";
+  candidateRef: ProgramCandidate; obligationIds: string[]; itemKey?: string;
+  environmentRef: string; evidenceRefs: string[]; input: unknown;
+}
+export type ProgramCollectionItem = { key: string; outcome: "completed"; value: unknown } | { key: string; outcome: "failed" | "waiting"; reason?: string };
+export interface ProgramCollectionResult {
+  items: ProgramCollectionItem[]; results: unknown[]; failures: { id: string; reason: string }[];
+  seal: string; coverage: unknown; status: "completed" | "partial" | "no-work";
+}
+export interface ProgramCaptureReceipt {
+  receiptId: string; artifactRef: string; candidateDigest: string; environmentRef: string;
+  itemKey: string; buildDigest: string; mime: string; width: number; height: number;
+  route: string; viewport: string; state: string; producerAttemptId: string;
+}
+export class ProgramError extends Error {
+  constructor(readonly code: string, message: string) { super(message); this.name = "ProgramError"; }
+}
+export function programAssert(condition: unknown, message: string, code = "AF_PROGRAM_INVALID"): asserts condition {
+  if (!condition) throw new ProgramError(code, message);
+}
+export function programDigest(value: unknown): string {
+  return `sha256:${createHash("sha256").update(stableStringify(value)).digest("hex")}`;
+}
+/** Count before cloning/expanding; serialization is not a memory guard. */
+export function programValueBytes(value: unknown, maxBytes: number, maxItems = 10000): number {
+  let bytes = 0, nodes = 0;
+  const walk = (entry: unknown, depth: number): void => {
+    programAssert(depth <= 40 && ++nodes <= 1000000, "Value nesting/node budget exceeded");
+    if (typeof entry === "string") bytes += Buffer.byteLength(entry) + 2;
+    else if (entry === null || typeof entry === "number" || typeof entry === "boolean") bytes += 24;
+    else if (Array.isArray(entry)) { programAssert(entry.length <= maxItems, "Value item budget exceeded"); bytes += 2; for (const item of entry) walk(item, depth + 1); }
+    else if (entry && typeof entry === "object") { bytes += 2; for (const [key, child] of Object.entries(entry)) { bytes += Buffer.byteLength(key) + 4; walk(child, depth + 1); } }
+    else programAssert(false, "Non-data value rejected");
+    programAssert(bytes <= maxBytes, "Value byte budget exceeded");
+  };
+  walk(value, 0); return bytes;
+}
+export function refKey(ref: ProgramRef): string {
+  programAssert(ref && typeof ref.id === "string" && typeof ref.version === "string", "Versioned reference required");
+  return `${ref.id}@${ref.version}`;
+}
+export function registryEntry<T>(entries: Record<string, T>, ref: ProgramRef): T {
+  const key = refKey(ref); programAssert(Object.hasOwn(entries, key), `Unregistered reference ${key}`); return entries[key];
+}
+export function validateProgramData(value: unknown, schema: ProgramSchema, depth = 0): void {
+  programAssert(depth <= 32, "Schema/data depth exceeded");
+  if (schema.anyOf) {
+    programAssert(schema.anyOf.some(option => { try { validateProgramData(value, option, depth + 1); return true; } catch { return false; } }), "No schema alternative matched");
+  }
+  const type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  if (schema.type) programAssert((Array.isArray(schema.type) ? schema.type : [schema.type]).some(expected => expected === type || expected === "integer" && typeof value === "number" && Number.isSafeInteger(value)), `Expected ${schema.type}, got ${type}`);
+  if (schema.enum) programAssert(schema.enum.some(entry => programDigest(entry) === programDigest(value)), "Value outside enum");
+  if (Object.hasOwn(schema, "const")) programAssert(programDigest(value) === programDigest(schema.const), "Const mismatch");
+  if (typeof value === "number") programAssert(Number.isFinite(value) && (schema.minimum === undefined || value >= schema.minimum) && (schema.maximum === undefined || value <= schema.maximum), "Number outside bounds");
+  if (typeof value === "string") programAssert((schema.minLength === undefined || value.length >= schema.minLength) && (schema.maxLength === undefined || value.length <= schema.maxLength), "String outside bounds");
+  if (Array.isArray(value)) {
+    programAssert((schema.minItems === undefined || value.length >= schema.minItems) && (schema.maxItems === undefined || value.length <= schema.maxItems), "Array outside bounds");
+    if (schema.items) for (const entry of value) validateProgramData(entry, schema.items, depth + 1);
+  } else if (value && typeof value === "object") {
+    const data = value as Record<string, unknown>;
+    for (const key of schema.required ?? []) programAssert(Object.hasOwn(data, key), `Missing field ${key}`);
+    for (const [key, entry] of Object.entries(data)) {
+      if (schema.properties && Object.hasOwn(schema.properties, key)) validateProgramData(entry, schema.properties[key], depth + 1);
+      else programAssert(schema.additionalProperties !== false, `Unexpected field ${key}`);
+    }
+  }
+}
+export function programPath(path: string): void {
+  programAssert(typeof path === "string" && path.length > 0 && path.length < 2048 && !path.includes("\\") && !path.includes("\0") && !path.startsWith("/") && !path.includes(":") && path.split("/").every(part => part !== ".." && part !== "." && part !== ""), "Invalid relative path");
+  programAssert(path !== ".git" && !path.startsWith(".git/") && !path.startsWith(".forge/local/"), "Protected path");
+}
+export function programWithin(path: string, scope: string[]): boolean { return scope.some(prefix => path === prefix || path.startsWith(`${prefix}/`)); }
+export function validateWorkflowProgram(program: WorkflowProgramV2, registry: ProgramRegistry, ancestry: Set<string> = new Set(), lexical: ProgramLexicalContext = {}): void {
+  programAssert(program?.schemaVersion === 2 && typeof program.id === "string" && program.id.length > 0 && Number.isSafeInteger(program.version) && program.version > 0, "Program v2 required");
+  programAssert(program.operatorVersion === undefined || program.operatorVersion === 2, "Unsupported operator version");
+  programAssert(program.mode === undefined || ["data", "candidate"].includes(program.mode), "Invalid workflow mode");
+  programValueBytes(program, 4 * 1024 * 1024); programValueBytes(registry, 4 * 1024 * 1024);
+  const identity = programDigest(program); programAssert(!ancestry.has(identity), "Recursive subworkflow cycle"); ancestry = new Set([...ancestry, identity]); programAssert(ancestry.size <= 32, "Subworkflow depth exceeded");
+  const schemaKeys = new Set(["type", "enum", "const", "properties", "required", "additionalProperties", "items", "minItems", "maxItems", "minLength", "maxLength", "minimum", "maximum", "anyOf"]);
+  function validateSchema(schema: ProgramSchema, depth: number): void {
+    programAssert(schema && typeof schema === "object" && !Array.isArray(schema) && depth <= 32 && Object.keys(schema).every(key => schemaKeys.has(key)), "Unsupported/invalid schema keyword");
+    if (schema.type) programAssert((Array.isArray(schema.type) ? schema.type : [schema.type]).every(type => ["object", "array", "string", "number", "integer", "boolean", "null"].includes(type)), "Unsupported schema type");
+    if (schema.properties) for (const child of Object.values(schema.properties)) validateSchema(child, depth + 1);
+    if (schema.items) validateSchema(schema.items, depth + 1);
+    if (schema.anyOf) { programAssert(Array.isArray(schema.anyOf) && schema.anyOf.length > 0 && schema.anyOf.length <= 32, "Invalid schema alternatives"); for (const child of schema.anyOf) validateSchema(child, depth + 1); }
+    if (schema.required) programAssert(Array.isArray(schema.required) && schema.required.every(key => typeof key === "string"), "Invalid required fields");
+  }
+  for (const schema of Object.values(registry.schemas)) validateSchema(schema, 0);
+  registryEntry(registry.schemas, program.inputSchema); registryEntry(registry.schemas, program.outputSchema);
+  const policy = registryEntry(registry.policies, program.policy), acceptance = registryEntry(registry.acceptance, program.acceptance);
+  for (const field of ["maxItems", "concurrency", "maxAttempts", "maxOperations", "maxDepth", "deadlineMs", "maxOutputBytes"] as const) programAssert(Number.isSafeInteger(policy[field]) && policy[field] > 0, `Invalid limit ${field}`);
+  programAssert(policy.concurrency <= 32 && policy.maxDepth <= 32 && policy.maxItems <= 10000 && policy.maxAttempts <= 10000 && policy.maxOperations <= 20000 && policy.maxOutputBytes <= 4 * 1024 * 1024, "Physical limits exceeded");
+  for (const path of [...policy.writeScope, ...acceptance.writeScope, ...(policy.captureScope ?? [])]) programPath(path);
+  programAssert(acceptance.criteria.length > 0 && new Set(acceptance.criteria).size === acceptance.criteria.length, "Acceptance criteria required and unique");
+  if (program.population) { const population = registryEntry(registry.populations, program.population); programAssert(population.members.length <= policy.maxItems && new Set(population.members).size === population.members.length && population.evidence.length > 0, "Population inventory invalid"); validateVisualPopulation(population); }
+  const kinds = new Set(["agent", "command", "map", "branch", "loop", "compose", "gate", "repair", "subworkflow", "waitEvent", "value"]);
+  const expressions: Record<string, [number, number]> = { workflowInput: [0, 0], item: [0, 0], loopState: [0, 0], output: [1, 1], field: [2, 2], literal: [1, 1], object: [1, 1], array: [0, 10000], eq: [2, 2], and: [1, 100], or: [1, 100], not: [1, 1], concat: [1, 100], filter: [3, 3], unique: [2, 2], sort: [2, 2], take: [2, 2], length: [1, 1], population: [0, 0], acceptance: [0, 0], acceptedCandidate: [1, 1], acceptedCandidates: [1, 1], outputCandidate: [1, 1], candidateFromBaseline: [0, 1], coverageFor: [2, 2], coverageReceipt: [1, 1], acceptanceWriteScope: [1, 1], approvedChecksFor: [1, 1], acceptanceChecks: [1, 1] };
+  function inspect(value: unknown, resolve: (id: string) => string | undefined, dependencies: Set<string>, depth = 0): void {
+    programAssert(depth <= 32, "Expression nesting exceeded");
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) { for (const entry of value) inspect(entry, resolve, dependencies, depth + 1); return; }
+    const object = value as Record<string, unknown>;
+    if (Object.hasOwn(object, "$expr")) {
+      const expression = object as unknown as ProgramExpr, limits = expressions[expression.$expr];
+      programAssert(limits && Array.isArray(expression.args) && expression.args.length >= limits[0] && expression.args.length <= limits[1] && Object.keys(object).every(key => key === "$expr" || key === "args"), "Unknown expression/arity");
+      if (["output", "acceptedCandidate", "acceptedCandidates", "outputCandidate", "coverageReceipt"].includes(expression.$expr)) { const target = resolve(String(expression.args[0])); programAssert(target, `Unknown output ${expression.args[0]}`); dependencies.add(target); }
+      if (expression.$expr !== "literal") for (const arg of expression.args) inspect(arg, resolve, dependencies, depth + 1); return;
+    }
+    for (const entry of Object.values(object)) inspect(entry, resolve, dependencies, depth + 1);
+  }
+  const options: Record<string, string[]> = {
+    value: ["value"], agent: ["executor", "input", "candidate", "writeScope"], command: ["executor", "input", "candidate", "writeScope"],
+    map: ["items", "key", "coverage", "concurrency", "completion", "quorum", "body", "order"],
+    branch: ["condition", "then", "else"], loop: ["initialState", "maxRounds", "body", "next", "until"],
+    repair: ["recipe", "entryMode", "initialCandidate", "writeScope", "implement", "review", "checks", "input", "assessmentScope", "evidence", "maxRepairRounds", "maxAssessmentAttempts", "maxInfrastructureAttempts", "progressPolicy"],
+    compose: ["candidates", "onConflict"], gate: ["candidate", "coverage", "authorization"], subworkflow: ["program", "input"],
+    waitEvent: ["schema", "type", "correlation", "subject", "timeoutMs"], sequence: ["steps", "result"], parallel: ["steps", "result", "onFailure"],
+  };
+  kinds.add("sequence"); kinds.add("parallel");
+  const entries = programGraph(program);
+  programAssert(entries.length <= policy.maxOperations, "Template limit exceeded");
+  for (const entry of entries) {
+    const step = entry.step;
+    programAssert(step && kinds.has(step.kind) && /^[A-Za-z][A-Za-z0-9_-]{0,79}$/.test(step.id) && step.options && typeof step.options === "object", "Invalid operation");
+    programAssert(Object.keys(step.options).every(key => [...options[step.kind], "after", "label"].includes(key)), `Unknown ${step.kind} option`);
+    programAssert(entries.filter(other => other.id === entry.id).length === 1, "Duplicate operation ID");
+    inspect(Object.fromEntries(Object.entries(step.options).filter(([key]) => !["body", "steps", "result", "then", "else", "next", "until"].includes(key))), id => id, new Set());
+    programAssert(entry.id.split("/").length <= policy.maxDepth * 3 + 1, "Template depth exceeded");
+    if (step.kind === "map") {
+      programAssert(["all-required", "partial", "quorum"].includes(String(step.options.completion)), "Explicit map completion required");
+      programAssert(step.options.order === undefined || ["key", "input"].includes(String(step.options.order)), "Invalid map order");
+      if (step.options.completion !== "all-required") programAssert(acceptance.allowPartial, "Partial/quorum requires owner acceptance permission");
+      if (step.options.completion === "quorum") programAssert(step.options.quorum && typeof step.options.quorum === "object" && Number.isSafeInteger((step.options.quorum as { minAccepted: number }).minAccepted) && (step.options.quorum as { minAccepted: number }).minAccepted > 0, "Quorum minAccepted required");
+      else programAssert(step.options.quorum === undefined, "Quorum only applies to quorum completion");
+    }
+    if (["agent", "command"].includes(step.kind)) { const executor = registryEntry(registry.executors, step.options.executor as ProgramRef); if (executor.inputSchema) registryEntry(registry.schemas, executor.inputSchema); }
+    if (step.kind === "repair") {
+      registryEntry(registry.executors, step.options.implement as ProgramRef); registryEntry(registry.executors, step.options.review as ProgramRef);
+      programAssert(["implement-first", "assess-first"].includes(String(step.options.entryMode)), "Repair entryMode required");
+      programAssert((step.options.recipe as ProgramRef)?.id === "repair" && (step.options.recipe as ProgramRef)?.version === "v2", "Unsupported repair recipe");
+      const phase = step.options.assessmentScope as "item" | "final" | undefined;
+      programAssert(phase === undefined || phase === "item" || phase === "final", "Invalid assessment scope");
+      if (acceptance.requiredChecksByScope) {
+        programAssert(phase && acceptance.assessmentBindings?.[step.id] === phase, "Assessment scope must match owner operation binding");
+        if (phase === "item") programAssert(lexical.item || entries.some(ancestor => ancestor.step.kind === "map" && entry.id.startsWith(`${ancestor.id}/body/`)), "Item assessment requires a map context");
+      }
+      const required = phase && acceptance.requiredChecksByScope ? acceptance.requiredChecksByScope[phase] : acceptance.requiredChecks;
+      programAssert(Array.isArray(step.options.checks) && required.every(check => (step.options.checks as unknown[]).includes(check)), "Repair cannot omit required checks");
+      for (const ref of (step.options.evidence ?? []) as ProgramRef[]) programAssert(registryEntry(registry.executors, ref).effect === "read", "Evidence executor must be readonly");
+    }
+    if (step.kind === "parallel") programAssert(["collect-all", "cancel-siblings"].includes(String(step.options.onFailure)), "Parallel failure policy required");
+    if (step.kind === "compose") programAssert(step.options.onConflict === undefined || step.options.onConflict === "needs-resolution", "Unsupported conflict policy");
+    if (step.kind === "waitEvent") registryEntry(registry.schemas, step.options.schema as ProgramRef);
+    if (step.kind === "subworkflow") { const child = registryEntry(registry.programs ?? {}, step.options.program as ProgramRef); programAssert(programDigest(child.policy) === programDigest(program.policy) && programDigest(child.acceptance) === programDigest(program.acceptance), "Child cannot replace inherited policy/acceptance"); programAssert(!child.population || program.population && programDigest(child.population) === programDigest(program.population), "Child cannot replace inherited population"); validateWorkflowProgram(child, registry, ancestry, { ...lexical, ...(entries.some(ancestor => ancestor.step.kind === "map" && entry.id.startsWith(`${ancestor.id}/body/`)) ? { item: {} } : {}), ...(entries.some(ancestor => ancestor.step.kind === "loop" && entry.id.startsWith(`${ancestor.id}/body/`)) ? { state: {} } : {}) }); }
+  }
+  programAssert(Object.hasOwn(program, "result"), "Explicit program result required");
+  inspect(program.result, id => program.steps.some(step => step.id === id) ? id : undefined, new Set());
+  if (acceptance.requiredChecksByScope) programAssert(acceptance.obligations?.length && new Set(acceptance.obligations.map(obligation => obligation.id)).size === acceptance.obligations.length, "Scoped acceptance requires unique owner obligations");
+  validateProgramTypes(program, registry, lexical);
+  programDigest(program); programDigest(registry);
+}

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

@@ -0,0 +1,126 @@
+import type { WorkflowRef, WorkflowOptions, WorkflowOperation, WorkflowDefinition, WorkflowExpression, WorkflowValue, WorkflowResolved, WorkflowActivityOptions, WorkflowBody, WorkflowCollection } from "./program-api.ts";
+export type { WorkflowRef, WorkflowOptions, WorkflowOperation, WorkflowDefinition, WorkflowExpression, WorkflowValue, WorkflowResolved, WorkflowActivityOptions, WorkflowBody, WorkflowCollection } from "./program-api.ts";
+import ts from "typescript";
+import { programAssert, programValueBytes, type ProgramExpr, type ProgramOperation, type WorkflowProgramV2 } from "./program-contract.ts";
+
+export const PROGRAM_DSL_VERSION = "forge-workflow-dsl/2";
+export const expressionNames = ["workflowInput", "item", "loopState", "output", "field", "literal", "object", "array", "eq", "and", "or", "not", "concat", "filter", "unique", "sort", "take", "length", "population", "acceptance", "acceptedCandidate", "acceptedCandidates", "outputCandidate", "candidateFromBaseline", "coverageFor", "coverageReceipt", "acceptanceWriteScope", "approvedChecksFor", "acceptanceChecks"];
+export const referenceNames = ["schemaRef", "executorRef", "policyRef", "acceptanceRef", "populationRef", "recipeRef", "programRef"];
+export const operationNames = ["agent", "command", "map", "branch", "loop", "compose", "gate", "repair", "subworkflow", "waitEvent", "value", "sequence", "parallel"];
+export function workflowExpression(name: string, ...args: unknown[]): ProgramExpr { return { $expr: name, args }; }
+export function workflowOperation(kind: string, id: string, options: Record<string, unknown>): ProgramOperation { return { kind, id, options }; }
+export function schemaRef<T = unknown>(id: string, version: string): WorkflowRef<"schema", unknown, T> { return { id, version } as WorkflowRef<"schema", unknown, T>; }
+export const executorRef = <Input = unknown, Output = unknown>(id: string, version: string) => ({ id, version } as WorkflowRef<"executor", Input, Output>);
+export const policyRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"policy">);
+export const acceptanceRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"acceptance">);
+export const populationRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"population">);
+export const recipeRef = (id: string, version: string) => ({ id, version } as WorkflowRef<"recipe">);
+export const programRef = <Input = unknown, Output = unknown>(id: string, version: string) => ({ id, version } as WorkflowRef<"program", Input, Output>);
+export const workflowInput = <T = unknown>() => workflowExpression("workflowInput") as WorkflowExpression<T>;
+export const item = <T = unknown>() => workflowExpression("item") as WorkflowExpression<T>;
+export const loopState = <T = unknown>() => workflowExpression("loopState") as WorkflowExpression<T>;
+export function output<T>(operation: WorkflowOperation<keyof WorkflowOptions, T>): WorkflowExpression<T>;
+export function output(id: string): WorkflowExpression;
+export function output(operation: string | WorkflowOperation): WorkflowExpression { return workflowExpression("output", typeof operation === "string" ? operation : operation.id); }
+export function field<T, K extends (unknown extends T ? string : keyof T & string)>(value: WorkflowExpression<T>, key: K): WorkflowExpression<unknown extends T ? unknown : T[K & keyof T]>;
+export function field<T, K extends keyof T & string>(value: T, key: K): WorkflowExpression<T[K]>;
+export function field(value: unknown, key: string): WorkflowExpression { return workflowExpression("field", value, key); }
+export const literal = <T>(value: T) => workflowExpression("literal", value) as WorkflowExpression<T>;
+export const object = <T extends Record<string, unknown>>(value: T) => workflowExpression("object", value) as WorkflowExpression<WorkflowResolved<T>>;
+export const array = <T extends unknown[]>(...values: T) => workflowExpression("array", ...values) as WorkflowExpression<WorkflowResolved<T>>;
+export const eq = (left: unknown, right: unknown) => workflowExpression("eq", left, right);
+export const and = (...values: unknown[]) => workflowExpression("and", ...values);
+export const or = (...values: unknown[]) => workflowExpression("or", ...values);
+export const not = (value: unknown) => workflowExpression("not", value);
+export const concat = (...values: unknown[]) => workflowExpression("concat", ...values);
+export const filter = (values: unknown, key: string, equals: unknown) => workflowExpression("filter", values, key, equals);
+export const unique = (values: unknown, key: string) => workflowExpression("unique", values, key);
+export const sort = (values: unknown, key: string) => workflowExpression("sort", values, key);
+export const take = (values: unknown, count: number) => workflowExpression("take", values, count);
+export const length = (value: unknown) => workflowExpression("length", value);
+export const population = () => workflowExpression("population");
+export const acceptance = () => workflowExpression("acceptance");
+export const acceptedCandidate = (id: string) => workflowExpression("acceptedCandidate", id);
+export const acceptedCandidates = (id: string) => workflowExpression("acceptedCandidates", id);
+export const outputCandidate = (id: string) => workflowExpression("outputCandidate", id);
+export const candidateFromBaseline = (entry?: unknown) => entry === undefined ? workflowExpression("candidateFromBaseline") : workflowExpression("candidateFromBaseline", entry);
+export const coverageFor = (contract: unknown, discovered: unknown) => workflowExpression("coverageFor", contract, discovered);
+export const coverageReceipt = (id: string) => workflowExpression("coverageReceipt", id);
+export const acceptanceWriteScope = (id: string) => workflowExpression("acceptanceWriteScope", id);
+export const approvedChecksFor = (entry: unknown) => workflowExpression("approvedChecksFor", entry);
+export const acceptanceChecks = (id: string) => workflowExpression("acceptanceChecks", id);
+export const agent = <Input = unknown, Output = unknown>(id: string, options: WorkflowActivityOptions<Input, Output>) => workflowOperation("agent", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"agent", Output>;
+export const command = <Input = unknown, Output = unknown>(id: string, options: WorkflowActivityOptions<Input, Output>) => workflowOperation("command", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"command", Output>;
+export const map = <T = unknown>(id: string, options: Omit<WorkflowOptions["map"], "body"> & { body: WorkflowBody<T> }) => workflowOperation("map", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"map", WorkflowCollection<T>>;
+export const branch = (id: string, options: WorkflowOptions["branch"]) => workflowOperation("branch", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"branch">;
+export const loop = (id: string, options: WorkflowOptions["loop"]) => workflowOperation("loop", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"loop">;
+export const compose = (id: string, options: WorkflowOptions["compose"]) => workflowOperation("compose", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"compose">;
+export const gate = (id: string, options: WorkflowOptions["gate"]) => workflowOperation("gate", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"gate">;
+export const repair = (id: string, options: WorkflowOptions["repair"]) => workflowOperation("repair", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"repair">;
+export const subworkflow = <Input = unknown, Output = unknown>(id: string, options: Omit<WorkflowOptions["subworkflow"], "program" | "input"> & { program: WorkflowRef<"program", Input, Output>; input: WorkflowValue<NoInfer<Input>> }) => workflowOperation("subworkflow", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"subworkflow", Output>;
+export const waitEvent = <T = unknown>(id: string, options: Omit<WorkflowOptions["waitEvent"], "schema"> & { schema: WorkflowRef<"schema", unknown, T> }) => workflowOperation("waitEvent", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"waitEvent", T>;
+export const value = <T>(id: string, options: Omit<WorkflowOptions["value"], "value"> & { value: T }) => workflowOperation("value", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"value", WorkflowResolved<T>>;
+export function defineWorkflow(program: WorkflowDefinition): WorkflowProgramV2 { return { schemaVersion: 2, operatorVersion: 2, ...program }; }
+
+/** Parse a finite AST. Never transpile, import, evaluate, or call authored JavaScript. */
+export const sequence = (id: string, options: WorkflowOptions["sequence"]) => workflowOperation("sequence", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"sequence">;
+export const parallel = (id: string, options: WorkflowOptions["parallel"]) => workflowOperation("parallel", id, options as unknown as Record<string, unknown>) as WorkflowOperation<"parallel">;
+export function lowerWorkflowSource(source: string): WorkflowProgramV2 {
+  programAssert(Buffer.byteLength(source) <= 256 * 1024, "DSL source too large");
+  const file = ts.createSourceFile("workflow.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  programAssert((file as ts.SourceFile & { parseDiagnostics: readonly ts.Diagnostic[] }).parseDiagnostics.length === 0, "Malformed workflow source");
+  const bindings = new Map<string, unknown>(), imports = new Map<string, string>(); let program: WorkflowProgramV2 | undefined, nodes = 0, bindingBytes = 0;
+  function evaluateList(entries: readonly ts.Expression[], depth: number): unknown[] { let bytes = 0; const values: unknown[] = []; for (const entry of entries) { const value = evaluate(entry, depth); bytes += programValueBytes(value, 4 * 1024 * 1024); programAssert(bytes <= 4 * 1024 * 1024, "DSL expansion byte budget exceeded"); values.push(value); } return values; }
+  function evaluate(node: ts.Expression, depth = 0): unknown {
+    programAssert(++nodes <= 100000 && depth <= 32, "DSL AST budget exceeded");
+    const next = (expression: ts.Expression) => evaluate(expression, depth + 1);
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    if (ts.isNumericLiteral(node)) return Number(node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) return -Number(node.operand.text);
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return next(node.expression);
+    if (ts.isIdentifier(node)) { programAssert(bindings.has(node.text), `Unknown binding ${node.text}`); programValueBytes(bindings.get(node.text), 4 * 1024 * 1024); return structuredClone(bindings.get(node.text)); }
+    if (ts.isArrayLiteralExpression(node)) { programAssert(node.elements.every(element => !ts.isSpreadElement(element)), "Spread forbidden"); return evaluateList(node.elements, depth + 1); }
+    if (ts.isObjectLiteralExpression(node)) {
+      const object: Record<string, unknown> = Object.create(null), explicit = new Set<string>(); let bytes = 0;
+      for (const property of node.properties) {
+        if (ts.isSpreadAssignment(property)) {
+          programAssert(ts.isIdentifier(property.expression) && bindings.has(property.expression.text), "Only finite const data object spreads allowed");
+          const spread = bindings.get(property.expression.text); programAssert(spread && typeof spread === "object" && !Array.isArray(spread) && !Object.hasOwn(spread, "$expr"), "Object spread requires const data");
+          bytes += programValueBytes(spread, 4 * 1024 * 1024); programAssert(bytes <= 4 * 1024 * 1024, "DSL expansion byte budget exceeded"); Object.assign(object, structuredClone(spread)); continue;
+        }
+        programAssert(ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)), "Only literal data properties allowed");
+        const key = property.name.text; programAssert(!explicit.has(key) && !["__proto__", "prototype", "constructor"].includes(key), "Duplicate/protected DSL key"); explicit.add(key); const value = next(property.initializer); bytes += Buffer.byteLength(key) + programValueBytes(value, 4 * 1024 * 1024); programAssert(bytes <= 4 * 1024 * 1024, "DSL expansion byte budget exceeded"); object[key] = value;
+      }
+      return object;
+    }
+    if (ts.isCallExpression(node)) {
+      programAssert(ts.isIdentifier(node.expression), "Only DSL constructors allowed");
+      const name = imports.get(node.expression.text); programAssert(name, `Unimported constructor ${node.expression.text}`);
+      const args = evaluateList(node.arguments, depth + 1);
+      if (expressionNames.includes(name)) { if (name === "output" && args[0] && typeof args[0] === "object" && "kind" in args[0]) args[0] = (args[0] as ProgramOperation).id; return { $expr: name, args }; }
+      if (referenceNames.includes(name)) { programAssert(args.length === 2 && args.every(arg => typeof arg === "string"), "Versioned registry reference required"); return { id: args[0], version: args[1] }; }
+      if (operationNames.includes(name)) { programAssert(args.length === 2 && typeof args[0] === "string" && args[1] && typeof args[1] === "object", "Operation ID and options required"); return { kind: name, id: args[0], options: args[1] }; }
+      programAssert(name === "defineWorkflow" && args.length === 1 && args[0] && typeof args[0] === "object", "Invalid workflow constructor"); return { schemaVersion: 2, operatorVersion: 2, ...args[0] };
+    }
+    programAssert(false, `Unsupported authored syntax ${ts.SyntaxKind[node.kind]}`);
+  }
+  for (const statement of file.statements) {
+    if (ts.isImportDeclaration(statement)) {
+      programAssert(ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "forgeos/agent-fabric/workflows" && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings), "Only versioned Forge DSL named imports allowed");
+      for (const element of statement.importClause.namedBindings.elements) {
+        const name = element.propertyName?.text ?? element.name.text;
+        if (statement.importClause.isTypeOnly || element.isTypeOnly) { programAssert(["WorkflowOptions", "WorkflowRef", "WorkflowOperation", "WorkflowDefinition", "WorkflowExpression", "WorkflowValue", "WorkflowResolved", "WorkflowActivityOptions", "WorkflowBody", "WorkflowCollection"].includes(name), "Unknown DSL author type"); continue; }
+        programAssert(["defineWorkflow", ...expressionNames, ...referenceNames, ...operationNames].includes(name) && !imports.has(element.name.text), "Unknown/duplicate DSL import"); imports.set(element.name.text, name);
+      }
+    } else if (ts.isVariableStatement(statement)) {
+      programAssert((statement.declarationList.flags & ts.NodeFlags.Const) !== 0, "Only const bindings allowed");
+      for (const declaration of statement.declarationList.declarations) { programAssert(ts.isIdentifier(declaration.name) && declaration.initializer && !bindings.has(declaration.name.text) && !imports.has(declaration.name.text), "Invalid const declaration"); const value = evaluate(declaration.initializer); bindingBytes += programValueBytes(value, 4 * 1024 * 1024); programAssert(bindingBytes <= 4 * 1024 * 1024, "DSL cumulative binding budget exceeded"); bindings.set(declaration.name.text, value); }
+    } else if (ts.isExportAssignment(statement)) {
+      programAssert(!program && !statement.isExportEquals, "Only one export default workflow allowed"); program = evaluate(statement.expression) as WorkflowProgramV2;
+    } else programAssert(false, "Only DSL imports, const data bindings, and export default allowed");
+  }
+  programAssert(program?.schemaVersion === 2, "export default defineWorkflow required"); programValueBytes(program, 4 * 1024 * 1024); return program;
+}

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

@@ -0,0 +1,22 @@
+import { programAssert, programDigest, type ProgramAcceptance, type ProgramCaptureReceipt, type ProgramPopulation, type ProgramVisualCase } from "./program-contract.ts";
+import { canonicalItemKey } from "./program-structure.ts";
+
+export function validateVisualPopulation(population: ProgramPopulation): void {
+  if (!population.visualCases) return;
+  const keys = population.members.map(canonicalItemKey), cases = population.visualCases;
+  programAssert(cases.length === keys.length && new Set(cases.map(entry => canonicalItemKey(entry.itemKey))).size === keys.length && cases.every(entry => keys.includes(canonicalItemKey(entry.itemKey))), "Visual cases must cover exactly owner population");
+  const tuples = cases.map(entry => programDigest([entry.route, entry.viewport, entry.state]));
+  programAssert(new Set(tuples).size === tuples.length, "Duplicate visual route/viewport/state case");
+  for (const entry of cases) programAssert([entry.route, entry.viewport, entry.state].every(value => typeof value === "string" && value.length > 0 && value.length <= 2048) && [entry.width, entry.height].every(value => Number.isSafeInteger(value) && value > 0 && value <= 16384) && entry.width * entry.height <= 64 * 1024 * 1024, "Invalid expected visual case");
+}
+export function captureKeys(acceptance: ProgramAcceptance, phase: "item" | "final", members: string[], itemKey?: string): string[] {
+  const required = (acceptance.obligations ?? []).some(obligation => (phase === "final" || obligation.scope === "item") && obligation.requiredEvidence?.includes("capture"));
+  if (!required) return [];
+  programAssert(members.length > 0 && (phase !== "item" || itemKey && members.includes(itemKey)), "Capture obligations require an owner population");
+  return phase === "item" ? [itemKey!] : members;
+}
+export function validateVisualCapture(capture: Pick<ProgramCaptureReceipt, "itemKey" | "route" | "viewport" | "state" | "width" | "height">, cases?: ProgramVisualCase[]): void {
+  if (!cases) return;
+  const expected = cases.find(entry => canonicalItemKey(entry.itemKey) === canonicalItemKey(capture.itemKey));
+  programAssert(expected && ["route", "viewport", "state", "width", "height"].every(key => expected[key as keyof ProgramVisualCase] === capture[key as keyof typeof capture]), "Capture does not match owner visual case");
+}

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

@@ -0,0 +1,15 @@
+import { programAssert } from "./program-contract.ts";
+
+/** Bounded image header validation. Pixel decoding/render acceptance belongs to the registered checker. */
+export function programImage(bytes: Uint8Array): { mime: string; width: number; height: number } {
+  const data = Buffer.from(bytes); programAssert(data.length >= 24 && data.length <= 8 * 1024 * 1024, "Invalid image byte size");
+  let mime = "", width = 0, height = 0;
+  if (data.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && data.toString("ascii",12,16) === "IHDR") { mime = "image/png"; width = data.readUInt32BE(16); height = data.readUInt32BE(20); }
+  else if (data[0] === 255 && data[1] === 216) {
+    mime = "image/jpeg"; let offset = 2;
+    while (offset + 9 < data.length) { if (data[offset++] !== 255) break; const marker = data[offset++], size = data.readUInt16BE(offset); if ([192,193,194].includes(marker)) { height = data.readUInt16BE(offset+3); width = data.readUInt16BE(offset+5); break; } if (size < 2) break; offset += size; }
+  } else if (data.toString("ascii",0,4) === "RIFF" && data.toString("ascii",8,12) === "WEBP" && data.toString("ascii",12,16) === "VP8X" && data.length >= 30) {
+    mime = "image/webp"; width = 1 + data.readUIntLE(24,3); height = 1 + data.readUIntLE(27,3);
+  }
+  programAssert(width > 0 && height > 0 && width <= 16384 && height <= 16384 && width * height <= 64 * 1024 * 1024, "Unsupported/invalid image header or pixel budget"); return { mime, width, height };
+}

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

@@ -0,0 +1,50 @@
+import { link, open, readFile, unlink } from "node:fs/promises";
+import { readFileSync, unlinkSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { programAssert } from "./program-contract.ts";
+
+const code = (error: unknown) => (error as NodeJS.ErrnoException).code;
+const transient = (error: unknown) => ["ENOENT", "EEXIST", "EPERM", "EACCES", "EBUSY"].includes(code(error) ?? "");
+function dead(bytes: string): boolean {
+  const holder = JSON.parse(bytes) as { pid: number };
+  if (!Number.isSafeInteger(holder.pid) || holder.pid <= 0) return false;
+  try { process.kill(holder.pid, 0); return false; } catch (error) { return code(error) === "ESRCH"; }
+}
+/** Shared local hardlink protocol. Only a confirmed dead holder may be reclaimed. */
+export class ProgramFileLease {
+  private constructor(readonly path: string, readonly token: string, private bytes: string, private lostMessage: string) {}
+  static async acquire(path: string, options: { waitMs?: number; busyCode?: string; busyMessage?: string; lostMessage?: string } = {}): Promise<ProgramFileLease> {
+    const token = randomUUID(), bytes = JSON.stringify({ pid: process.pid, token });
+    const candidate = `${path}.${token}.candidate`, reclaim = `${path}.reclaim`, deadline = Date.now() + (options.waitMs ?? 0);
+    const handle = await open(candidate, "wx", 0o600);
+    try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+    try {
+      for (;;) {
+        try { await link(candidate, path); return new ProgramFileLease(path, token, bytes, options.lostMessage ?? "Program lock ownership changed"); }
+        catch (error) { if (!transient(error)) throw error; }
+        let reclaimed = false;
+        try {
+          const old = await readFile(path, "utf8");
+          if (dead(old)) {
+            try { const guard = readFileSync(reclaim, "utf8"); if (dead(guard) && readFileSync(reclaim, "utf8") === guard) unlinkSync(reclaim); }
+            catch (error) { if (!transient(error) && !(error instanceof SyntaxError)) throw error; }
+            let claimed = false;
+            try {
+              await link(candidate, reclaim); claimed = true;
+              if (readFileSync(path, "utf8") === old) { unlinkSync(path); reclaimed = true; }
+            } finally {
+              if (claimed) { programAssert(readFileSync(reclaim, "utf8") === bytes, "Reclaim identity changed"); unlinkSync(reclaim); }
+            }
+          }
+        } catch (error) { if (!transient(error) && !(error instanceof SyntaxError)) throw error; }
+        if (reclaimed) continue;
+        programAssert(Date.now() < deadline, options.busyMessage ?? "Program lock busy", options.busyCode ?? "AF_PROGRAM_CONFLICT");
+        await new Promise(resolve => setTimeout(resolve, 20));
+      }
+    } finally { await unlink(candidate).catch(() => {}); }
+  }
+  async assert(): Promise<void> { programAssert(await readFile(this.path, "utf8") === this.bytes, this.lostMessage); }
+  async close(): Promise<void> {
+    programAssert(readFileSync(this.path, "utf8") === this.bytes, this.lostMessage); unlinkSync(this.path);
+  }
+}

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

@@ -0,0 +1,16 @@
+import { join } from "node:path";
+import { ProgramFileLease } from "./program-lock.ts";
+
+/** Owner and transactions use the same crash-recoverable admission protocol. */
+export class ProgramOwnerLease {
+  private constructor(private lease: ProgramFileLease) {}
+  get path(): string { return this.lease.path; }
+  get epoch(): string { return this.lease.token; }
+  static async acquire(directory: string): Promise<ProgramOwnerLease> {
+    return new ProgramOwnerLease(await ProgramFileLease.acquire(join(directory, "owner.lock"), {
+      busyCode: "AF_PROGRAM_OWNER_BUSY", busyMessage: "Another program owner is active or reclaiming", lostMessage: "Owner admission lease lost",
+    }));
+  }
+  async assert(): Promise<void> { await this.lease.assert(); }
+  async close(): Promise<void> { await this.lease.close(); }
+}

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

@@ -0,0 +1,38 @@
+import { programAssert } from "./program-contract.ts";
+
+export interface ActivityScope { id: string; limit: number }
+interface Ticket { runId: string; runLimit: number; scopes: ActivityScope[]; resolve: (release: () => void) => void; reject: (error: Error) => void; signal: AbortSignal; abort: () => void }
+/** Round robin between eligible runs; parent controls never hold activity capacity. */
+export class ProgramActivityScheduler {
+  private tickets: Ticket[] = [];
+  private active = new Map<string, number>();
+  private scopes = new Map<string, number>();
+  private count = 0;
+  private lastRun = "";
+  constructor(readonly ownerLimit = 4) { programAssert(Number.isSafeInteger(ownerLimit) && ownerLimit > 0 && ownerLimit <= 32, "Invalid owner capacity"); }
+  restore(runId: string, scopes: ActivityScope[]): () => void {
+    this.count++; this.active.set(runId, (this.active.get(runId) ?? 0) + 1);
+    for (const scope of scopes) this.scopes.set(scope.id, (this.scopes.get(scope.id) ?? 0) + 1);
+    let released = false;
+    return () => { if (released) return; released = true; this.count--; this.active.set(runId, this.active.get(runId)! - 1); for (const scope of scopes) this.scopes.set(scope.id, this.scopes.get(scope.id)! - 1); this.drain(); };
+  }
+  acquire(runId: string, runLimit: number, scopes: ActivityScope[], signal: AbortSignal): Promise<() => void> {
+    return new Promise((resolve, reject) => {
+      const ticket: Ticket = { runId, runLimit, scopes, resolve, reject, signal, abort: () => { this.tickets = this.tickets.filter(entry => entry !== ticket); reject(new Error("Activity admission canceled")); this.drain(); } };
+      if (signal.aborted) { ticket.abort(); return; }
+      signal.addEventListener("abort", ticket.abort, { once: true }); this.tickets.push(ticket); this.drain();
+    });
+  }
+  private drain(): void {
+    while (this.count < this.ownerLimit) {
+      const eligible = this.tickets.filter(ticket => !ticket.signal.aborted && (this.active.get(ticket.runId) ?? 0) < ticket.runLimit && ticket.scopes.every(scope => (this.scopes.get(scope.id) ?? 0) < scope.limit));
+      const ticket = eligible.find(entry => entry.runId !== this.lastRun) ?? eligible[0]; if (!ticket) return;
+      this.tickets.splice(this.tickets.indexOf(ticket), 1); ticket.signal.removeEventListener("abort", ticket.abort);
+      this.lastRun = ticket.runId; this.count++; this.active.set(ticket.runId, (this.active.get(ticket.runId) ?? 0) + 1);
+      for (const scope of ticket.scopes) this.scopes.set(scope.id, (this.scopes.get(scope.id) ?? 0) + 1);
+      let released = false;
+      ticket.resolve(() => { if (released) return; released = true; this.count--; this.active.set(ticket.runId, this.active.get(ticket.runId)! - 1); for (const scope of ticket.scopes) this.scopes.set(scope.id, this.scopes.get(scope.id)! - 1); this.drain(); });
+    }
+  }
+  snapshot(): { active: number; queued: number; ownerLimit: number } { return { active: this.count, queued: this.tickets.length, ownerLimit: this.ownerLimit }; }
+}