owlrunkit 0.13.0

package/scripts/runkit-contract/quick-verify.mjs

@@ -0,0 +1,201 @@
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+
+import { currentCoreIdentity } from "./core-contract.mjs";
+import {
+  closeQuickOutputFiles,
+  createQuickReceiptStore,
+  persistQuickReceipt,
+} from "./quick-receipt.mjs";
+import { captureWorkspaceSnapshot } from "./quick-workspace-snapshot.mjs";
+
+function runExactCommand({ executable, argv, cwd, stdoutFd, stderrFd }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const child = spawn(executable, argv, {
+      cwd,
+      shell: false,
+      stdio: ["ignore", stdoutFd, stderrFd],
+      env: process.env,
+    });
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      resolve({ exitCode: null, signal: null, launchError: error.message });
+    });
+    child.once("close", (exitCode, signal) => {
+      if (settled) return;
+      settled = true;
+      resolve({ exitCode, signal, launchError: null });
+    });
+  });
+}
+
+export async function runQuickVerification({ workspaceRoot, commandArgv }) {
+  if (!Array.isArray(commandArgv) || commandArgv.length === 0 || !commandArgv.every((value) => typeof value === "string")) {
+    return {
+      status: "quick_verification_input_invalid",
+      exitCode: 3,
+      issues: ["An exact command is required after --."],
+      authorizationGranted: false,
+    };
+  }
+  let root;
+  try {
+    root = realpathSync(workspaceRoot);
+  } catch {
+    return {
+      status: "quick_verification_input_invalid",
+      exitCode: 3,
+      issues: ["Workspace does not exist."],
+      authorizationGranted: false,
+    };
+  }
+
+  let workspaceBefore;
+  let store;
+  try {
+    workspaceBefore = captureWorkspaceSnapshot(root);
+    store = createQuickReceiptStore(root);
+  } catch (error) {
+    return {
+      status: "quick_verification_input_invalid",
+      exitCode: 3,
+      issues: [error instanceof Error ? error.message : String(error)],
+      authorizationGranted: false,
+    };
+  }
+
+  const [executable, ...argv] = commandArgv;
+  const startedAt = new Date().toISOString();
+  const execution = await runExactCommand({
+    executable,
+    argv,
+    cwd: root,
+    stdoutFd: store.stdoutFd,
+    stderrFd: store.stderrFd,
+  });
+  closeQuickOutputFiles(store);
+  const finishedAt = new Date().toISOString();
+
+  let workspaceAfter;
+  try {
+    workspaceAfter = captureWorkspaceSnapshot(root);
+  } catch (error) {
+    return {
+      status: "quick_verification_source_mutated",
+      exitCode: 2,
+      receiptPath: null,
+      receiptSha256: null,
+      issues: [error instanceof Error ? error.message : String(error)],
+      authorizationGranted: false,
+    };
+  }
+
+  const sourceMutated = workspaceBefore.sourceFingerprint !== workspaceAfter.sourceFingerprint;
+  const issueCodes = ["quick_ignored_artifact_unbound"];
+  if (sourceMutated) issueCodes.push("source_mutated_during_verification");
+  let persisted;
+  try {
+    persisted = persistQuickReceipt({
+      workspaceRoot: root,
+      store,
+      receipt: {
+      schemaVersion: "OwlCodaQuickVerificationReceiptV1",
+      receiptId: store.receiptId,
+      assurance: "captured_verification",
+      authorizationGranted: false,
+      coreIdentity: {
+        contractVersion: currentCoreIdentity().contractVersion,
+        coreVersion: currentCoreIdentity().coreVersion,
+        coreManifestSha256: currentCoreIdentity().coreManifestSha256,
+      },
+      workspaceBefore,
+      exactCommand: {
+        executable,
+        argv,
+        cwd: root,
+      },
+      verificationContext: {
+        platform: process.platform,
+        architecture: process.arch,
+        runtime: process.version,
+      },
+      startedAt,
+      finishedAt,
+      exitResult: {
+        exitCode: execution.exitCode,
+        signal: execution.signal,
+      },
+      workspaceAfter,
+      mutationDecision: sourceMutated
+        ? "invalidated_by_command_source_mutation"
+        : "source_unchanged",
+        issueCodes,
+      },
+    });
+  } catch (error) {
+    return {
+      status: "quick_verification_control_invalid",
+      exitCode: 1,
+      receiptPath: null,
+      receiptSha256: null,
+      sourceFingerprint: workspaceAfter.sourceFingerprint,
+      commandExitCode: execution.exitCode,
+      mutationDecision: sourceMutated
+        ? "invalidated_by_command_source_mutation"
+        : "source_unchanged",
+      issueCodes: [...issueCodes, "quick_receipt_store_invalid"],
+      issues: [error instanceof Error ? error.message : String(error)],
+      nextAllowedAction: "repair_quick_receipt_store_and_rerun",
+      authorizationGranted: false,
+    };
+  }
+
+  if (sourceMutated) {
+    return {
+      status: "quick_verification_source_mutated",
+      exitCode: 2,
+      receiptPath: persisted.receiptPath,
+      receiptSha256: persisted.receiptSha256,
+      sourceFingerprint: workspaceAfter.sourceFingerprint,
+      commandExitCode: execution.exitCode,
+      mutationDecision: "invalidated_by_command_source_mutation",
+      issueCodes,
+      attestCommand: `owlcoda attest ${persisted.receiptPath}`,
+      issues: [],
+      nextAllowedAction: "restore_source_or_run_a_new_quick_verification",
+      authorizationGranted: false,
+    };
+  }
+  if (execution.launchError || execution.exitCode !== 0) {
+    return {
+      status: "quick_verification_failed",
+      exitCode: 1,
+      receiptPath: persisted.receiptPath,
+      receiptSha256: persisted.receiptSha256,
+      sourceFingerprint: workspaceAfter.sourceFingerprint,
+      commandExitCode: execution.exitCode,
+      mutationDecision: "source_unchanged",
+      issueCodes,
+      attestCommand: `owlcoda attest ${persisted.receiptPath}`,
+      issues: execution.launchError ? [execution.launchError] : [],
+      nextAllowedAction: "inspect_output_and_rerun",
+      authorizationGranted: false,
+    };
+  }
+  return {
+    status: "quick_verification_passed",
+    exitCode: 0,
+    receiptPath: persisted.receiptPath,
+    receiptSha256: persisted.receiptSha256,
+    sourceFingerprint: workspaceAfter.sourceFingerprint,
+    commandExitCode: 0,
+    mutationDecision: "source_unchanged",
+    issueCodes,
+    attestCommand: `owlcoda attest ${persisted.receiptPath}`,
+    issues: [],
+    nextAllowedAction: `owlcoda attest ${persisted.receiptPath}`,
+    authorizationGranted: false,
+  };
+}

