@warpgogol/forge 2.8.0 → 2.8.2

package/src/tests/program-schemas.test.ts

@@ -0,0 +1,445 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for program packet schemas — verify strict rejection of
+unknown fields, required fields, and type constraints (RFC-0856).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial schema tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect } from "vitest";
+import {
+  programManifestSchema,
+  programPacketSchema,
+  programPacketLeaseSchema,
+  programPacketCompletionSchema,
+  programPacketPreparationSchema,
+  recoveryRecordSchema,
+} from "../../os/program/schemas.ts";
+
+describe("programManifestSchema", () => {
+  it("accepts a valid manifest", () => {
+    const manifest = {
+      schema: "forge/program@1",
+      program: "RFC-0855",
+      title: "Test program",
+      branch: "main",
+      state: "preparing",
+      currentPacket: "000-test",
+      steward: "human:alice",
+      sequential: true,
+      parallelism: 1,
+      packets: [
+        {
+          order: 0,
+          packetId: "000-test",
+          file: "000-test.md",
+          state: "draft",
+          governingDecision: "RFC-0856",
+          decisionKind: "rfc",
+          resolvedRfc: "RFC-0856",
+          dependsOnPacket: null,
+          baseCommit: null,
+          sealCommit: null,
+          completion: null,
+        },
+      ],
+    };
+
+    const result = programManifestSchema.safeParse(manifest);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects unknown fields", () => {
+    const manifest = {
+      schema: "forge/program@1",
+      program: "RFC-0855",
+      title: "Test",
+      branch: "main",
+      state: "preparing",
+      currentPacket: "000-test",
+      steward: "human:alice",
+      sequential: true,
+      parallelism: 1,
+      packets: [],
+      extraField: "should fail",
+    };
+
+    const result = programManifestSchema.safeParse(manifest);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects parallelism !== 1", () => {
+    const manifest = {
+      schema: "forge/program@1",
+      program: "RFC-0855",
+      title: "Test",
+      branch: "main",
+      state: "preparing",
+      currentPacket: "000-test",
+      steward: "human:alice",
+      sequential: true,
+      parallelism: 2,
+      packets: [],
+    };
+
+    const result = programManifestSchema.safeParse(manifest);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty packets array", () => {
+    const manifest = {
+      schema: "forge/program@1",
+      program: "RFC-0855",
+      title: "Test",
+      branch: "main",
+      state: "preparing",
+      currentPacket: "000-test",
+      steward: "human:alice",
+      sequential: true,
+      parallelism: 1,
+      packets: [],
+    };
+
+    const result = programManifestSchema.safeParse(manifest);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("programPacketSchema", () => {
+  it("accepts a valid packet", () => {
+    const packet = {
+      schema: "forge/program-packet@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      state: "draft",
+      governingDecision: "RFC-0856",
+      decisionKind: "rfc",
+      resolvedRfc: "RFC-0856",
+      dependsOnPacket: null,
+      baseCommit: null,
+      branch: "main",
+      steward: "human:alice",
+      normativeSources: [{ path: "docs/rfcs/rfc-0856.md", sha256: "a".repeat(64) }],
+      allowedFiles: ["packages/forge/**"],
+      forbiddenFiles: ["missions/**"],
+      permittedTransitionDiagnostics: [],
+      requiredValidations: [
+        { command: "pnpm test", expectedStatus: "pass", expectedDiagnostics: [] },
+      ],
+    };
+
+    const result = programPacketSchema.safeParse(packet);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects unknown fields", () => {
+    const packet = {
+      schema: "forge/program-packet@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      state: "draft",
+      governingDecision: "RFC-0856",
+      decisionKind: "rfc",
+      resolvedRfc: "RFC-0856",
+      dependsOnPacket: null,
+      baseCommit: null,
+      branch: "main",
+      steward: "human:alice",
+      normativeSources: [],
+      allowedFiles: [],
+      forbiddenFiles: [],
+      permittedTransitionDiagnostics: [],
+      requiredValidations: [],
+      extra: true,
+    };
+
+    const result = programPacketSchema.safeParse(packet);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty allowedFiles", () => {
+    const packet = {
+      schema: "forge/program-packet@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      state: "draft",
+      governingDecision: "RFC-0856",
+      decisionKind: "rfc",
+      resolvedRfc: "RFC-0856",
+      dependsOnPacket: null,
+      baseCommit: null,
+      branch: "main",
+      steward: "human:alice",
+      normativeSources: [],
+      allowedFiles: [],
+      forbiddenFiles: [],
+      permittedTransitionDiagnostics: [],
+      requiredValidations: [],
+    };
+
+    const result = programPacketSchema.safeParse(packet);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects invalid sha256", () => {
+    const packet = {
+      schema: "forge/program-packet@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      state: "draft",
+      governingDecision: "RFC-0856",
+      decisionKind: "rfc",
+      resolvedRfc: "RFC-0856",
+      dependsOnPacket: null,
+      baseCommit: null,
+      branch: "main",
+      steward: "human:alice",
+      normativeSources: [{ path: "test.md", sha256: "short" }],
+      allowedFiles: ["packages/**"],
+      forbiddenFiles: [],
+      permittedTransitionDiagnostics: [],
+      requiredValidations: [],
+    };
+
+    const result = programPacketSchema.safeParse(packet);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("programPacketLeaseSchema", () => {
+  it("accepts a valid execution lease", () => {
+    const lease = {
+      schema: "forge/program-packet-lease@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      phase: "execution",
+      actor: "agent:bot1",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      tokenHash: "b".repeat(64),
+      startedAt: "2026-08-15T10:00:00Z",
+      heartbeatAt: "2026-08-15T10:00:00Z",
+      timeoutSeconds: 3600,
+    };
+
+    const result = programPacketLeaseSchema.safeParse(lease);
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid preparation lease with null sealCommit", () => {
+    const lease = {
+      schema: "forge/program-packet-lease@1",
+      program: "RFC-0855",
+      packetId: "140-test",
+      phase: "preparation",
+      actor: "human:alice",
+      baseCommit: "abc123",
+      sealCommit: null,
+      tokenHash: "b".repeat(64),
+      startedAt: "2026-08-15T10:00:00Z",
+      heartbeatAt: "2026-08-15T10:00:00Z",
+      timeoutSeconds: 3600,
+    };
+
+    const result = programPacketLeaseSchema.safeParse(lease);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects invalid phase", () => {
+    const lease = {
+      schema: "forge/program-packet-lease@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      phase: "invalid",
+      actor: "agent:bot1",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      tokenHash: "b".repeat(64),
+      startedAt: "2026-08-15T10:00:00Z",
+      heartbeatAt: "2026-08-15T10:00:00Z",
+      timeoutSeconds: 3600,
+    };
+
+    const result = programPacketLeaseSchema.safeParse(lease);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects invalid actor format", () => {
+    const lease = {
+      schema: "forge/program-packet-lease@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      phase: "execution",
+      actor: "invalid-format",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      tokenHash: "b".repeat(64),
+      startedAt: "2026-08-15T10:00:00Z",
+      heartbeatAt: "2026-08-15T10:00:00Z",
+      timeoutSeconds: 3600,
+    };
+
+    const result = programPacketLeaseSchema.safeParse(lease);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("programPacketPreparationSchema", () => {
+  it("accepts a valid preparation report", () => {
+    const prep = {
+      schema: "forge/program-packet-preparation@1",
+      program: "RFC-0855",
+      packetId: "140-resolved-certification-profile",
+      baseCommit: "abc123",
+      preparationCommits: ["def456"],
+      preparationHead: "def456",
+      changedFiles: [
+        "docs/rfcs/rfc-0865.md",
+        "docs/specs/werkstatt-release-certification/forge-spec.yaml",
+      ],
+      governingDecision: "werkstatt-release-certification/CERT-002",
+      resolvedRfc: "RFC-0865",
+      materializationCommit: "def456",
+      validations: [
+        { command: "rfc.validate --id RFC-0865", status: "pass", evidenceDigest: "sha256:abc" },
+      ],
+      cleanTrees: true,
+      preparedBy: "human:andrii-syrokomskyi",
+    };
+
+    const result = programPacketPreparationSchema.safeParse(prep);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects unknown fields", () => {
+    const prep = {
+      schema: "forge/program-packet-preparation@1",
+      program: "RFC-0855",
+      packetId: "140-test",
+      baseCommit: "abc123",
+      preparationCommits: ["def456"],
+      preparationHead: "def456",
+      changedFiles: [],
+      governingDecision: "werkstatt-release-certification/CERT-002",
+      resolvedRfc: "RFC-0865",
+      materializationCommit: "def456",
+      validations: [],
+      cleanTrees: true,
+      preparedBy: "human:alice",
+      extra: true,
+    };
+
+    const result = programPacketPreparationSchema.safeParse(prep);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects cleanTrees: false", () => {
+    const prep = {
+      schema: "forge/program-packet-preparation@1",
+      program: "RFC-0855",
+      packetId: "140-test",
+      baseCommit: "abc123",
+      preparationCommits: ["def456"],
+      preparationHead: "def456",
+      changedFiles: [],
+      governingDecision: "werkstatt-release-certification/CERT-002",
+      resolvedRfc: "RFC-0865",
+      materializationCommit: "def456",
+      validations: [],
+      cleanTrees: false,
+      preparedBy: "human:alice",
+    };
+
+    const result = programPacketPreparationSchema.safeParse(prep);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("programPacketCompletionSchema", () => {
+  it("accepts a valid completion", () => {
+    const completion = {
+      schema: "forge/program-packet-completion@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      implementationCommits: ["ghi789"],
+      implementationHead: "ghi789",
+      changedFiles: ["packages/forge/foo.ts"],
+      validations: [{ command: "pnpm test", status: "pass", evidenceDigest: "sha256:abc" }],
+      remainingTransitionDiagnostics: [],
+      unexpectedDiagnostics: [],
+      recoveryStatus: "not-applicable",
+      cleanTrees: true,
+      completedBy: "human:alice",
+    };
+
+    const result = programPacketCompletionSchema.safeParse(completion);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects non-empty unexpectedDiagnostics", () => {
+    const completion = {
+      schema: "forge/program-packet-completion@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      implementationCommits: ["ghi789"],
+      implementationHead: "ghi789",
+      changedFiles: [],
+      validations: [],
+      remainingTransitionDiagnostics: [],
+      unexpectedDiagnostics: ["something"],
+      recoveryStatus: "not-applicable",
+      cleanTrees: true,
+      completedBy: "human:alice",
+    };
+
+    const result = programPacketCompletionSchema.safeParse(completion);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects cleanTrees: false", () => {
+    const completion = {
+      schema: "forge/program-packet-completion@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      implementationCommits: ["ghi789"],
+      implementationHead: "ghi789",
+      changedFiles: [],
+      validations: [],
+      remainingTransitionDiagnostics: [],
+      unexpectedDiagnostics: [],
+      recoveryStatus: "not-applicable",
+      cleanTrees: false,
+      completedBy: "human:alice",
+    };
+
+    const result = programPacketCompletionSchema.safeParse(completion);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("recoveryRecordSchema", () => {
+  it("accepts a valid recovery record", () => {
+    const recovery = {
+      schema: "forge/program-packet-recovery@1",
+      program: "RFC-0855",
+      packetId: "000-test",
+      previousLeaseDigest: "c".repeat(64),
+      reason: "executor timeout",
+      actor: "human:alice",
+      observedHead: "abc123",
+      target: "blocked",
+      recoveredAt: "2026-08-15T10:00:00Z",
+    };
+
+    const result = recoveryRecordSchema.safeParse(recovery);
+    expect(result.success).toBe(true);
+  });
+});

package/src/tests/program-spec-node.test.ts

@@ -0,0 +1,250 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for RFC-0857 spec-node seal validation — verify that
+spec-node packets with null resolvedRfc are rejected at seal boundary
+(PROGRAM-PACKET-12) and that phase-aware lease schema accepts preparation
+and execution phases.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0857: spec-node seal validation and phase-aware lease tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect } from "vitest";
+import { validateSealTransition } from "../../os/program/state.ts";
+import {
+  programPacketLeaseSchema,
+  programPacketPreparationSchema,
+  type ProgramManifest,
+  type ProgramPacket,
+  type ProgramPacketIndexEntry,
+} from "../../os/program/schemas.ts";
+
+function makeManifest(packets: ProgramPacketIndexEntry[]): ProgramManifest {
+  return {
+    schema: "forge/program@1",
+    program: "RFC-0855",
+    title: "Test",
+    branch: "main",
+    state: "executing",
+    currentPacket: "140-test",
+    steward: "human:alice",
+    sequential: true,
+    parallelism: 1,
+    packets,
+  };
+}
+
+function makePacket(): ProgramPacket {
+  return {
+    schema: "forge/program-packet@1",
+    program: "RFC-0855",
+    packetId: "140-test",
+    state: "draft",
+    governingDecision: "werkstatt-release-certification/CERT-002",
+    decisionKind: "spec-node",
+    resolvedRfc: null,
+    dependsOnPacket: "130-predecessor",
+    baseCommit: "abc123",
+    branch: "main",
+    steward: "human:alice",
+    normativeSources: [{ path: "docs/rfcs/rfc-0857.md", sha256: "a".repeat(64) }],
+    allowedFiles: ["packages/forge/**"],
+    forbiddenFiles: [],
+    permittedTransitionDiagnostics: [],
+    requiredValidations: [],
+  };
+}
+
+function makeEntry(overrides?: Partial<ProgramPacketIndexEntry>): ProgramPacketIndexEntry {
+  return {
+    order: 1,
+    packetId: "140-test",
+    file: "140-test.md",
+    state: "draft",
+    governingDecision: "werkstatt-release-certification/CERT-002",
+    decisionKind: "spec-node",
+    resolvedRfc: null,
+    dependsOnPacket: "130-predecessor",
+    baseCommit: "abc123",
+    sealCommit: null,
+    completion: null,
+    ...overrides,
+  };
+}
+
+function makePredecessorEntry(completed = true): ProgramPacketIndexEntry {
+  return {
+    order: 0,
+    packetId: "130-predecessor",
+    file: "130-predecessor.md",
+    state: completed ? "completed" : "sealed",
+    governingDecision: "RFC-0856",
+    decisionKind: "rfc",
+    resolvedRfc: "RFC-0856",
+    dependsOnPacket: null,
+    baseCommit: null,
+    sealCommit: "def456",
+    completion: completed ? "ghi789" : null,
+  };
+}
+
+describe("RFC-0857: spec-node seal validation", () => {
+  it("rejects spec-node packet with null resolvedRfc", () => {
+    const manifest = makeManifest([makePredecessorEntry(), makeEntry()]);
+    const packet = makePacket();
+    const entry = makeEntry();
+
+    const violations = validateSealTransition(manifest, entry, packet, {
+      branch: "main",
+      head: "abc123",
+      isClean: true,
+      hasActiveLease: false,
+    });
+
+    const specNodeViolation = violations.find((v) => v.rule === "PROGRAM-PACKET-12");
+    expect(specNodeViolation).toBeDefined();
+    expect(specNodeViolation!.message).toContain("resolvedRfc: null");
+  });
+
+  it("accepts spec-node packet with non-null resolvedRfc", () => {
+    const manifest = makeManifest([makePredecessorEntry(), makeEntry({ resolvedRfc: "RFC-0865" })]);
+    const packet = makePacket();
+    const entry = makeEntry({ resolvedRfc: "RFC-0865" });
+
+    const violations = validateSealTransition(manifest, entry, packet, {
+      branch: "main",
+      head: "abc123",
+      isClean: true,
+      hasActiveLease: false,
+    });
+
+    const specNodeViolation = violations.find((v) => v.rule === "PROGRAM-PACKET-12");
+    expect(specNodeViolation).toBeUndefined();
+  });
+
+  it("does not apply PROGRAM-PACKET-12 to rfc-kind packets", () => {
+    const manifest = makeManifest([
+      makePredecessorEntry(),
+      makeEntry({ decisionKind: "rfc", resolvedRfc: "RFC-0856" }),
+    ]);
+    const packet = makePacket();
+    (packet as Partial<ProgramPacket>).decisionKind = "rfc";
+    (packet as Partial<ProgramPacket>).resolvedRfc = "RFC-0856";
+    const entry = makeEntry({ decisionKind: "rfc", resolvedRfc: "RFC-0856" });
+
+    const violations = validateSealTransition(manifest, entry, packet, {
+      branch: "main",
+      head: "abc123",
+      isClean: true,
+      hasActiveLease: false,
+    });
+
+    const specNodeViolation = violations.find((v) => v.rule === "PROGRAM-PACKET-12");
+    expect(specNodeViolation).toBeUndefined();
+  });
+});
+
+describe("RFC-0857: phase-aware lease schema", () => {
+  it("accepts preparation phase lease with null sealCommit", () => {
+    const lease = {
+      schema: "forge/program-packet-lease@1",
+      program: "RFC-0855",
+      packetId: "140-test",
+      phase: "preparation",
+      actor: "human:steward",
+      baseCommit: "abc123",
+      sealCommit: null,
+      tokenHash: "b".repeat(64),
+      startedAt: "2026-08-15T10:00:00Z",
+      heartbeatAt: "2026-08-15T10:00:00Z",
+      timeoutSeconds: 3600,
+    };
+
+    const result = programPacketLeaseSchema.safeParse(lease);
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts execution phase lease with non-null sealCommit", () => {
+    const lease = {
+      schema: "forge/program-packet-lease@1",
+      program: "RFC-0855",
+      packetId: "140-test",
+      phase: "execution",
+      actor: "agent:bot1",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      tokenHash: "b".repeat(64),
+      startedAt: "2026-08-15T10:00:00Z",
+      heartbeatAt: "2026-08-15T10:00:00Z",
+      timeoutSeconds: 3600,
+    };
+
+    const result = programPacketLeaseSchema.safeParse(lease);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects lease missing phase field", () => {
+    const lease = {
+      schema: "forge/program-packet-lease@1",
+      program: "RFC-0855",
+      packetId: "140-test",
+      actor: "agent:bot1",
+      baseCommit: "abc123",
+      sealCommit: "def456",
+      tokenHash: "b".repeat(64),
+      startedAt: "2026-08-15T10:00:00Z",
+      heartbeatAt: "2026-08-15T10:00:00Z",
+      timeoutSeconds: 3600,
+    };
+
+    const result = programPacketLeaseSchema.safeParse(lease);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("RFC-0857: preparation report schema", () => {
+  it("accepts a valid preparation report", () => {
+    const prep = {
+      schema: "forge/program-packet-preparation@1",
+      program: "RFC-0855",
+      packetId: "140-resolved-certification-profile",
+      baseCommit: "abc123",
+      preparationCommits: ["def456"],
+      preparationHead: "def456",
+      changedFiles: ["docs/rfcs/rfc-0865.md"],
+      governingDecision: "werkstatt-release-certification/CERT-002",
+      resolvedRfc: "RFC-0865",
+      materializationCommit: "def456",
+      validations: [
+        { command: "rfc.validate --id RFC-0865", status: "pass", evidenceDigest: "sha256:abc" },
+      ],
+      cleanTrees: true,
+      preparedBy: "human:steward",
+    };
+
+    const result = programPacketPreparationSchema.safeParse(prep);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects preparation report with empty resolvedRfc", () => {
+    const prep = {
+      schema: "forge/program-packet-preparation@1",
+      program: "RFC-0855",
+      packetId: "140-test",
+      baseCommit: "abc123",
+      preparationCommits: ["def456"],
+      preparationHead: "def456",
+      changedFiles: [],
+      governingDecision: "werkstatt-release-certification/CERT-002",
+      resolvedRfc: "",
+      materializationCommit: "def456",
+      validations: [],
+      cleanTrees: true,
+      preparedBy: "human:steward",
+    };
+
+    const result = programPacketPreparationSchema.safeParse(prep);
+    expect(result.success).toBe(false);
+  });
+});