@warpgogol/forge 2.8.0 → 2.8.2

package/os/program/program.module.ts

@@ -0,0 +1,212 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the program packet control plane commands with the forge
+kernel registry (RFC-0856).</purpose>
+<non-goals>
+  <item>Do not implement command logic here — handlers live in handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial program module registration.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export const forgeProgramModule: ForgeModule = {
+  name: "forge-program",
+  version: "0.1.0",
+
+  async register(registry) {
+    const { runValidate } = await import("./handlers/validate.ts");
+    const { runSeal } = await import("./handlers/seal.ts");
+    const { runLease } = await import("./handlers/lease.ts");
+    const { runComplete } = await import("./handlers/complete.ts");
+
+    registry.registerCommand({
+      name: "program.packet.validate",
+      description:
+        "Validate a program packet against schema, source hashes, branch/head, " +
+        "and state machine rules. Read-only. " +
+        "Usage: program.packet.validate --program=RFC-XXXX --packet=NNN-foo --phase=draft --json",
+      scope: "workspace",
+      supportsAllSites: false,
+      flags: {
+        program: {
+          kind: "string",
+          required: true,
+          description: "Program RFC id (e.g. RFC-0855).",
+        },
+        packet: {
+          kind: "string",
+          required: true,
+          description: "Packet id (e.g. 010-node-24).",
+        },
+        phase: {
+          kind: "string",
+          description: "Validation phase: draft, sealed, active, or completion.",
+        },
+        json: {
+          kind: "boolean",
+          description: "Machine-readable JSON output.",
+        },
+      },
+      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+      cacheable: false,
+      execute: runValidate,
+    });
+
+    registry.registerCommand({
+      name: "program.packet.seal",
+      description:
+        "Steward finalizes a packet against the predecessor's completion commit, " +
+        "updates packet state from draft to sealed, and records the seal in the " +
+        "program manifest. Does not commit — use ecosystem.commit after. " +
+        "Usage: program.packet.seal --program=RFC-XXXX --packet=NNN-foo " +
+        "--steward=human:id --idempotency-key=<key> --json",
+      scope: "workspace",
+      supportsAllSites: false,
+      mutatesState: true,
+      flags: {
+        program: {
+          kind: "string",
+          required: true,
+          description: "Program RFC id.",
+        },
+        packet: {
+          kind: "string",
+          required: true,
+          description: "Packet id to seal.",
+        },
+        steward: {
+          kind: "string",
+          required: true,
+          description: "Steward actor id (human:<id> or agent:<id>).",
+        },
+        "idempotency-key": {
+          kind: "string",
+          description: "Idempotency key for retry-safe sealing.",
+        },
+        json: {
+          kind: "boolean",
+          description: "Machine-readable JSON output.",
+        },
+      },
+      writes: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+      cacheable: false,
+      execute: runSeal,
+    });
+
+    registry.registerCommand({
+      name: "program.packet.lease",
+      description:
+        "Manage the exclusive local executor lease for a sealed packet. " +
+        "Actions: start, heartbeat, release, recover. " +
+        "Raw lease tokens are never persisted — only the SHA-256 hash. " +
+        "Usage: program.packet.lease --program=RFC-XXXX --packet=NNN-foo " +
+        "--action=start --executor=agent:id --json",
+      scope: "workspace",
+      supportsAllSites: false,
+      flags: {
+        program: {
+          kind: "string",
+          required: true,
+          description: "Program RFC id.",
+        },
+        packet: {
+          kind: "string",
+          required: true,
+          description: "Packet id.",
+        },
+        action: {
+          kind: "string",
+          required: true,
+          description: "Lease action: start, heartbeat, release, or recover.",
+        },
+        executor: {
+          kind: "string",
+          description: "Executor actor id (required for --action=start).",
+        },
+        steward: {
+          kind: "string",
+          description: "Steward actor id (required for --action=recover).",
+        },
+        "lease-token": {
+          kind: "string",
+          description: "Opaque lease token (required for heartbeat and release).",
+        },
+        reason: {
+          kind: "string",
+          description: "Recovery reason (required for --action=recover).",
+        },
+        json: {
+          kind: "boolean",
+          description: "Machine-readable JSON output.",
+        },
+      },
+      writes: [".forge/program-leases/**"],
+      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+      cacheable: false,
+      execute: runLease,
+    });
+
+    registry.registerCommand({
+      name: "program.packet.complete",
+      description:
+        "Steward validates the implementation range, writes the completion report, " +
+        "and updates the program manifest. Supports --bootstrap for packet 000. " +
+        "Does not commit — use ecosystem.commit after. " +
+        "Usage: program.packet.complete --program=RFC-XXXX --packet=NNN-foo " +
+        "--steward=human:id --lease-token=<token> --implementation-head=<sha> --json",
+      scope: "workspace",
+      supportsAllSites: false,
+      mutatesState: true,
+      flags: {
+        program: {
+          kind: "string",
+          required: true,
+          description: "Program RFC id.",
+        },
+        packet: {
+          kind: "string",
+          required: true,
+          description: "Packet id to complete.",
+        },
+        steward: {
+          kind: "string",
+          required: true,
+          description: "Steward actor id (must differ from executor).",
+        },
+        "lease-token": {
+          kind: "string",
+          description: "Lease token (required for non-bootstrap).",
+        },
+        "implementation-head": {
+          kind: "string",
+          description: "SHA of the implementation head commit (required for non-bootstrap).",
+        },
+        "idempotency-key": {
+          kind: "string",
+          description: "Idempotency key for retry-safe completion.",
+        },
+        bootstrap: {
+          kind: "boolean",
+          description: "Bootstrap completion (packet 000 only).",
+        },
+        "seal-commit": {
+          kind: "string",
+          description: "Seal commit SHA (required for --bootstrap).",
+        },
+        json: {
+          kind: "boolean",
+          description: "Machine-readable JSON output.",
+        },
+      },
+      writes: ["docs/plans/**/completions/**", "docs/plans/**/program.yaml"],
+      reads: ["docs/plans/**/program.yaml", "docs/plans/**/*.md"],
+      cacheable: false,
+      execute: runComplete,
+    });
+  },
+};

