owlrunkit 0.15.0 → 0.16.0

package/scripts/runkit-contract/finalize.mjs

@@ -20,11 +20,12 @@ import {
   safeIdentifier,
   sha256,
   writeJsonAtomically,
-  writeJsonExclusive,
+  writeJsonExclusiveAtomically,
 } from "./provenance-common.mjs";
 import { receiptSha256, validateReceiptLineage } from "./receipt-lineage.mjs";
 import { verifySnapshotEvidence, verifySnapshotSourceBinding } from "./snapshot.mjs";
 import { verifyDeliveryPacket } from "./source-fingerprint.mjs";
+import { verifySourceCandidateV2 } from "./source-candidate.mjs";
 import {
   validateVerificationContext,
   verificationContextFingerprint,
@@ -36,6 +37,7 @@ const REQUEST_KEYS = [
   "schemaVersion",
   "receiptId",
   "deliveryPacketPath",
+  "sourceCandidatePath",
   "verificationContext",
   "snapshotPaths",
   "supersedesReceiptSha256",
@@ -56,6 +58,75 @@ const REPAIRABLE_INVALID_REASONS = new Set([
   "source_mutated_during_verification",
 ]);
 
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort()
+      .map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(",")}}`;
+  }
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) {
+    throw new Error("Finalize artifact is not canonical JSON.");
+  }
+  return encoded;
+}
+
+function writeFinalizeArtifactExact(filePath, value, label) {
+  if (!existsSync(filePath)) {
+    writeJsonExclusiveAtomically(filePath, value);
+    return;
+  }
+  const stat = lstatSync(filePath);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`Existing finalize artifact differs: ${label}.`);
+  }
+  const existing = readJson(realpathSync(filePath));
+  if (canonicalJson(existing) !== canonicalJson(value)) {
+    throw new Error(`Existing finalize artifact differs: ${label}.`);
+  }
+}
+
+function writeFinalizeLineageExact(
+  filePath,
+  { expectedEntries, nextEntries },
+) {
+  const validation = validateReceiptLineage(nextEntries);
+  if (!validation.valid || !validation.active) {
+    throw new Error("Replacement receipt lineage is invalid.");
+  }
+  if (!existsSync(filePath)) {
+    if (expectedEntries.length !== 0 || nextEntries.length !== 1) {
+      throw new Error("Receipt lineage changed before activation.");
+    }
+    writeJsonExclusiveAtomically(filePath, nextEntries);
+    return;
+  }
+  const stat = lstatSync(filePath);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error("Receipt lineage changed before activation.");
+  }
+  const document = readJson(realpathSync(filePath));
+  const currentEntries = Array.isArray(document)
+    ? document
+    : document?.receipts;
+  if (!Array.isArray(currentEntries)) {
+    throw new Error("Receipt lineage changed before activation.");
+  }
+  if (canonicalJson(currentEntries) === canonicalJson(nextEntries)) {
+    return;
+  }
+  if (
+    canonicalJson(currentEntries) !== canonicalJson(expectedEntries)
+    || nextEntries.length !== expectedEntries.length + 1
+    || canonicalJson(nextEntries.slice(0, -1))
+      !== canonicalJson(expectedEntries)
+  ) {
+    throw new Error("Receipt lineage changed before activation.");
+  }
+  writeJsonAtomically(filePath, nextEntries);
+}
+
 function changedPaths(packet) {
   const files = packet?.changedFiles?.files ?? packet?.changedFiles?.wholeFileSha256;
   if (!isRecord(files) || Object.keys(files).length === 0) {
@@ -64,14 +135,106 @@ function changedPaths(packet) {
   return Object.keys(files).sort();
 }
 
+function candidateChangedPaths(candidate) {
+  return [...new Set(candidate.sourceManifest.entries.flatMap((entry) => (
+    entry.previousPath ? [entry.path, entry.previousPath] : [entry.path]
+  )))].sort();
+}
+
+function candidatePresentFiles(candidate) {
+  return Object.fromEntries(candidate.sourceManifest.entries
+    .filter((entry) => entry.operation !== "deleted")
+    .map((entry) => [entry.path, entry.sha256])
+    .sort(([left], [right]) => left.localeCompare(right)));
+}
+
+function loadFinalizeSource({ workspaceRoot, runId, request }) {
+  if (request.deliveryPacketPath !== undefined) {
+    const sourcePath = resolveExistingArtifact(
+      workspaceRoot,
+      request.deliveryPacketPath,
+      "deliveryPacketPath",
+    );
+    const source = readJson(sourcePath);
+    if (source.runId !== runId) {
+      throw new Error("Delivery packet runId does not match the execution.");
+    }
+    const sourceGate = verifyDeliveryPacket({ workspaceRoot, packet: source });
+    return {
+      kind: "delivery_packet_v1",
+      sourcePath,
+      source,
+      sourceGate,
+      changedPaths: changedPaths(source),
+      expectedFiles:
+        source.changedFiles?.files ?? source.changedFiles?.wholeFileSha256,
+      verifyCurrent: () => verifyDeliveryPacket({
+        workspaceRoot,
+        packet: source,
+      }),
+    };
+  }
+
+  const sourcePath = resolveExistingArtifact(
+    workspaceRoot,
+    request.sourceCandidatePath,
+    "sourceCandidatePath",
+  );
+  const source = readJson(sourcePath);
+  if (source.runId !== runId) {
+    throw new Error("Source candidate runId does not match the execution.");
+  }
+  const candidateGate = verifySourceCandidateV2({
+    workspaceRoot,
+    candidatePath: request.sourceCandidatePath,
+  });
+  const fingerprint = source.sourceFingerprint?.sha256;
+  const sourceGate = {
+    status: candidateGate.status,
+    exitCode: candidateGate.exitCode,
+    declaredFingerprint: fingerprint,
+    recomputedFingerprint: candidateGate.status === "valid"
+      ? candidateGate.sourceFingerprint
+      : fingerprint,
+    issues: candidateGate.issueCodes ?? [],
+  };
+  return {
+    kind: "source_candidate_v2",
+    sourcePath,
+    source,
+    sourceGate,
+    changedPaths: candidateChangedPaths(source),
+    expectedFiles: candidatePresentFiles(source),
+    verifyCurrent: () => {
+      const gate = verifySourceCandidateV2({
+        workspaceRoot,
+        candidatePath: request.sourceCandidatePath,
+      });
+      return {
+        status: gate.status,
+        exitCode: gate.exitCode,
+        declaredFingerprint: fingerprint,
+        recomputedFingerprint: gate.status === "valid"
+          ? gate.sourceFingerprint
+          : fingerprint,
+        issues: gate.issueCodes ?? [],
+      };
+    },
+  };
+}
+
 function validateRequest(request) {
   assertAllowedKeys(request, "Finalize request", REQUEST_KEYS);
   if (request.schemaVersion !== "OwlCodaRunKitFinalizeRequestV1") {
     throw new Error("Unsupported finalize request schemaVersion.");
   }
   safeIdentifier(request.receiptId, "receiptId");
-  if (typeof request.deliveryPacketPath !== "string" || request.deliveryPacketPath.length === 0) {
-    throw new Error("Finalize request requires deliveryPacketPath.");
+  const hasDeliveryPacket = typeof request.deliveryPacketPath === "string"
+    && request.deliveryPacketPath.length > 0;
+  const hasSourceCandidate = typeof request.sourceCandidatePath === "string"
+    && request.sourceCandidatePath.length > 0;
+  if (hasDeliveryPacket === hasSourceCandidate) {
+    throw new Error("Finalize requires exactly one deliveryPacketPath or sourceCandidatePath.");
   }
   if (!Array.isArray(request.snapshotPaths)
     || request.snapshotPaths.some((value) => typeof value !== "string" || value.length === 0)) {
@@ -100,6 +263,9 @@ function validateRequest(request) {
   if (request.supersedesReceiptSha256 === undefined && request.repairControl !== undefined) {
     throw new Error("repairControl is only valid for repair finalize.");
   }
+  if (hasSourceCandidate && request.supersedesReceiptSha256 !== undefined) {
+    throw new Error("SourceCandidate V2 finalize does not support receipt repair.");
+  }
   if (request.repairControl !== undefined) validateRepairControl(request.repairControl);
   const context = validateVerificationContext(request.verificationContext);
   if (!context.valid) throw new Error(`Finalize verification context is invalid: ${context.issues.join("; ")}`);
@@ -280,6 +446,7 @@ function snapshotCommandReceipt({
   expectedFiles,
   expectedFingerprint,
   partialSourceBinding = false,
+  sourceCandidate = null,
 }) {
   const absolutePath = resolveExistingArtifact(workspaceRoot, snapshotPath, "snapshotPaths entry");
   const snapshot = readJson(absolutePath);
@@ -288,7 +455,29 @@ function snapshotCommandReceipt({
   }
   const validation = verifySnapshotEvidence({ workspaceRoot, runId, snapshot });
   if (!validation.valid) throw new Error(validation.issues.join("; "));
-  if (!partialSourceBinding) {
+  if (sourceCandidate !== null) {
+    const expected = JSON.stringify(sortedFileMap(expectedFiles));
+    const before = JSON.stringify(sortedFileMap(
+      snapshot.repositoryBefore?.selectedFiles ?? {},
+    ));
+    const after = JSON.stringify(sortedFileMap(
+      snapshot.repositoryAfter?.selectedFiles ?? {},
+    ));
+    const materialInputs = Object.entries(sortedFileMap(expectedFiles))
+      .map(([id, hash]) => ({ id, sha256: hash }));
+    const actualMaterialInputs = [
+      ...(snapshot.command?.evidence?.materialInputs ?? []),
+    ].sort((left, right) => String(left?.id).localeCompare(String(right?.id)));
+    if (
+      snapshot.repositoryBefore?.head !== sourceCandidate.baseline.head
+      || snapshot.repositoryAfter?.head !== sourceCandidate.baseline.head
+      || before !== expected
+      || after !== expected
+      || JSON.stringify(actualMaterialInputs) !== JSON.stringify(materialInputs)
+    ) {
+      throw new Error("Snapshot source does not match SourceCandidate V2.");
+    }
+  } else if (!partialSourceBinding) {
     const sourceBinding = verifySnapshotSourceBinding({ snapshot, expectedFiles, expectedFingerprint });
     if (!sourceBinding.valid) throw new Error(sourceBinding.issues.join("; "));
   }
@@ -323,6 +512,13 @@ function nextLineage({ lineagePath, receipt, supersedesReceiptSha256 }) {
     }
     return [{ receiptSha256: nextHash, receipt }];
   }
+  if (
+    supersedesReceiptSha256 === undefined
+    && existing.active.receiptSha256 === nextHash
+    && canonicalJson(existing.active.receipt) === canonicalJson(receipt)
+  ) {
+    return existing.entries;
+  }
   if (supersedesReceiptSha256 !== undefined) {
     if (existing.active.receiptSha256 !== supersedesReceiptSha256) {
       throw new Error("Repair supersedesReceiptSha256 does not match the active receipt.");
@@ -603,14 +799,10 @@ export function runFinalize({ workspaceRoot, runId, request, hooks = {} }) {
   const { executionRoot, pinGate } = loadActiveExecution(workspaceRoot, runId);
   if (pinGate.status !== "valid") return pinGate;
   assertExecutionUnclosed(executionRoot, runId);
-  const packetPath = resolveExistingArtifact(
-    workspaceRoot,
-    request.deliveryPacketPath,
-    "deliveryPacketPath",
-  );
-  const packet = readJson(packetPath);
-  if (packet.runId !== runId) throw new Error("Delivery packet runId does not match the execution.");
-  const sourceGate = verifyDeliveryPacket({ workspaceRoot, packet });
+  const sourceBinding = loadFinalizeSource({ workspaceRoot, runId, request });
+  const packetPath = sourceBinding.sourcePath;
+  const packet = sourceBinding.source;
+  const sourceGate = sourceBinding.sourceGate;
   if (sourceGate.status !== "valid") {
     return {
       status: sourceGate.status,
@@ -622,7 +814,7 @@ export function runFinalize({ workspaceRoot, runId, request, hooks = {} }) {
   }
   const profilesDocument = readJson(path.join(workspaceRoot, ".owlcoda/runkit/profiles.json"));
   const profileImpact = resolveProfileImpactProjection({
-    changedPaths: changedPaths(packet),
+    changedPaths: sourceBinding.changedPaths,
     profiles: profilesDocument.profiles,
     detailed: request.supersedesReceiptSha256 !== undefined,
   });
@@ -636,7 +828,7 @@ export function runFinalize({ workspaceRoot, runId, request, hooks = {} }) {
     };
   }
   const contextFingerprint = verificationContextFingerprint(request.verificationContext);
-  const expectedFiles = packet.changedFiles?.files ?? packet.changedFiles?.wholeFileSha256;
+  const expectedFiles = sourceBinding.expectedFiles;
   const receiptsRoot = path.join(executionRoot, "verification-receipts");
   const lineagePath = path.join(receiptsRoot, "receipt-lineage.json");
   const existing = activeLineage(lineagePath);
@@ -679,6 +871,9 @@ export function runFinalize({ workspaceRoot, runId, request, hooks = {} }) {
     expectedFiles,
     expectedFingerprint: sourceGate.recomputedFingerprint,
     partialSourceBinding: request.supersedesReceiptSha256 !== undefined,
+    sourceCandidate: sourceBinding.kind === "source_candidate_v2"
+      ? sourceBinding.source
+      : null,
   }));
   const commandReceipts = [...reusedCommandReceipts, ...replayedCommandReceipts];
   const commandIds = commandReceipts.map(receipt => receipt.id);
@@ -714,6 +909,13 @@ export function runFinalize({ workspaceRoot, runId, request, hooks = {} }) {
     receiptId: request.receiptId,
     status: "passed",
     sourceFingerprint: sourceGate.recomputedFingerprint,
+    sourceArtifact: {
+      kind: sourceBinding.kind,
+      runId,
+      path: relativeToWorkspace(workspaceRoot, sourceBinding.sourcePath),
+      sha256: sha256(readFileSync(sourceBinding.sourcePath)),
+      sourceFingerprint: sourceGate.recomputedFingerprint,
+    },
     verificationContextFingerprint: contextFingerprint,
     goalContractSha256: currentGoal.goalContractSha256,
     risk: structuredClone(currentGoal.risk),
@@ -758,7 +960,7 @@ export function runFinalize({ workspaceRoot, runId, request, hooks = {} }) {
         selectedProfileIds: profileImpact.profileIds,
         activeParent: existing.active,
       });
-    } else if (verifyDeliveryPacket({ workspaceRoot, packet }).status !== "valid") {
+    } else if (sourceBinding.verifyCurrent().status !== "valid") {
       throw new Error("Source changed before receipt persistence.");
     }
   };
@@ -768,14 +970,33 @@ export function runFinalize({ workspaceRoot, runId, request, hooks = {} }) {
   const profileImpactPath = path.join(outputRoot, "profile-impact.json");
   const gateInputPath = path.join(outputRoot, "verification-gate-input.json");
   const gateOutputPath = path.join(outputRoot, "verification-gate-output.json");
-  writeJsonExclusive(receiptPath, receipt);
-  writeJsonExclusive(sourceGatePath, sourceGate);
-  writeJsonExclusive(profileImpactPath, profileImpact);
-  writeJsonExclusive(gateInputPath, gateInput);
-  writeJsonExclusive(gateOutputPath, gate);
+  writeFinalizeArtifactExact(
+    receiptPath,
+    receipt,
+    "verification receipt",
+  );
+  writeFinalizeArtifactExact(sourceGatePath, sourceGate, "source gate");
+  writeFinalizeArtifactExact(
+    profileImpactPath,
+    profileImpact,
+    "profile impact",
+  );
+  writeFinalizeArtifactExact(
+    gateInputPath,
+    gateInput,
+    "verification gate input",
+  );
+  writeFinalizeArtifactExact(
+    gateOutputPath,
+    gate,
+    "verification gate output",
+  );
   if (typeof hooks.beforeLineageActivate === "function") hooks.beforeLineageActivate();
   assertCurrentBindings();
-  writeJsonAtomically(lineagePath, lineage);
+  writeFinalizeLineageExact(lineagePath, {
+    expectedEntries: existing.entries,
+    nextEntries: lineage,
+  });
   return {
     status: gate.decision,
     exitCode: 0,