owlrunkit 0.18.4 → 0.19.1

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

@@ -15,7 +15,19 @@ import {
   persistQuickInputArtifact,
   persistQuickReceipt,
 } from "./quick-receipt.mjs";
-import { captureWorkspaceSnapshot } from "./quick-workspace-snapshot.mjs";
+import {
+  inspectQuickIsolation,
+  prepareQuickIsolation,
+  removeQuickIsolation,
+} from "./quick-isolation.mjs";
+import {
+  captureWorkspaceSnapshot,
+  workspaceSourceStateFingerprint,
+} from "./quick-workspace-snapshot.mjs";
+import {
+  captureRuntimeTransition,
+  runtimeReportPath,
+} from "./runtime-transition.mjs";
 
 function shellQuote(value) {
   return `'${String(value).replaceAll("'", `'"'"'`)}'`;
@@ -25,7 +37,7 @@ function quickAttestCommand(workspaceRoot, receiptPath) {
   return `npx --no-install owlrunkit quick-attest --workspace ${shellQuote(workspaceRoot)} --receipt ${shellQuote(receiptPath)}`;
 }
 
-function runExactCommand({ executable, argv, cwd, stdinPath, stdoutFd, stderrFd }) {
+function runExactCommand({ executable, argv, cwd, stdinPath, stdoutFd, stderrFd, env }) {
   return new Promise((resolve) => {
     let settled = false;
     let stdinFd;
@@ -38,7 +50,7 @@ function runExactCommand({ executable, argv, cwd, stdinPath, stdoutFd, stderrFd
         cwd,
         shell: false,
         stdio: [stdinFd ?? "ignore", stdoutFd, stderrFd],
-        env: process.env,
+        env: env ?? process.env,
       });
     } catch (error) {
       if (stdinFd !== undefined) closeSync(stdinFd);
@@ -69,7 +81,82 @@ function inputArtifactResult(stdinArtifact) {
     : { inputArtifacts: { stdin: stdinArtifact } };
 }
 
-export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFile }) {
+function mutationTruth({ workspaceBefore, workspaceAfter, isolationResult, cleanupStatus }) {
+  const workspaceSourceChanged = workspaceSourceStateFingerprint(workspaceBefore)
+    !== workspaceSourceStateFingerprint(workspaceAfter);
+  const boundIgnoredChanged = workspaceBefore.ignoredPathsBound === true
+    && workspaceBefore.ignoredPathsFingerprint !== workspaceAfter.ignoredPathsFingerprint;
+  const dependencyChanged = isolationResult?.dependencyChanged === true;
+  const consumerSourceChanged = (isolationResult?.consumerDelta.sourcePaths.length ?? 0) > 0;
+  const cleanupFailed = cleanupStatus === "cleanup_failed";
+  const issueCodes = [
+    ...(workspaceSourceChanged ? ["source_mutated_during_verification"] : []),
+    ...(boundIgnoredChanged ? ["bound_ignored_path_mutated_during_verification"] : []),
+    ...(dependencyChanged ? ["dependency_environment_mutated_during_verification"] : []),
+    ...(consumerSourceChanged ? ["consumer_source_mutated_during_verification"] : []),
+    ...(cleanupFailed ? ["quick_isolation_cleanup_failed"] : []),
+  ];
+  const decisions = [
+    ...(workspaceSourceChanged ? ["invalidated_by_command_source_mutation"] : []),
+    ...(boundIgnoredChanged ? ["invalidated_by_bound_ignored_mutation"] : []),
+    ...(dependencyChanged ? ["invalidated_by_dependency_environment_mutation"] : []),
+    ...(consumerSourceChanged ? ["invalidated_by_consumer_source_mutation"] : []),
+    ...(cleanupFailed ? ["invalidated_by_isolation_cleanup_failure"] : []),
+  ];
+  return {
+    mutationDecision: decisions.length === 0
+      ? "source_unchanged"
+      : decisions.length === 1
+        ? decisions[0]
+        : "invalidated_by_multiple_mutations",
+    issueCodes,
+    mutationClasses: {
+      workspaceSource: workspaceSourceChanged ? "changed" : "unchanged",
+      boundIgnoredPaths: workspaceBefore.ignoredPathsBound !== true
+        ? "not_bound"
+        : boundIgnoredChanged ? "changed" : "unchanged",
+      dependencyEnvironment: isolationResult?.dependencyEnvironmentAfter === null
+        || isolationResult?.dependencyEnvironmentAfter === undefined
+        ? "not_bound"
+        : dependencyChanged ? "changed" : "unchanged",
+      consumerSource: isolationResult === null
+        ? "not_isolated"
+        : consumerSourceChanged ? "changed" : "unchanged",
+      consumerIgnoredArtifacts: (isolationResult?.consumerDelta.ignoredPaths.length ?? 0) > 0
+        ? "changed_and_discarded"
+        : isolationResult === null ? "not_isolated" : "none",
+    },
+  };
+}
+
+function isolationReceipt(isolation, isolationResult, cleanupStatus) {
+  if (isolation === null) return null;
+  return {
+    schemaVersion: isolation.schemaVersion,
+    mode: "temporary_consumer",
+    consumerRoot: isolation.consumerRoot,
+    sourceCopy: {
+      fileCount: isolation.sourceCopy.fileCount,
+      totalBytes: isolation.sourceCopy.totalBytes,
+      fingerprint: isolation.sourceCopy.fingerprint,
+    },
+    cacheEnvironmentVariables: isolation.environment.environmentVariables,
+    dependencyEnvironment: isolation.dependencyEnvironment,
+    dependencyEnvironmentAfter: isolationResult.dependencyEnvironmentAfter,
+    consumerDelta: isolationResult.consumerDelta,
+    cleanupStatus,
+  };
+}
+
+export async function runQuickVerification({
+  workspaceRoot,
+  commandArgv,
+  stdinFile,
+  isolate = false,
+  dependencyRoot,
+  ignoredPaths = [],
+  captureRuntime = false,
+}) {
   if (!Array.isArray(commandArgv) || commandArgv.length === 0 || !commandArgv.every((value) => typeof value === "string")) {
     return {
       status: "quick_verification_input_invalid",
@@ -89,6 +176,22 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
       authorizationGranted: false,
     };
   }
+  if (dependencyRoot !== undefined && isolate !== true) {
+    return {
+      status: "quick_verification_input_invalid",
+      exitCode: 3,
+      issues: ["--dependency-root requires --isolate."],
+      authorizationGranted: false,
+    };
+  }
+  if (!Array.isArray(ignoredPaths) || ignoredPaths.some(value => typeof value !== "string")) {
+    return {
+      status: "quick_verification_input_invalid",
+      exitCode: 3,
+      issues: ["--bind-ignored must contain literal workspace-relative paths."],
+      authorizationGranted: false,
+    };
+  }
 
   let stdinBytes;
   if (stdinFile !== undefined) {
@@ -119,8 +222,9 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
   let store;
   let stdinArtifact = null;
   let persistedStdinPath;
+  let isolation = null;
   try {
-    workspaceBefore = captureWorkspaceSnapshot(root);
+    workspaceBefore = captureWorkspaceSnapshot(root, { ignoredPaths });
     store = createQuickReceiptStore(root);
     if (stdinBytes !== undefined) {
       const persistedInput = persistQuickInputArtifact({
@@ -131,7 +235,15 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
       stdinArtifact = persistedInput.artifact;
       persistedStdinPath = persistedInput.inputPath;
     }
+    if (isolate === true) {
+      isolation = prepareQuickIsolation({ workspaceRoot: root, dependencyRoot });
+      const stableSource = captureWorkspaceSnapshot(root, { ignoredPaths });
+      if (stableSource.sourceFingerprint !== workspaceBefore.sourceFingerprint) {
+        throw new Error("Source workspace changed while the temporary consumer was being prepared.");
+      }
+    }
   } catch (error) {
+    if (isolation !== null) removeQuickIsolation(isolation);
     if (store !== undefined) closeQuickOutputFiles(store);
     return {
       status: "quick_verification_input_invalid",
@@ -142,22 +254,43 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
   }
 
   const [executable, ...argv] = commandArgv;
+  const executionCwd = isolation?.consumerRoot ?? root;
+  const expectedRuntimeReportPath = captureRuntime
+    ? runtimeReportPath(store.receiptRoot)
+    : null;
+  const executionEnvironment = isolation === null
+    ? { ...process.env }
+    : { ...process.env, ...isolation.environment.overrides };
+  delete executionEnvironment.OWLRUNKIT_RUNTIME_REPORT;
+  if (expectedRuntimeReportPath !== null) {
+    executionEnvironment.OWLRUNKIT_RUNTIME_REPORT = expectedRuntimeReportPath;
+  }
   const startedAt = new Date().toISOString();
   const execution = await runExactCommand({
     executable,
     argv,
-    cwd: root,
+    cwd: executionCwd,
     stdinPath: persistedStdinPath,
     stdoutFd: store.stdoutFd,
     stderrFd: store.stderrFd,
+    env: executionEnvironment,
   });
   closeQuickOutputFiles(store);
   const finishedAt = new Date().toISOString();
 
   let workspaceAfter;
+  let isolationResult = null;
+  let cleanupStatus = "not_required";
   try {
-    workspaceAfter = captureWorkspaceSnapshot(root);
+    if (isolation !== null) {
+      isolationResult = inspectQuickIsolation(isolation);
+      cleanupStatus = removeQuickIsolation(isolation);
+    }
+    workspaceAfter = captureWorkspaceSnapshot(root, { ignoredPaths });
   } catch (error) {
+    if (isolation !== null && cleanupStatus === "not_required") {
+      removeQuickIsolation(isolation);
+    }
     return {
       status: "quick_verification_source_mutated",
       exitCode: 2,
@@ -168,16 +301,23 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
     };
   }
 
-  const sourceMutated = workspaceBefore.sourceFingerprint !== workspaceAfter.sourceFingerprint;
-  const issueCodes = [];
-  if (sourceMutated) issueCodes.push("source_mutated_during_verification");
+  const mutation = mutationTruth({
+    workspaceBefore,
+    workspaceAfter,
+    isolationResult,
+    cleanupStatus,
+  });
+  const sourceMutated = mutation.mutationDecision !== "source_unchanged";
+  const receiptV3 = isolate === true || ignoredPaths.length > 0;
   let persisted;
   try {
     persisted = persistQuickReceipt({
       workspaceRoot: root,
       store,
       receipt: {
-      schemaVersion: stdinArtifact === null
+      schemaVersion: receiptV3
+        ? "OwlCodaQuickVerificationReceiptV3"
+        : stdinArtifact === null
         ? "OwlCodaQuickVerificationReceiptV1"
         : "OwlCodaQuickVerificationReceiptV2",
       receiptId: store.receiptId,
@@ -192,8 +332,15 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
       exactCommand: {
         executable,
         argv,
-        cwd: root,
+        cwd: executionCwd,
       },
+      ...(receiptV3
+        ? {
+            sourceWorkspaceRoot: root,
+            executionIsolation: isolationReceipt(isolation, isolationResult, cleanupStatus),
+            mutationClasses: mutation.mutationClasses,
+          }
+        : {}),
       ...(stdinArtifact === null
         ? {}
         : { inputArtifacts: { stdin: stdinArtifact } }),
@@ -209,10 +356,8 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
         signal: execution.signal,
       },
       workspaceAfter,
-      mutationDecision: sourceMutated
-        ? "invalidated_by_command_source_mutation"
-        : "source_unchanged",
-        issueCodes,
+      mutationDecision: mutation.mutationDecision,
+        issueCodes: mutation.issueCodes,
       },
     });
   } catch (error) {
@@ -223,10 +368,8 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
       receiptSha256: null,
       sourceFingerprint: workspaceAfter.sourceFingerprint,
       commandExitCode: execution.exitCode,
-      mutationDecision: sourceMutated
-        ? "invalidated_by_command_source_mutation"
-        : "source_unchanged",
-      issueCodes: [...issueCodes, "quick_receipt_store_invalid"],
+      mutationDecision: mutation.mutationDecision,
+      issueCodes: [...mutation.issueCodes, "quick_receipt_store_invalid"],
       ...inputArtifactResult(stdinArtifact),
       issues: [error instanceof Error ? error.message : String(error)],
       nextAllowedAction: "repair_quick_receipt_store_and_rerun",
@@ -234,7 +377,25 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
     };
   }
 
-  const { outputSummary } = persisted;
+  const { outputSummary, evidenceStorage } = persisted;
+  let runtimeTransition = null;
+  if (expectedRuntimeReportPath !== null) {
+    try {
+      runtimeTransition = captureRuntimeTransition({
+        workspaceRoot: root,
+        quickReceiptPath: persisted.receiptPath,
+        runtimeReportPath: expectedRuntimeReportPath,
+      });
+    } catch (error) {
+      runtimeTransition = {
+        status: "runtime_transition_invalid",
+        receiptPath: null,
+        issues: [error instanceof Error ? error.message : String(error)],
+        authorizationGranted: false,
+      };
+    }
+  }
+  const runtimeFields = runtimeTransition === null ? {} : { runtimeTransition };
 
   if (sourceMutated) {
     const attestCommand = quickAttestCommand(root, persisted.receiptPath);
@@ -245,16 +406,42 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
       receiptSha256: persisted.receiptSha256,
       sourceFingerprint: workspaceAfter.sourceFingerprint,
       commandExitCode: execution.exitCode,
-      mutationDecision: "invalidated_by_command_source_mutation",
-      issueCodes,
+      mutationDecision: mutation.mutationDecision,
+      issueCodes: mutation.issueCodes,
       ...inputArtifactResult(stdinArtifact),
       outputSummary,
+      evidenceStorage,
+      ...runtimeFields,
       attestCommand,
       issues: [],
       nextAllowedAction: "restore_source_or_run_a_new_quick_verification",
       authorizationGranted: false,
     };
   }
+  if (runtimeTransition?.status === "runtime_transition_invalid") {
+    const attestCommand = quickAttestCommand(root, persisted.receiptPath);
+    return {
+      status: "quick_verification_runtime_truth_invalid",
+      exitCode: 1,
+      quickVerificationStatus: execution.launchError || execution.exitCode !== 0
+        ? "quick_verification_failed"
+        : "quick_verification_passed",
+      receiptPath: persisted.receiptPath,
+      receiptSha256: persisted.receiptSha256,
+      sourceFingerprint: workspaceAfter.sourceFingerprint,
+      commandExitCode: execution.exitCode,
+      mutationDecision: "source_unchanged",
+      issueCodes: mutation.issueCodes,
+      ...inputArtifactResult(stdinArtifact),
+      outputSummary,
+      evidenceStorage,
+      runtimeTransition,
+      attestCommand,
+      issues: runtimeTransition.issues,
+      nextAllowedAction: "repair_runtime_report_and_run_a_new_quick_verification",
+      authorizationGranted: false,
+    };
+  }
   if (execution.launchError || execution.exitCode !== 0) {
     const attestCommand = quickAttestCommand(root, persisted.receiptPath);
     return {
@@ -265,9 +452,11 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
       sourceFingerprint: workspaceAfter.sourceFingerprint,
       commandExitCode: execution.exitCode,
       mutationDecision: "source_unchanged",
-      issueCodes,
+      issueCodes: mutation.issueCodes,
       ...inputArtifactResult(stdinArtifact),
       outputSummary,
+      evidenceStorage,
+      ...runtimeFields,
       attestCommand,
       issues: execution.launchError ? [execution.launchError] : [],
       nextAllowedAction: "inspect_output_and_rerun",
@@ -283,9 +472,11 @@ export async function runQuickVerification({ workspaceRoot, commandArgv, stdinFi
     sourceFingerprint: workspaceAfter.sourceFingerprint,
     commandExitCode: 0,
     mutationDecision: "source_unchanged",
-    issueCodes,
+    issueCodes: mutation.issueCodes,
     ...inputArtifactResult(stdinArtifact),
     outputSummary,
+    evidenceStorage,
+    ...runtimeFields,
     attestCommand,
     issues: [],
     nextAllowedAction: attestCommand,

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

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

package/scripts/runkit-contract/runkit-bootstrap.mjs

@@ -12,6 +12,7 @@ import { resolveProjectCli } from "./project-cli-resolver.mjs";
 
 const CURRENT_PACKAGE_COMMANDS = new Set([
   "adopt",
+  "bootstrap",
   "core-successor",
   "fleet",
   "init",