package/scripts/runkit-contract/quick-workspace-snapshot.mjs

@@ -0,0 +1,3 @@
+export {
+  captureWorkspaceSnapshot,
+} from "../../packages/attest/src/workspace-snapshot.mjs";

package/scripts/runkit-contract/ready-for-commit.mjs

@@ -0,0 +1,188 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+import { validateCoreArtifact } from "./core-contract.mjs";
+import {
+  assertAllowedKeys,
+  isRecord,
+  loadActiveExecution,
+  readJson,
+  relativeToWorkspace,
+  repositoryActionsFalse,
+  resolveExistingArtifact,
+  sha256,
+  writeJsonExclusive,
+} from "./provenance-common.mjs";
+import { resolveProfileImpactProjection } from "./profile-impact.mjs";
+import { verifySnapshotEvidence, verifySnapshotFreshness } from "./snapshot.mjs";
+import { verifyDeliveryPacket } from "./source-fingerprint.mjs";
+import { validateVerificationReceiptGate } from "./verification-receipt-gate.mjs";
+
+const REQUEST_KEYS = [
+  "schemaVersion",
+  "deliveryPacketPath",
+  "verificationGateInputPath",
+  "roots",
+];
+
+function changedPaths(packet) {
+  const files = packet?.changedFiles?.files ?? packet?.changedFiles?.wholeFileSha256;
+  if (!isRecord(files) || Object.keys(files).length === 0) {
+    throw new Error("Delivery packet does not declare changed files.");
+  }
+  return Object.keys(files).sort();
+}
+
+function validateRequest(request) {
+  assertAllowedKeys(request, "Ready-for-commit request", REQUEST_KEYS);
+  if (request.schemaVersion !== "OwlCodaRunKitReadyForCommitRequestV1") {
+    throw new Error("Unsupported ready-for-commit request schemaVersion.");
+  }
+  if (typeof request.deliveryPacketPath !== "string" || request.deliveryPacketPath.length === 0) {
+    throw new Error("Ready-for-commit request requires deliveryPacketPath.");
+  }
+  if (typeof request.verificationGateInputPath !== "string" || request.verificationGateInputPath.length === 0) {
+    throw new Error("Ready-for-commit request requires verificationGateInputPath.");
+  }
+  if (!Array.isArray(request.roots) || request.roots.length === 0) {
+    throw new Error("Ready-for-commit request requires roots.");
+  }
+  const roles = new Set();
+  for (const root of request.roots) {
+    if (!isRecord(root)
+      || typeof root.role !== "string"
+      || root.role.length === 0
+      || typeof root.snapshotPath !== "string"
+      || root.snapshotPath.length === 0) {
+      throw new Error("Each ready root requires role and snapshotPath.");
+    }
+    if (roles.has(root.role)) throw new Error(`Duplicate ready root role: ${root.role}`);
+    roles.add(root.role);
+  }
+  if (!roles.has("candidate")) throw new Error("Ready-for-commit requires a candidate root snapshot.");
+}
+
+function verifyReleasedLeases(executionRoot) {
+  const leasesRoot = path.join(executionRoot, "leases");
+  const leases = readdirSync(leasesRoot, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => readJson(path.join(leasesRoot, entry.name)));
+  if (leases.length === 0) throw new Error("Ready-for-commit requires at least one released lease.");
+  if (leases.some((lease) => lease.state !== "released")) {
+    throw new Error("Ready-for-commit is not allowed while an active lease remains.");
+  }
+  return leases.map((lease) => lease.workItemId).sort();
+}
+
+function verifyCloseout({ executionRoot, runId, gateInputBytes, gate }) {
+  const closeoutPath = path.join(executionRoot, "closeout-receipt.json");
+  if (!existsSync(closeoutPath)) throw new Error("Accepted closeout receipt is required.");
+  const closeout = readJson(closeoutPath);
+  const artifactGate = validateCoreArtifact(closeout.artifact);
+  if (!artifactGate.valid) throw new Error(artifactGate.issues.join("; "));
+  if (closeout.acceptanceSha256 !== artifactGate.acceptanceSha256
+    || closeout.artifactSha256 !== artifactGate.artifactSha256) {
+    throw new Error("Closeout artifact hashes are invalid.");
+  }
+  const payload = closeout.artifact.payload;
+  if (payload.runId !== runId || payload.decision !== "accepted") {
+    throw new Error("Closeout does not accept the current execution.");
+  }
+  if (payload.authorizationGranted !== false) throw new Error("Closeout authorization must remain false.");
+  if (payload.verification?.gateInputSha256 !== sha256(gateInputBytes)) {
+    throw new Error("Closeout gate input hash does not match the requested gate input.");
+  }
+  if (payload.verification?.activeReceiptSha256 !== gate.activeReceiptSha256) {
+    throw new Error("Closeout active receipt does not match the current verification gate.");
+  }
+  return { closeoutPath, closeout };
+}
+
+export function runReadyForCommit({ workspaceRoot, runId, request }) {
+  validateRequest(request);
+  const { executionRoot, pinGate } = loadActiveExecution(workspaceRoot, runId);
+  if (pinGate.status !== "valid") return pinGate;
+  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 });
+  if (sourceGate.status !== "valid") {
+    return {
+      status: sourceGate.status,
+      exitCode: sourceGate.exitCode,
+      runId,
+      issues: sourceGate.issues,
+      authorizationGranted: false,
+    };
+  }
+  const gateInputPath = resolveExistingArtifact(
+    workspaceRoot,
+    request.verificationGateInputPath,
+    "verificationGateInputPath",
+  );
+  const gateInputBytes = readFileSync(gateInputPath);
+  const gateInput = JSON.parse(gateInputBytes.toString("utf8"));
+  const gate = validateVerificationReceiptGate(gateInput);
+  if (!gate.accepted || gate.lineage.active.receipt.runId !== runId) {
+    throw new Error("Verification gate does not accept the current execution.");
+  }
+  if (gate.sourceFingerprint !== sourceGate.recomputedFingerprint) {
+    throw new Error("Verification gate source fingerprint is stale.");
+  }
+  const profiles = readJson(path.join(workspaceRoot, ".owlcoda/runkit/profiles.json")).profiles;
+  const detailedProfileImpact = isRecord(gateInput.profileImpact)
+    && ("directProfileIds" in gateInput.profileImpact
+      || "transitiveProfileIds" in gateInput.profileImpact);
+  const currentProfileImpact = resolveProfileImpactProjection({
+    changedPaths: changedPaths(packet),
+    profiles,
+    detailed: detailedProfileImpact,
+  });
+  if (JSON.stringify(currentProfileImpact) !== JSON.stringify(gateInput.profileImpact)) {
+    throw new Error("Verification profile impact is stale.");
+  }
+  const releasedLeaseIds = verifyReleasedLeases(executionRoot);
+  const { closeoutPath } = verifyCloseout({ executionRoot, runId, gateInputBytes, gate });
+  const roots = request.roots.map((root) => {
+    const snapshotPath = resolveExistingArtifact(workspaceRoot, root.snapshotPath, "root snapshotPath");
+    const snapshot = readJson(snapshotPath);
+    const evidence = verifySnapshotEvidence({ workspaceRoot, runId, snapshot });
+    if (!evidence.valid) throw new Error(evidence.issues.join("; "));
+    const freshness = verifySnapshotFreshness(snapshot);
+    if (!freshness.valid) throw new Error(freshness.issues.join("; "));
+    return {
+      role: root.role,
+      snapshotPath: root.snapshotPath,
+      snapshotSha256: sha256(readFileSync(snapshotPath)),
+      targetRoot: snapshot.targetRoot,
+      head: freshness.current.head,
+      manifestFingerprint: freshness.current.manifestFingerprint,
+    };
+  });
+  const readyPath = path.join(executionRoot, "READY_FOR_COMMIT_RECEIPT.json");
+  const receipt = {
+    schemaVersion: "OwlCodaRunKitReadyForCommitReceiptV1",
+    runId,
+    status: "ready_for_commit",
+    sourceFingerprint: sourceGate.recomputedFingerprint,
+    activeReceiptSha256: gate.activeReceiptSha256,
+    verificationGateInputPath: request.verificationGateInputPath,
+    verificationGateInputSha256: sha256(gateInputBytes),
+    deliveryPacketPath: request.deliveryPacketPath,
+    deliveryPacketSha256: sha256(readFileSync(packetPath)),
+    closeoutReceiptPath: relativeToWorkspace(workspaceRoot, closeoutPath),
+    closeoutReceiptSha256: sha256(readFileSync(closeoutPath)),
+    releasedLeaseIds,
+    roots,
+    repositoryActions: repositoryActionsFalse(),
+    authorizationGranted: false,
+  };
+  writeJsonExclusive(readyPath, receipt);
+  return {
+    status: "ready_for_commit",
+    exitCode: 0,
+    runId,
+    readyReceiptPath: relativeToWorkspace(workspaceRoot, readyPath),
+    authorizationGranted: false,
+  };
+}