package/os/program/schemas.ts

@@ -0,0 +1,218 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Zod schemas for the forge/program@1 control plane — program manifest,
+packet, lease, completion, and recovery records. All schemas are strict and
+reject unknown fields (RFC-0856).</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — forge must remain dependency-free.</item>
+  <item>Do not add command logic here — schemas only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial program control-plane schemas.</item>
+  <item>RFC-0857: phase-aware lease schema (preparation | execution) and preparation report schema.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod/v4";
+
+// ---------------------------------------------------------------------------
+// Shared primitives
+// ---------------------------------------------------------------------------
+
+export const programActorSchema = z
+  .string()
+  .regex(/^(human|agent):.+$/, "Must be 'human:<id>' or 'agent:<id>'");
+
+export const programStateSchema = z.enum(["preparing", "executing", "blocked", "complete"]);
+
+export const packetStateSchema = z.enum(["draft", "sealed", "active", "completed", "blocked"]);
+
+export const recoveryStatusSchema = z.enum(["verified", "not-applicable"]);
+
+export const programLeasePhaseSchema = z.enum(["preparation", "execution"]);
+
+// ---------------------------------------------------------------------------
+// Program manifest: forge/program@1
+// ---------------------------------------------------------------------------
+
+export const programPacketIndexEntrySchema = z.object({
+  order: z.number().int().min(0),
+  packetId: z.string().min(1),
+  file: z.string().min(1),
+  state: packetStateSchema,
+  governingDecision: z.string().min(1),
+  decisionKind: z.enum(["rfc", "spec-amendment", "spec-node"]),
+  resolvedRfc: z.string().nullable(),
+  dependsOnPacket: z.string().nullable(),
+  baseCommit: z.string().nullable(),
+  sealCommit: z.string().nullable(),
+  completion: z.string().nullable(),
+});
+
+export const programManifestSchema = z
+  .object({
+    schema: z.literal("forge/program@1"),
+    program: z.string().min(1),
+    title: z.string().min(1),
+    branch: z.string().min(1),
+    state: programStateSchema,
+    currentPacket: z.string().min(1),
+    steward: programActorSchema,
+    sequential: z.literal(true),
+    parallelism: z.literal(1),
+    packets: z.array(programPacketIndexEntrySchema).min(1),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Program packet: forge/program-packet@1
+// ---------------------------------------------------------------------------
+
+export const normativeSourceSchema = z.object({
+  path: z.string().min(1),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/, "Must be a SHA-256 hex digest"),
+});
+
+export const requiredValidationSchema = z.object({
+  command: z.string().min(1),
+  expectedStatus: z.literal("pass"),
+  expectedDiagnostics: z.array(z.string()),
+});
+
+export const programPacketSchema = z
+  .object({
+    schema: z.literal("forge/program-packet@1"),
+    program: z.string().min(1),
+    packetId: z.string().min(1),
+    state: z.enum(["draft", "sealed"]),
+    governingDecision: z.string().min(1),
+    decisionKind: z.enum(["rfc", "spec-amendment", "spec-node"]),
+    resolvedRfc: z.string().nullable(),
+    dependsOnPacket: z.string().nullable(),
+    baseCommit: z.string().nullable(),
+    branch: z.string().min(1),
+    steward: programActorSchema,
+    normativeSources: z.array(normativeSourceSchema),
+    allowedFiles: z.array(z.string().min(1)).min(1),
+    forbiddenFiles: z.array(z.string().min(1)),
+    permittedTransitionDiagnostics: z.array(z.string()),
+    requiredValidations: z.array(requiredValidationSchema),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Program packet lease: forge/program-packet-lease@1
+// ---------------------------------------------------------------------------
+
+export const programPacketLeaseSchema = z
+  .object({
+    schema: z.literal("forge/program-packet-lease@1"),
+    program: z.string().min(1),
+    packetId: z.string().min(1),
+    phase: programLeasePhaseSchema,
+    actor: programActorSchema,
+    baseCommit: z.string().min(1),
+    sealCommit: z.string().nullable(),
+    tokenHash: z.string().regex(/^[0-9a-f]{64}$/, "Must be a SHA-256 hex digest"),
+    startedAt: z.string().min(1),
+    heartbeatAt: z.string().min(1),
+    timeoutSeconds: z.number().int().positive(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Program packet preparation: forge/program-packet-preparation@1 (RFC-0857)
+// ---------------------------------------------------------------------------
+
+export const preparationValidationSchema = z.object({
+  command: z.string().min(1),
+  status: z.literal("pass"),
+  evidenceDigest: z.string().min(1),
+});
+
+export const programPacketPreparationSchema = z
+  .object({
+    schema: z.literal("forge/program-packet-preparation@1"),
+    program: z.string().min(1),
+    packetId: z.string().min(1),
+    baseCommit: z.string().min(1),
+    preparationCommits: z.array(z.string().min(1)),
+    preparationHead: z.string().min(1),
+    changedFiles: z.array(z.string().min(1)),
+    governingDecision: z.string().min(1),
+    resolvedRfc: z.string().min(1),
+    materializationCommit: z.string().min(1),
+    validations: z.array(preparationValidationSchema),
+    cleanTrees: z.literal(true),
+    preparedBy: programActorSchema,
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Program packet completion: forge/program-packet-completion@1
+// ---------------------------------------------------------------------------
+
+export const completionValidationSchema = z.object({
+  command: z.string().min(1),
+  status: z.literal("pass"),
+  evidenceDigest: z.string().min(1),
+});
+
+export const programPacketCompletionSchema = z
+  .object({
+    schema: z.literal("forge/program-packet-completion@1"),
+    program: z.string().min(1),
+    packetId: z.string().min(1),
+    baseCommit: z.string().min(1),
+    sealCommit: z.string().min(1),
+    implementationCommits: z.array(z.string().min(1)),
+    implementationHead: z.string().min(1),
+    changedFiles: z.array(z.string().min(1)),
+    validations: z.array(completionValidationSchema),
+    remainingTransitionDiagnostics: z.array(z.string()),
+    unexpectedDiagnostics: z.array(z.string()).length(0),
+    recoveryStatus: recoveryStatusSchema,
+    cleanTrees: z.literal(true),
+    completedBy: programActorSchema,
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Recovery record: forge/program-packet-recovery@1
+// ---------------------------------------------------------------------------
+
+export const recoveryRecordSchema = z
+  .object({
+    schema: z.literal("forge/program-packet-recovery@1"),
+    program: z.string().min(1),
+    packetId: z.string().min(1),
+    previousLeaseDigest: z.string().min(1),
+    reason: z.string().min(1),
+    actor: programActorSchema,
+    observedHead: z.string().min(1),
+    target: z.enum(["blocked", "sealed"]),
+    recoveredAt: z.string().min(1),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// TypeScript types (inferred from schemas)
+// ---------------------------------------------------------------------------
+
+export type ProgramActor = z.infer<typeof programActorSchema>;
+export type ProgramState = z.infer<typeof programStateSchema>;
+export type PacketState = z.infer<typeof packetStateSchema>;
+export type RecoveryStatus = z.infer<typeof recoveryStatusSchema>;
+export type ProgramManifest = z.infer<typeof programManifestSchema>;
+export type ProgramPacketIndexEntry = z.infer<typeof programPacketIndexEntrySchema>;
+export type ProgramPacket = z.infer<typeof programPacketSchema>;
+export type NormativeSource = z.infer<typeof normativeSourceSchema>;
+export type RequiredValidation = z.infer<typeof requiredValidationSchema>;
+export type ProgramLeasePhase = z.infer<typeof programLeasePhaseSchema>;
+export type ProgramPacketLease = z.infer<typeof programPacketLeaseSchema>;
+export type PreparationValidation = z.infer<typeof preparationValidationSchema>;
+export type ProgramPacketPreparation = z.infer<typeof programPacketPreparationSchema>;
+export type ProgramPacketCompletion = z.infer<typeof programPacketCompletionSchema>;
+export type CompletionValidation = z.infer<typeof completionValidationSchema>;
+export type RecoveryRecord = z.infer<typeof recoveryRecordSchema>;

package/os/program/state.ts

@@ -0,0 +1,264 @@
+/*
+<MODULE_CONTRACT>
+<purpose>State machine logic for program packet transitions.
+Validates allowed transitions and produces violation records.</purpose>
+<non-goals>
+  <item>Do not mutate files — state validation only.</item>
+  <item>Do not import from @warpgogol/* — forge must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial state machine logic.</item>
+  <item>RFC-0857: spec-node resolvedRfc validation at seal boundary (PROGRAM-PACKET-12).</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  ProgramManifest,
+  ProgramPacket,
+  ProgramPacketIndexEntry,
+  ProgramPacketLease,
+  ProgramActor,
+} from "./schemas.ts";
+
+// ---------------------------------------------------------------------------
+// Violation type
+// ---------------------------------------------------------------------------
+
+export interface PacketViolation {
+  rule: string;
+  path?: string;
+  message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Transition validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a seal transition is allowed.
+ */
+export function validateSealTransition(
+  manifest: ProgramManifest,
+  entry: ProgramPacketIndexEntry,
+  packet: ProgramPacket,
+  options: {
+    branch: string;
+    head: string;
+    isClean: boolean;
+    hasActiveLease: boolean;
+  },
+): PacketViolation[] {
+  const violations: PacketViolation[] = [];
+
+  // PROGRAM-PACKET-02: wrong branch
+  if (options.branch !== manifest.branch) {
+    violations.push({
+      rule: "PROGRAM-PACKET-02",
+      message: `wrong branch: expected ${manifest.branch}, got ${options.branch}`,
+    });
+  }
+
+  // PROGRAM-PACKET-10: dirty tree at sealed boundary
+  if (!options.isClean) {
+    violations.push({
+      rule: "PROGRAM-PACKET-10",
+      message: "dirty tree at seal boundary — commit or stash changes first",
+    });
+  }
+
+  // PROGRAM-PACKET-05: active or stale lease exists
+  if (options.hasActiveLease) {
+    violations.push({
+      rule: "PROGRAM-PACKET-05",
+      message: "active or stale lease exists — recover before sealing",
+    });
+  }
+
+  // Packet must be in draft state
+  if (packet.state !== "draft") {
+    violations.push({
+      rule: "PROGRAM-PACKET-04",
+      message: `packet state is ${packet.state}, expected draft`,
+    });
+  }
+
+  // PROGRAM-PACKET-03: predecessor must be completed (unless bootstrap)
+  if (entry.dependsOnPacket !== null) {
+    const predecessor = manifest.packets.find((p) => p.packetId === entry.dependsOnPacket);
+    if (!predecessor) {
+      violations.push({
+        rule: "PROGRAM-PACKET-03",
+        message: `predecessor packet ${entry.dependsOnPacket} not found in manifest`,
+      });
+    } else if (predecessor.state !== "completed") {
+      violations.push({
+        rule: "PROGRAM-PACKET-03",
+        message: `predecessor packet ${entry.dependsOnPacket} is ${predecessor.state}, expected completed`,
+      });
+    } else if (predecessor.completion && entry.baseCommit !== predecessor.completion) {
+      violations.push({
+        rule: "PROGRAM-PACKET-09",
+        message: `baseCommit ${entry.baseCommit} does not match predecessor completion ${predecessor.completion}`,
+      });
+    }
+  }
+
+  // baseCommit must be set for sealed packet (unless bootstrap with null predecessor)
+  if (entry.dependsOnPacket !== null && entry.baseCommit === null) {
+    violations.push({
+      rule: "PROGRAM-PACKET-09",
+      message: "baseCommit is null for a non-bootstrap packet",
+    });
+  }
+
+  // allowedFiles must be non-empty
+  if (packet.allowedFiles.length === 0) {
+    violations.push({
+      rule: "PROGRAM-PACKET-06",
+      message: "allowedFiles is empty — packet must define at least one allowed path",
+    });
+  }
+
+  // RFC-0857: spec-node packets require a resolved RFC that is accepted or implemented
+  if (entry.decisionKind === "spec-node") {
+    if (entry.resolvedRfc === null) {
+      violations.push({
+        rule: "PROGRAM-PACKET-12",
+        message: `spec-node packet ${entry.packetId} has resolvedRfc: null — materialize and accept the governing RFC before sealing`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Validate that a lease start transition is allowed.
+ */
+export function validateLeaseStartTransition(
+  manifest: ProgramManifest,
+  entry: ProgramPacketIndexEntry,
+  packet: ProgramPacket,
+  options: {
+    head: string;
+    steward: ProgramActor;
+    actor: ProgramActor;
+    hasActiveLease: boolean;
+  },
+): PacketViolation[] {
+  const violations: PacketViolation[] = [];
+
+  // PROGRAM-PACKET-04: role collision
+  if (options.steward === options.actor) {
+    violations.push({
+      rule: "PROGRAM-PACKET-04",
+      message: `role collision: steward and actor are the same (${options.steward})`,
+    });
+  }
+
+  // Packet must be sealed
+  if (packet.state !== "sealed") {
+    violations.push({
+      rule: "PROGRAM-PACKET-04",
+      message: `packet state is ${packet.state}, expected sealed`,
+    });
+  }
+
+  // PROGRAM-PACKET-05: active or stale lease exists
+  if (options.hasActiveLease) {
+    violations.push({
+      rule: "PROGRAM-PACKET-05",
+      message: "active or stale lease already exists for this packet",
+    });
+  }
+
+  // PROGRAM-PACKET-02: HEAD must match sealCommit
+  if (entry.sealCommit && options.head !== entry.sealCommit) {
+    violations.push({
+      rule: "PROGRAM-PACKET-02",
+      message: `HEAD ${options.head} does not match sealCommit ${entry.sealCommit}`,
+    });
+  }
+
+  return violations;
+}
+
+/**
+ * Validate that a completion transition is allowed.
+ */
+export function validateCompleteTransition(
+  manifest: ProgramManifest,
+  entry: ProgramPacketIndexEntry,
+  lease: ProgramPacketLease,
+  options: {
+    head: string;
+    isClean: boolean;
+    steward: ProgramActor;
+    implementationHead: string;
+    changedFiles: string[];
+    allowedFiles: string[];
+    forbiddenFiles: string[];
+    ancestryValid: boolean;
+  },
+): PacketViolation[] {
+  const violations: PacketViolation[] = [];
+
+  // PROGRAM-PACKET-04: steward must differ from actor
+  if (options.steward === lease.actor) {
+    violations.push({
+      rule: "PROGRAM-PACKET-04",
+      message: "completion steward must differ from lease actor",
+    });
+  }
+
+  // PROGRAM-PACKET-10: dirty tree
+  if (!options.isClean) {
+    violations.push({
+      rule: "PROGRAM-PACKET-10",
+      message: "dirty tree at completion boundary",
+    });
+  }
+
+  // PROGRAM-PACKET-09: ancestry
+  if (!options.ancestryValid) {
+    violations.push({
+      rule: "PROGRAM-PACKET-09",
+      message: "implementation commits do not descend from seal commit",
+    });
+  }
+
+  // PROGRAM-PACKET-09: implementation head must match
+  if (options.head !== options.implementationHead) {
+    violations.push({
+      rule: "PROGRAM-PACKET-09",
+      message: `HEAD ${options.head} does not match declared implementationHead ${options.implementationHead}`,
+    });
+  }
+
+  // PROGRAM-PACKET-06: path validation
+  for (const file of options.changedFiles) {
+    if (options.forbiddenFiles.length > 0 && isPathForbidden(file, options.forbiddenFiles)) {
+      violations.push({
+        rule: "PROGRAM-PACKET-06",
+        path: file,
+        message: `changed file ${file} is in forbidden list`,
+      });
+    }
+    if (!isPathAllowed(file, options.allowedFiles)) {
+      violations.push({
+        rule: "PROGRAM-PACKET-06",
+        path: file,
+        message: `changed file ${file} is not in allowed list`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+// ---------------------------------------------------------------------------
+// Path helpers (imported from discovery for convenience)
+// ---------------------------------------------------------------------------
+
+import { isPathAllowed, isPathForbidden } from "./discovery.ts";