owlrunkit 0.15.1 → 0.16.1

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

@@ -4,33 +4,45 @@ import {
   lstatSync,
   mkdirSync,
   readFileSync,
-  readdirSync,
   realpathSync,
   renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { isAbsolute, relative, resolve, win32 } from "node:path";
+import { isAbsolute, relative, resolve, sep, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseProjectControlState } from "./project-control-parser.mjs";
 
 export const CONTRACT_VERSION = "0.2";
-export const CORE_VERSION = "0.15.1";
+export const CORE_VERSION = "0.16.1";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
   "acceptance-evidence.mjs",
+  "assurance-router.mjs",
+  "core-successor.mjs",
   "coverage-adoption.mjs",
   "core-contract.mjs",
   "delivery-create.mjs",
   "delivery-selection.mjs",
+  "deployment-workflow.mjs",
+  "fleet-discovery.mjs",
   "finalize.mjs",
+  "formal-workflow.mjs",
+  "human-status.mjs",
   "inspect-presentation.mjs",
+  "install-codex-skill.mjs",
   "lease-lifecycle.mjs",
   "lifecycle-orchestration.mjs",
   "offline-store.mjs",
   "onboarding-doctor.mjs",
+  "owner-authority-trust.mjs",
+  "owner-deployment-decision.mjs",
   "profile-impact.mjs",
   "profile-onboarding.mjs",
+  "project-cli-resolver.mjs",
+  "project-control-parser.mjs",
+  "project-control-state.mjs",
   "provenance-common.mjs",
   "quick-attest.mjs",
   "quick-canonical.mjs",
@@ -45,24 +57,53 @@ const CORE_FILES = [
   "repair-execution.mjs",
   "resume-execution.mjs",
   "resource-preflight.mjs",
+  "remote-deployment.mjs",
+  "remote-process-adapter.mjs",
+  "ssh-remote-adapter.mjs",
+  "runkit-bootstrap.mjs",
   "runkit-cli.mjs",
   "snapshot.mjs",
+  "source-candidate.mjs",
   "source-fingerprint.mjs",
+  "sync-core016-release-identity.mjs",
   "verification-receipt-gate.mjs",
   "verification-context.mjs",
   "verification-plan.mjs",
   "visual-smoke.mjs",
+  "schemas/assurance-route-v1.schema.json",
   "schemas/closeout-receipt-v2.schema.json",
   "schemas/adoption-evidence-v1.schema.json",
   "schemas/coverage-adopt-request-v1.schema.json",
   "schemas/core-artifact.schema.json",
   "schemas/core-artifact-v2.schema.json",
+  "schemas/core-successor-batch-receipt-v1.schema.json",
+  "schemas/core-successor-plan-v1.schema.json",
+  "schemas/core-successor-project-success-receipt-v1.schema.json",
+  "schemas/deployment-execute-request-v1.schema.json",
+  "schemas/deployment-lineage-v1.schema.json",
+  "schemas/deployment-prepare-receipt-v1.schema.json",
   "schemas/engine-pin.schema.json",
   "schemas/engine-pin-v2.schema.json",
   "schemas/evidence-coverage-index-v1.schema.json",
+  "schemas/fleet-discovery-v1.schema.json",
+  "schemas/fleet-manifest-v1.schema.json",
+  "schemas/fleet-root-registry-v1.schema.json",
+  "schemas/human-status-v1.schema.json",
+  "schemas/owner-authority-trust-v1.schema.json",
+  "schemas/owner-migration-authority-v1.schema.json",
+  "schemas/owner-migration-authority-v2.schema.json",
+  "schemas/owner-deployment-authority-v1.schema.json",
+  "schemas/owner-deployment-authority-v2.schema.json",
+  "schemas/owner-deployment-decision-v1.schema.json",
+  "schemas/profile-apply-receipt-v1.schema.json",
+  "schemas/profile-detection-v2.schema.json",
   "schemas/project-config.schema.json",
   "schemas/project-config-v2.schema.json",
   "schemas/profiles.schema.json",
+  "schemas/remote-deployment-manifest-v1.schema.json",
+  "schemas/remote-deployment-result-v1.schema.json",
+  "schemas/remote-deployment-stage-journal-v1.schema.json",
+  "schemas/remote-target-v1.schema.json",
   "schemas/resume-attempt-v1.schema.json",
   "schemas/resume-request-v1.schema.json",
   "schemas/resource-preflight-request-v1.schema.json",
@@ -70,7 +111,9 @@ const CORE_FILES = [
   "schemas/replayable-evidence-v1.schema.json",
   "schemas/finalize-request-v1.schema.json",
   "schemas/ready-for-commit-v1.schema.json",
+  "schemas/ready-for-commit-v2.schema.json",
   "schemas/snapshot-v1.schema.json",
+  "schemas/source-candidate-v2.schema.json",
   "schemas/visual-smoke-request-v1.schema.json",
   "schemas/visual-smoke-result-v1.schema.json",
   "schemas/verification-context-v1.schema.json",
@@ -80,11 +123,20 @@ const CORE_FILES = [
   "schemas/verification-receipt-v2.schema.json",
   "schemas/verify-plan-request-v1.schema.json",
   "templates/goal-contract.json",
+  "templates/assurance-request.json",
+  "templates/core-successor-owner-authority.json",
+  "templates/owner-authority-trust.json",
   "templates/coverage-adopt-request.json",
+  "templates/deployment-execute-request.json",
+  "templates/deployment-owner-authority.json",
+  "templates/deployment-owner-decision.json",
+  "templates/fleet-manifest.json",
+  "templates/fleet-root-registry.json",
   "templates/finalize-request.json",
   "templates/ready-for-commit-request.json",
   "templates/resume-request.json",
   "templates/resource-preflight-request.json",
+  "templates/remote-deployment-manifest.json",
   "templates/snapshot-request.json",
   "templates/visual-smoke-request.json",
   "templates/verify-plan-request.json",
@@ -125,6 +177,80 @@ function atomicWriteJson(filePath, value) {
   renameSync(temporaryPath, filePath);
 }
 
+function pathEntryExists(filePath) {
+  try {
+    lstatSync(filePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function canonicalWorkspaceRoot(workspaceRoot) {
+  const requested = resolve(workspaceRoot);
+  const stat = lstatSync(requested);
+  if (
+    stat.isSymbolicLink()
+    || !stat.isDirectory()
+  ) {
+    throw new Error("workspaceRoot must be a real directory.");
+  }
+  return realpathSync(requested);
+}
+
+function ensureRealDirectory(root, target, label) {
+  const remainder = relative(root, target);
+  if (
+    remainder === ""
+    || remainder === ".."
+    || remainder.startsWith(`..${sep}`)
+    || isAbsolute(remainder)
+  ) {
+    throw new Error(`${label} escapes the workspace.`);
+  }
+  let current = root;
+  for (const segment of remainder.split(/[\\/]/u)) {
+    current = resolve(current, segment);
+    if (!pathEntryExists(current)) {
+      try {
+        mkdirSync(current);
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+    }
+    const stat = lstatSync(current);
+    if (
+      stat.isSymbolicLink()
+      || !stat.isDirectory()
+      || realpathSync(current) !== current
+    ) {
+      throw new Error(`${label} must be a real directory without symlink ancestors.`);
+    }
+  }
+  return target;
+}
+
+function assertRegularRuntimeFile(root, filePath, label) {
+  const remainder = relative(root, filePath);
+  if (
+    remainder === ""
+    || remainder === ".."
+    || remainder.startsWith(`..${sep}`)
+    || isAbsolute(remainder)
+  ) {
+    throw new Error(`${label} escapes the workspace.`);
+  }
+  const stat = lstatSync(filePath);
+  if (
+    stat.isSymbolicLink()
+    || !stat.isFile()
+    || realpathSync(filePath) !== filePath
+  ) {
+    throw new Error(`${label} must be a regular file without symlink ancestors.`);
+  }
+}
+
 function projectConfig(core = currentCoreIdentity()) {
   return {
     schemaVersion: "OwlCodaRunKitConfigV2",
@@ -169,7 +295,11 @@ function migrateProjectConfig({ runtimeRoot, configPath, config, migration }) {
     authorizationGranted: false,
   };
   const receiptsRoot = resolve(runtimeRoot, "config-migration-receipts");
-  mkdirSync(receiptsRoot, { recursive: true });
+  ensureRealDirectory(
+    runtimeRoot,
+    receiptsRoot,
+    "Config migration receipt directory",
+  );
   const receiptName = writeMigrationReceiptAppendOnly(
     receiptsRoot,
     migrationReceiptName(migration, config.core, next.core),
@@ -183,17 +313,17 @@ function coreDirectory() {
   return resolve(fileURLToPath(new URL(".", import.meta.url)));
 }
 
-function coreManifestStream() {
-  const coreRoot = coreDirectory();
-  const projectRoot = resolve(coreRoot, "../..");
+function coreManifestStreamFromRoots(coreRoot, projectRoot) {
   return [
     ...CORE_FILES.map((name) => `${name}\tsha256:${sha256(readFileSync(resolve(coreRoot, name)))}\n`),
     ...CORE_DEPENDENCY_FILES.map((name) => `${name}\tsha256:${sha256(readFileSync(resolve(projectRoot, name)))}\n`),
   ].join("");
 }
 
-export function currentCoreIdentity() {
-  const manifestSha256 = sha256(coreManifestStream());
+export function coreIdentityFromSourceRoot(sourceRoot) {
+  const projectRoot = realpathSync(sourceRoot);
+  const coreRoot = resolve(projectRoot, "scripts/runkit-contract");
+  const manifestSha256 = sha256(coreManifestStreamFromRoots(coreRoot, projectRoot));
   return {
     contractVersion: CONTRACT_VERSION,
     coreVersion: CORE_VERSION,
@@ -202,6 +332,10 @@ export function currentCoreIdentity() {
   };
 }
 
+export function currentCoreIdentity() {
+  return coreIdentityFromSourceRoot(resolve(coreDirectory(), "../.."));
+}
+
 export function isDirectExecution(moduleUrl, argvPath = process.argv[1]) {
   if (!argvPath) return false;
   try {
@@ -303,193 +437,22 @@ 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)
-        }`,
-      ],
-    };
-  }
+function projectControlParserContract() {
+  return {
+    runtimeRoot: RUNTIME_ROOT,
+    acceptedCloseoutVerificationIssues,
+    validateCoreArtifact,
+    validateExecutionPin,
+    validateLeaseOwnedPaths,
+  };
 }
 
 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,
-  };
+  return parseProjectControlState({
+    workspaceRoot,
+    currentCore: currentCoreIdentity(),
+    contract: projectControlParserContract(),
+  }).upgradeSafety;
 }
 
 function validateProducer(producer) {
@@ -567,12 +530,26 @@ export function validateCoreArtifact(artifact) {
 export function acceptedCloseoutVerificationIssues(artifact) {
   if (artifact?.core?.contractVersion !== "0.2" || artifact?.payload?.decision !== "accepted") return [];
   const verification = artifact.payload.verification;
+  const sourceArtifactValid = verification?.sourceArtifact === undefined
+    || (
+      isRecord(verification.sourceArtifact)
+      && new Set(["delivery_packet_v1", "source_candidate_v2"])
+        .has(verification.sourceArtifact.kind)
+      && verification.sourceArtifact.runId === artifact.payload.runId
+      && typeof verification.sourceArtifact.path === "string"
+      && verification.sourceArtifact.path.length > 0
+      && typeof verification.sourceArtifact.sha256 === "string"
+      && /^[a-f0-9]{64}$/.test(verification.sourceArtifact.sha256)
+      && verification.sourceArtifact.sourceFingerprint
+        === verification.sourceFingerprint
+    );
   const validFields = [
     verification?.contractVersion === "0.2",
     verification?.gateDecision === "accepted_passed",
     typeof verification?.gateInputSha256 === "string" && /^[a-f0-9]{64}$/.test(verification.gateInputSha256),
     typeof verification?.activeReceiptSha256 === "string" && /^[a-f0-9]{64}$/.test(verification.activeReceiptSha256),
     typeof verification?.sourceFingerprint === "string" && /^[a-f0-9]{64}$/.test(verification.sourceFingerprint),
+    sourceArtifactValid,
     typeof verification?.verificationContextFingerprint === "string" && /^[a-f0-9]{64}$/.test(verification.verificationContextFingerprint),
     verification?.leaseState === "released",
     Array.isArray(verification?.selectedProfileIds)
@@ -588,15 +565,27 @@ export function acceptedCloseoutVerificationIssues(artifact) {
 
 export async function initializeProjectRunKit({ workspaceRoot } = {}) {
   if (typeof workspaceRoot !== "string" || workspaceRoot.length === 0) throw new Error("workspaceRoot is required.");
-  const root = realpathSync(workspaceRoot);
-  if (existsSync(resolve(root, ".owlrunkit"))) throw new Error("Legacy .owlrunkit exists; explicit migration is required before initialization.");
+  const root = canonicalWorkspaceRoot(workspaceRoot);
+  if (pathEntryExists(resolve(root, ".owlrunkit"))) throw new Error("Legacy .owlrunkit exists; explicit migration is required before initialization.");
   const runtimeRoot = resolve(root, RUNTIME_ROOT);
-  const remainder = relative(root, runtimeRoot);
-  if (remainder.startsWith("..") || isAbsolute(remainder)) throw new Error("Runtime root escapes the workspace.");
+  ensureRealDirectory(root, resolve(root, ".owlcoda"), "OwlCoda control directory");
+  ensureRealDirectory(root, runtimeRoot, "RunKit runtime directory");
+  ensureRealDirectory(
+    runtimeRoot,
+    resolve(runtimeRoot, "executions"),
+    "RunKit executions directory",
+  );
   const configPath = resolve(runtimeRoot, "config.json");
   const profilesPath = resolve(runtimeRoot, "profiles.json");
-  if (!existsSync(configPath)) {
-    mkdirSync(resolve(runtimeRoot, "executions"), { recursive: true });
+  const configExists = pathEntryExists(configPath);
+  const profilesExist = pathEntryExists(profilesPath);
+  if (configExists) {
+    assertRegularRuntimeFile(runtimeRoot, configPath, "Project config");
+  }
+  if (profilesExist) {
+    assertRegularRuntimeFile(runtimeRoot, profilesPath, "Project profiles");
+  }
+  if (!configExists) {
     atomicWriteJson(configPath, projectConfig());
   } else {
     const config = JSON.parse(readFileSync(configPath, "utf8"));
@@ -624,8 +613,11 @@ export async function initializeProjectRunKit({ workspaceRoot } = {}) {
         config,
         migration: "config-v01-to-v02",
       });
-      if (!existsSync(profilesPath)) {
-        writeFileSync(profilesPath, `${JSON.stringify({ schemaVersion: "OwlCodaRunKitProfilesV1", profiles: [] }, null, 2)}\n`);
+      if (!profilesExist) {
+        atomicWriteJson(profilesPath, {
+          schemaVersion: "OwlCodaRunKitProfilesV1",
+          profiles: [],
+        });
       }
       return { status: "upgraded", exitCode: 0, runtimeRoot: RUNTIME_ROOT, core: current, migrationReceipt };
     } else if (config.schemaVersion === "OwlCodaRunKitConfigV2" && config.core?.contractVersion === CONTRACT_VERSION) {
@@ -645,17 +637,22 @@ export async function initializeProjectRunKit({ workspaceRoot } = {}) {
         config,
         migration: "config-v02-core-refresh",
       });
-      if (!existsSync(profilesPath)) {
-        writeFileSync(profilesPath, `${JSON.stringify({ schemaVersion: "OwlCodaRunKitProfilesV1", profiles: [] }, null, 2)}\n`);
+      if (!profilesExist) {
+        atomicWriteJson(profilesPath, {
+          schemaVersion: "OwlCodaRunKitProfilesV1",
+          profiles: [],
+        });
       }
       return { status: "upgraded", exitCode: 0, runtimeRoot: RUNTIME_ROOT, core: current, migrationReceipt };
     } else {
       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`);
+  if (!profilesExist) {
+    atomicWriteJson(profilesPath, {
+      schemaVersion: "OwlCodaRunKitProfilesV1",
+      profiles: [],
+    });
   }
   return { status: "initialized", exitCode: 0, runtimeRoot: RUNTIME_ROOT, core: currentCoreIdentity() };
 }