owlrunkit 0.14.0 → 0.15.1

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

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
 import {
   existsSync,
+  lstatSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   realpathSync,
   renameSync,
   rmSync,
@@ -12,7 +14,7 @@ import { isAbsolute, relative, resolve, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const CONTRACT_VERSION = "0.2";
-export const CORE_VERSION = "0.14.0";
+export const CORE_VERSION = "0.15.1";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
@@ -72,6 +74,8 @@ const CORE_FILES = [
   "schemas/visual-smoke-request-v1.schema.json",
   "schemas/visual-smoke-result-v1.schema.json",
   "schemas/verification-context-v1.schema.json",
+  "schemas/verification-finalize-attempt-v1.schema.json",
+  "schemas/verification-preflight-v1.schema.json",
   "schemas/verification-plan-v1.schema.json",
   "schemas/verification-receipt-v2.schema.json",
   "schemas/verify-plan-request-v1.schema.json",
@@ -136,6 +140,22 @@ function migrationReceiptName(migration, fromCore, toCore) {
   return `config-v02-core-refresh-${from}-to-${to}.json`;
 }
 
+function writeMigrationReceiptAppendOnly(receiptsRoot, baseName, receipt) {
+  const bytes = `${JSON.stringify(receipt, null, 2)}\n`;
+  const stem = baseName.slice(0, -".json".length);
+  for (let attempt = 1; ; attempt += 1) {
+    const receiptName = attempt === 1
+      ? baseName
+      : `${stem}-attempt-${String(attempt).padStart(3, "0")}.json`;
+    try {
+      writeFileSync(resolve(receiptsRoot, receiptName), bytes, { flag: "wx" });
+      return receiptName;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+  }
+}
+
 function migrateProjectConfig({ runtimeRoot, configPath, config, migration }) {
   validateCoreIdentity(config.core);
   const next = projectConfig();
@@ -150,8 +170,11 @@ function migrateProjectConfig({ runtimeRoot, configPath, config, migration }) {
   };
   const receiptsRoot = resolve(runtimeRoot, "config-migration-receipts");
   mkdirSync(receiptsRoot, { recursive: true });
-  const receiptName = migrationReceiptName(migration, config.core, next.core);
-  atomicWriteJson(resolve(receiptsRoot, receiptName), receipt);
+  const receiptName = writeMigrationReceiptAppendOnly(
+    receiptsRoot,
+    migrationReceiptName(migration, config.core, next.core),
+    receipt,
+  );
   atomicWriteJson(configPath, next);
   return `${RUNTIME_ROOT}/config-migration-receipts/${receiptName}`;
 }
@@ -211,9 +234,15 @@ export function validateLeaseOwnedPaths(paths) {
 
 export function validateExecutionPin({ expected, actual } = {}) {
   const fields = ["contractVersion", "coreVersion", "coreManifestSha256", "coreSourceRef"];
-  const malformed = fields.filter((field) => typeof expected?.[field] !== "string" || typeof actual?.[field] !== "string");
-  if (malformed.length > 0) {
-    return { status: "invalid_input", exitCode: 3, issues: malformed.map((field) => `missing engine pin field: ${field}`) };
+  try {
+    validateCoreIdentity(expected, { requireSourceBinding: false });
+    validateCoreIdentity(actual, { requireSourceBinding: false });
+  } catch (error) {
+    return {
+      status: "invalid_input",
+      exitCode: 3,
+      issues: [error instanceof Error ? `invalid engine pin: ${error.message}` : String(error)],
+    };
   }
   const issues = fields.filter((field) => expected[field] !== actual[field]).map((field) => `${field} changed during execution`);
   return issues.length === 0
@@ -221,11 +250,27 @@ export function validateExecutionPin({ expected, actual } = {}) {
     : { status: "engine_changed_during_execution", exitCode: 2, issues };
 }
 
-function validateCoreIdentity(core) {
+function validateCoreIdentity(core, { requireSourceBinding = true } = {}) {
   if (!isRecord(core)) throw new Error("Core identity must be an object.");
+  const coreKeys = ["contractVersion", "coreManifestSha256", "coreSourceRef", "coreVersion"];
+  const unsupportedCoreKeys = Object.keys(core).filter(key => !coreKeys.includes(key));
+  if (unsupportedCoreKeys.length > 0) {
+    throw new Error(`Core identity contains unsupported field: ${unsupportedCoreKeys[0]}`);
+  }
   if (typeof core.contractVersion !== "string" || typeof core.coreVersion !== "string") throw new Error("Core identity requires contractVersion and coreVersion.");
+  if (!new Set(["0.1", CONTRACT_VERSION]).has(core.contractVersion)) {
+    throw new Error("Core identity contractVersion must be a supported RunKit contract version.");
+  }
+  if (!/^\d+\.\d+\.\d+$/u.test(core.coreVersion)) {
+    throw new Error("Core identity coreVersion must be a three-part semantic version.");
+  }
   if (!isSha256Ref(core.coreManifestSha256)) throw new Error("Core identity requires coreManifestSha256.");
-  if (typeof core.coreSourceRef !== "string" || core.coreSourceRef.length === 0) throw new Error("Core identity requires coreSourceRef.");
+  if (typeof core.coreSourceRef !== "string" || core.coreSourceRef.length === 0) {
+    throw new Error("Core identity coreSourceRef must be a non-empty string.");
+  }
+  if (requireSourceBinding && core.coreSourceRef !== `artifact:${core.coreManifestSha256}`) {
+    throw new Error("Core identity coreSourceRef must bind coreManifestSha256.");
+  }
 }
 
 export function validateProjectConfigV2(config) {
@@ -258,10 +303,207 @@ export function validateProjectConfigV2(config) {
   }
 }
 
+function inspectTrustedCloseout(executionRoot, runId) {
+  const closeoutPath = resolve(executionRoot, "closeout-receipt.json");
+  try {
+    const closeoutStat = lstatSync(closeoutPath);
+    if (closeoutStat.isSymbolicLink() || !closeoutStat.isFile()) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: [`Closeout receipt must be a regular file: ${runId}`],
+      };
+    }
+    const closeout = JSON.parse(readFileSync(closeoutPath, "utf8"));
+    if (closeout?.artifact?.payload?.runId !== runId) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: [`Closeout receipt runId mismatch: ${runId}`],
+      };
+    }
+    const artifactGate = validateCoreArtifact(closeout.artifact);
+    if (!artifactGate.valid) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: artifactGate.issues.map(issue => `Closeout receipt is invalid: ${runId}: ${issue}`),
+      };
+    }
+    if (closeout.acceptanceSha256 !== artifactGate.acceptanceSha256
+      || closeout.artifactSha256 !== artifactGate.artifactSha256) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: [`Closeout receipt hash mismatch: ${runId}`],
+      };
+    }
+    const payload = closeout.artifact.payload;
+    if (!new Set(["accepted", "rejected", "blocked"]).has(payload.decision)
+      || payload.authorizationGranted !== false) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: [`Closeout receipt decision or authorization is invalid: ${runId}`],
+      };
+    }
+    const expectedPayloadKeys = payload.decision === "accepted"
+      ? ["authorizationGranted", "decision", "runId", "verification"]
+      : ["authorizationGranted", "decision", "runId"];
+    const unsupportedPayloadKeys = Object.keys(payload)
+      .filter(key => !expectedPayloadKeys.includes(key));
+    if (unsupportedPayloadKeys.length > 0) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: [
+          `Closeout receipt payload contains unsupported field: ${runId}: ${unsupportedPayloadKeys[0]}`,
+        ],
+      };
+    }
+    const verificationIssues = acceptedCloseoutVerificationIssues(closeout.artifact);
+    if (verificationIssues.length > 0) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: verificationIssues.map(issue => `Closeout receipt is invalid: ${runId}: ${issue}`),
+      };
+    }
+    const pinPath = resolve(executionRoot, "engine-pin.json");
+    const pinStat = lstatSync(pinPath);
+    if (pinStat.isSymbolicLink() || !pinStat.isFile()) {
+      return {
+        trusted: false,
+        decision: null,
+        issues: [`Execution engine pin must be a regular file: ${runId}`],
+      };
+    }
+    const pinGate = validateExecutionPin({
+      expected: JSON.parse(readFileSync(pinPath, "utf8")),
+      actual: closeout.artifact.core,
+    });
+    if (pinGate.status !== "valid") {
+      return {
+        trusted: false,
+        decision: null,
+        issues: pinGate.issues.map(issue => `Closeout engine pin mismatch: ${runId}: ${issue}`),
+      };
+    }
+    return {
+      trusted: true,
+      decision: payload.decision,
+      issues: [],
+    };
+  } catch (error) {
+    return {
+      trusted: false,
+      decision: null,
+      issues: [
+        `Closeout receipt or engine pin is invalid: ${runId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      ],
+    };
+  }
+}
+
+export function inspectProjectUpgradeSafety({ workspaceRoot } = {}) {
+  if (typeof workspaceRoot !== "string" || workspaceRoot.length === 0) {
+    throw new Error("workspaceRoot is required.");
+  }
+  const root = realpathSync(workspaceRoot);
+  const executionsRoot = resolve(root, RUNTIME_ROOT, "executions");
+  if (!existsSync(executionsRoot)) {
+    return {
+      status: "safe",
+      activeRunIds: [],
+      activeLeaseIds: [],
+      issues: [],
+    };
+  }
+  const executionsStat = lstatSync(executionsRoot);
+  if (executionsStat.isSymbolicLink() || !executionsStat.isDirectory()) {
+    return {
+      status: "unsafe",
+      activeRunIds: [],
+      activeLeaseIds: [],
+      issues: ["RunKit executions root must be a regular directory."],
+    };
+  }
+  const activeRunIds = [];
+  const activeLeaseIds = [];
+  const issues = [];
+  const entries = readdirSync(executionsRoot, { withFileTypes: true })
+    .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) {
+      issues.push(`Execution directory must not be a symlink: ${entry.name}`);
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+    const executionRoot = resolve(executionsRoot, entry.name);
+    const closeoutPath = resolve(executionRoot, "closeout-receipt.json");
+    let skipHistoricalLeases = false;
+    if (!existsSync(closeoutPath)) {
+      activeRunIds.push(entry.name);
+    } else {
+      const closeout = inspectTrustedCloseout(executionRoot, entry.name);
+      issues.push(...closeout.issues);
+      skipHistoricalLeases = closeout.trusted
+        && new Set(["rejected", "blocked"]).has(closeout.decision);
+    }
+    if (skipHistoricalLeases) continue;
+    const leasesRoot = resolve(executionRoot, "leases");
+    if (!existsSync(leasesRoot)) continue;
+    const leasesStat = lstatSync(leasesRoot);
+    if (leasesStat.isSymbolicLink() || !leasesStat.isDirectory()) {
+      issues.push(`Lease directory must be a regular directory: ${entry.name}`);
+      continue;
+    }
+    const leaseEntries = readdirSync(leasesRoot, { withFileTypes: true })
+      .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const leaseEntry of leaseEntries) {
+      if (!leaseEntry.name.endsWith(".json")) continue;
+      if (leaseEntry.isSymbolicLink() || !leaseEntry.isFile()) {
+        issues.push(`Lease artifact must be a regular file: ${entry.name}/${leaseEntry.name}`);
+        continue;
+      }
+      try {
+        const lease = JSON.parse(readFileSync(resolve(leasesRoot, leaseEntry.name), "utf8"));
+        if (lease.state === "active") {
+          activeLeaseIds.push(`${entry.name}:${lease.workItemId ?? leaseEntry.name}`);
+        } else if (lease.state !== "released") {
+          issues.push(`Lease state is invalid: ${entry.name}/${leaseEntry.name}`);
+        }
+      } catch {
+        issues.push(`Lease artifact is invalid JSON: ${entry.name}/${leaseEntry.name}`);
+      }
+    }
+  }
+  return {
+    status: activeRunIds.length === 0
+      && activeLeaseIds.length === 0
+      && issues.length === 0
+      ? "safe"
+      : "unsafe",
+    activeRunIds,
+    activeLeaseIds,
+    issues,
+  };
+}
+
 function validateProducer(producer) {
   if (!isRecord(producer) || typeof producer.adapterKind !== "string" || typeof producer.adapterVersion !== "string") {
     throw new Error("Producer requires adapterKind and adapterVersion.");
   }
+  if (producer.adapterKind.length === 0 || producer.adapterVersion.length === 0) {
+    throw new Error("Producer adapterKind and adapterVersion must be non-empty strings.");
+  }
+  const producerKeys = ["adapterKind", "adapterVersion"];
+  const unsupportedProducerKeys = Object.keys(producer).filter(key => !producerKeys.includes(key));
+  if (unsupportedProducerKeys.length > 0) {
+    throw new Error(`Producer contains unsupported field: ${unsupportedProducerKeys[0]}`);
+  }
 }
 
 function validateExtensions(extensions) {
@@ -301,7 +543,18 @@ export function createCoreArtifact({ core = currentCoreIdentity(), producer, pay
 export function validateCoreArtifact(artifact) {
   try {
     if (!isRecord(artifact) || !new Set(["RunKitCoreArtifactV1", "RunKitCoreArtifactV2"]).has(artifact.schemaVersion)) throw new Error("Unsupported core artifact schemaVersion.");
+    const artifactKeys = ["core", "extensions", "payload", "producer", "schemaVersion"];
+    const unsupportedArtifactKeys = Object.keys(artifact).filter(key => !artifactKeys.includes(key));
+    if (unsupportedArtifactKeys.length > 0) {
+      throw new Error(`Core artifact contains unsupported field: ${unsupportedArtifactKeys[0]}`);
+    }
     validateCoreIdentity(artifact.core);
+    const expectedContractVersion = artifact.schemaVersion === "RunKitCoreArtifactV1"
+      ? "0.1"
+      : CONTRACT_VERSION;
+    if (artifact.core.contractVersion !== expectedContractVersion) {
+      throw new Error(`Core artifact ${artifact.schemaVersion} requires contractVersion ${expectedContractVersion}.`);
+    }
     validateProducer(artifact.producer);
     if (!isRecord(artifact.payload)) throw new Error("Core artifact payload must be an object.");
     validateExtensions(artifact.extensions);
@@ -340,10 +593,10 @@ export async function initializeProjectRunKit({ workspaceRoot } = {}) {
   const runtimeRoot = resolve(root, RUNTIME_ROOT);
   const remainder = relative(root, runtimeRoot);
   if (remainder.startsWith("..") || isAbsolute(remainder)) throw new Error("Runtime root escapes the workspace.");
-  mkdirSync(resolve(runtimeRoot, "executions"), { recursive: true });
   const configPath = resolve(runtimeRoot, "config.json");
   const profilesPath = resolve(runtimeRoot, "profiles.json");
   if (!existsSync(configPath)) {
+    mkdirSync(resolve(runtimeRoot, "executions"), { recursive: true });
     atomicWriteJson(configPath, projectConfig());
   } else {
     const config = JSON.parse(readFileSync(configPath, "utf8"));
@@ -355,6 +608,16 @@ export async function initializeProjectRunKit({ workspaceRoot } = {}) {
     if (config.schemaVersion === "OwlCodaRunKitConfigV2" && currentGate.status === "valid") {
       // The project already points at this exact Core identity.
     } else if (config.schemaVersion === "OwlCodaRunKitConfigV1" && config.core?.contractVersion === "0.1") {
+      const safety = inspectProjectUpgradeSafety({ workspaceRoot: root });
+      if (safety.status !== "safe") {
+        return {
+          ...safety,
+          status: "upgrade_blocked_active_execution",
+          exitCode: 2,
+          runtimeRoot: RUNTIME_ROOT,
+          core: current,
+        };
+      }
       const migrationReceipt = migrateProjectConfig({
         runtimeRoot,
         configPath,
@@ -366,6 +629,16 @@ export async function initializeProjectRunKit({ workspaceRoot } = {}) {
       }
       return { status: "upgraded", exitCode: 0, runtimeRoot: RUNTIME_ROOT, core: current, migrationReceipt };
     } else if (config.schemaVersion === "OwlCodaRunKitConfigV2" && config.core?.contractVersion === CONTRACT_VERSION) {
+      const safety = inspectProjectUpgradeSafety({ workspaceRoot: root });
+      if (safety.status !== "safe") {
+        return {
+          ...safety,
+          status: "upgrade_blocked_active_execution",
+          exitCode: 2,
+          runtimeRoot: RUNTIME_ROOT,
+          core: current,
+        };
+      }
       const migrationReceipt = migrateProjectConfig({
         runtimeRoot,
         configPath,
@@ -380,6 +653,7 @@ export async function initializeProjectRunKit({ workspaceRoot } = {}) {
       throw new Error(`Unsupported project config migration: ${config.schemaVersion ?? "missing schemaVersion"}.`);
     }
   }
+  mkdirSync(resolve(runtimeRoot, "executions"), { recursive: true });
   if (!existsSync(profilesPath)) {
     writeFileSync(profilesPath, `${JSON.stringify({ schemaVersion: "OwlCodaRunKitProfilesV1", profiles: [] }, null, 2)}\n`);
   }