owlrunkit 0.20.0 → 0.21.0

package/packages/attest/src/index.mjs

@@ -29,6 +29,12 @@ import {
   parseOfflineAttestationBundle,
 } from "./offline-bundle.mjs";
 import { captureWorkspaceSnapshot } from "./workspace-snapshot.mjs";
+import {
+  captureCanonicalCandidateIdentityV1,
+  captureForeignWorkspaceFilesystemIdentityV1,
+  validCanonicalCandidateIdentityV1,
+  validForeignWorkspaceFilesystemIdentityV1,
+} from "./candidate-identity.mjs";
 
 function readSubject(subjectPath) {
   const { absolutePath, bytes } = readFileBytesBounded(subjectPath);
@@ -45,6 +51,7 @@ export function attestFile({ subjectPath, workspaceRoot }) {
     "OwlCodaQuickVerificationReceiptV1",
     "OwlCodaQuickVerificationReceiptV2",
     "OwlCodaQuickVerificationReceiptV3",
+    "OwlCodaQuickVerificationReceiptV4",
   ]).has(subject.value.schemaVersion)) {
     const details = attestQuickReceiptDetailsFromBytes({
       receiptPath: subject.absolutePath,
@@ -99,6 +106,8 @@ export {
   attestQuickReceipt,
   attestQuickReceiptDetails,
   canonicalJson,
+  captureCanonicalCandidateIdentityV1,
+  captureForeignWorkspaceFilesystemIdentityV1,
   captureWorkspaceSnapshot,
   createAttestationRef,
   createOfflineAttestationBundle,
@@ -113,5 +122,7 @@ export {
   sha256Bytes,
   sha256Canonical,
   validQuickReceiptShape,
+  validCanonicalCandidateIdentityV1,
+  validForeignWorkspaceFilesystemIdentityV1,
   verifyBundle,
 };

package/packages/attest/src/quick-receipt-contract.mjs

@@ -3,6 +3,10 @@ import {
   isSha256Ref,
   sha256Canonical,
 } from "./formal.mjs";
+import {
+  validCanonicalCandidateIdentityV1,
+  validForeignWorkspaceFilesystemIdentityV1,
+} from "./candidate-identity.mjs";
 
 const RECEIPT_REQUIRED_KEYS = [
   "schemaVersion",
@@ -52,6 +56,10 @@ const V3_RECEIPT_ISSUES = new Set([
   "consumer_source_mutated_during_verification",
   "quick_isolation_cleanup_failed",
 ]);
+const V4_RECEIPT_ISSUES = new Set([
+  ...V3_RECEIPT_ISSUES,
+  "foreign_workspace_mutated_during_verification",
+]);
 const V3_MUTATION_DECISIONS = new Set([
   "source_unchanged",
   "invalidated_by_command_source_mutation",
@@ -61,6 +69,10 @@ const V3_MUTATION_DECISIONS = new Set([
   "invalidated_by_isolation_cleanup_failure",
   "invalidated_by_multiple_mutations",
 ]);
+const V4_MUTATION_DECISIONS = new Set([
+  ...V3_MUTATION_DECISIONS,
+  "invalidated_by_foreign_workspace_mutation",
+]);
 
 function validDateTime(value) {
   return typeof value === "string"
@@ -237,6 +249,48 @@ function validMutationClasses(value) {
     && ["not_isolated", "none", "changed_and_discarded"].includes(value.consumerIgnoredArtifacts);
 }
 
+function validForeignMutationClasses(value) {
+  return hasExactKeys(value, [
+    "workspaceSource",
+    "boundIgnoredPaths",
+    "dependencyEnvironment",
+    "consumerSource",
+    "consumerIgnoredArtifacts",
+    "foreignTarget",
+  ])
+    && ["unchanged", "changed"].includes(value.workspaceSource)
+    && ["not_bound", "unchanged", "changed"].includes(value.boundIgnoredPaths)
+    && ["not_bound", "unchanged", "changed"].includes(value.dependencyEnvironment)
+    && ["unchanged", "changed"].includes(value.consumerSource)
+    && ["none", "changed_and_discarded"].includes(value.consumerIgnoredArtifacts)
+    && ["unchanged", "changed"].includes(value.foreignTarget);
+}
+
+function validForeignWorkspace(value, sourceWorkspaceRoot) {
+  if (!hasExactKeys(value, [
+    "candidateBefore",
+    "candidateAfter",
+    "filesystemBefore",
+    "filesystemAfter",
+    "zeroWriteObserved",
+  ])) return false;
+  if (
+    !validCanonicalCandidateIdentityV1(value.candidateBefore)
+    || !validCanonicalCandidateIdentityV1(value.candidateAfter)
+    || !validForeignWorkspaceFilesystemIdentityV1(value.filesystemBefore)
+    || !validForeignWorkspaceFilesystemIdentityV1(value.filesystemAfter)
+    || value.candidateBefore.workspaceRoot !== sourceWorkspaceRoot
+    || value.candidateAfter.workspaceRoot !== sourceWorkspaceRoot
+    || value.filesystemBefore.workspaceRoot !== sourceWorkspaceRoot
+    || value.filesystemAfter.workspaceRoot !== sourceWorkspaceRoot
+  ) return false;
+  const unchanged = value.candidateBefore.candidateFingerprint
+      === value.candidateAfter.candidateFingerprint
+    && value.filesystemBefore.filesystemFingerprint
+      === value.filesystemAfter.filesystemFingerprint;
+  return value.zeroWriteObserved === unchanged;
+}
+
 function validV3MutationTruth(receipt) {
   const workspaceSourceChanged = sourceStateFingerprint(receipt.workspaceBefore)
     !== sourceStateFingerprint(receipt.workspaceAfter);
@@ -283,17 +337,66 @@ function validV3MutationTruth(receipt) {
     && JSON.stringify([...receipt.issueCodes].sort()) === JSON.stringify(expectedIssues);
 }
 
+function validV4MutationTruth(receipt) {
+  const workspaceSourceChanged = sourceStateFingerprint(receipt.workspaceBefore)
+    !== sourceStateFingerprint(receipt.workspaceAfter);
+  const boundIgnored = receipt.workspaceBefore.ignoredPathsBound === true;
+  const boundIgnoredChanged = boundIgnored
+    && receipt.workspaceBefore.ignoredPathsFingerprint
+      !== receipt.workspaceAfter.ignoredPathsFingerprint;
+  const isolation = receipt.executionIsolation;
+  const consumerSourceChanged = isolation.consumerDelta.sourcePaths.length > 0;
+  const consumerIgnoredChanged = isolation.consumerDelta.ignoredPaths.length > 0;
+  const dependencyBound = isolation.dependencyEnvironment !== null;
+  const dependencyChanged = dependencyBound
+    && (isolation.dependencyEnvironmentAfter === null
+      || isolation.dependencyEnvironmentAfter.fingerprint
+        !== isolation.dependencyEnvironment.fingerprint);
+  const cleanupFailed = isolation.cleanupStatus === "cleanup_failed";
+  const foreignChanged = receipt.foreignWorkspace.zeroWriteObserved !== true;
+  if (receipt.mutationClasses.workspaceSource !== (workspaceSourceChanged ? "changed" : "unchanged")
+    || receipt.mutationClasses.boundIgnoredPaths !== (boundIgnored
+      ? boundIgnoredChanged ? "changed" : "unchanged"
+      : "not_bound")
+    || receipt.mutationClasses.dependencyEnvironment !== (dependencyBound
+      ? dependencyChanged ? "changed" : "unchanged"
+      : "not_bound")
+    || receipt.mutationClasses.consumerSource !== (consumerSourceChanged ? "changed" : "unchanged")
+    || receipt.mutationClasses.consumerIgnoredArtifacts !== (consumerIgnoredChanged
+      ? "changed_and_discarded" : "none")
+    || receipt.mutationClasses.foreignTarget !== (foreignChanged ? "changed" : "unchanged")) {
+    return false;
+  }
+  const facts = [
+    [workspaceSourceChanged, "invalidated_by_command_source_mutation", "source_mutated_during_verification"],
+    [boundIgnoredChanged, "invalidated_by_bound_ignored_mutation", "bound_ignored_path_mutated_during_verification"],
+    [dependencyChanged, "invalidated_by_dependency_environment_mutation", "dependency_environment_mutated_during_verification"],
+    [consumerSourceChanged, "invalidated_by_consumer_source_mutation", "consumer_source_mutated_during_verification"],
+    [cleanupFailed, "invalidated_by_isolation_cleanup_failure", "quick_isolation_cleanup_failed"],
+    [foreignChanged, "invalidated_by_foreign_workspace_mutation", "foreign_workspace_mutated_during_verification"],
+  ].filter(([active]) => active);
+  const expectedDecision = facts.length === 0
+    ? "source_unchanged"
+    : facts.length === 1 ? facts[0][1] : "invalidated_by_multiple_mutations";
+  const expectedIssues = facts.map(([, , issue]) => issue).sort();
+  return receipt.mutationDecision === expectedDecision
+    && JSON.stringify([...receipt.issueCodes].sort()) === JSON.stringify(expectedIssues);
+}
+
 export function validQuickReceiptShape(receipt) {
   const receiptV1 = receipt?.schemaVersion === "OwlCodaQuickVerificationReceiptV1";
   const receiptV2 = receipt?.schemaVersion === "OwlCodaQuickVerificationReceiptV2";
   const receiptV3 = receipt?.schemaVersion === "OwlCodaQuickVerificationReceiptV3";
-  const requiredKeys = receiptV3
+  const receiptV4 = receipt?.schemaVersion === "OwlCodaQuickVerificationReceiptV4";
+  const requiredKeys = receiptV4
+    ? [...RECEIPT_REQUIRED_KEYS, "controllerWorkspaceRoot", "sourceWorkspaceRoot", "executionIsolation", "mutationClasses", "foreignWorkspace"]
+    : receiptV3
     ? [...RECEIPT_REQUIRED_KEYS, "sourceWorkspaceRoot", "executionIsolation", "mutationClasses"]
     : receiptV2
     ? [...RECEIPT_REQUIRED_KEYS, "inputArtifacts"]
     : RECEIPT_REQUIRED_KEYS;
-  const optionalKeys = receiptV3 ? ["inputArtifacts", "signatureRef"] : ["signatureRef"];
-  if (!(receiptV1 || receiptV2 || receiptV3) || !hasExactKeys(receipt, requiredKeys, optionalKeys)) return false;
+  const optionalKeys = receiptV3 || receiptV4 ? ["inputArtifacts", "signatureRef"] : ["signatureRef"];
+  if (!(receiptV1 || receiptV2 || receiptV3 || receiptV4) || !hasExactKeys(receipt, requiredKeys, optionalKeys)) return false;
   if (
     typeof receipt.receiptId !== "string"
     || receipt.receiptId.length === 0
@@ -320,13 +423,15 @@ export function validQuickReceiptShape(receipt) {
     || !hasExactKeys(receipt.outputArtifacts, ["stdout", "stderr"])
     || !validOutputArtifact(receipt.outputArtifacts.stdout)
     || !validOutputArtifact(receipt.outputArtifacts.stderr)
-    || !(receiptV3
+    || !(receiptV4
+      ? V4_MUTATION_DECISIONS.has(receipt.mutationDecision)
+      : receiptV3
       ? V3_MUTATION_DECISIONS.has(receipt.mutationDecision)
       : ["source_unchanged", "invalidated_by_command_source_mutation"].includes(receipt.mutationDecision))
     || !Array.isArray(receipt.issueCodes)
     || new Set(receipt.issueCodes).size !== receipt.issueCodes.length
     || !receipt.issueCodes.every((entry) => typeof entry === "string"
-      && (receiptV3 ? V3_RECEIPT_ISSUES : KNOWN_RECEIPT_ISSUES).has(entry))
+      && (receiptV4 ? V4_RECEIPT_ISSUES : receiptV3 ? V3_RECEIPT_ISSUES : KNOWN_RECEIPT_ISSUES).has(entry))
   ) {
     return false;
   }
@@ -348,6 +453,22 @@ export function validQuickReceiptShape(receipt) {
   )) {
     return false;
   }
+  if (receiptV4 && (
+    typeof receipt.controllerWorkspaceRoot !== "string"
+    || receipt.controllerWorkspaceRoot.length === 0
+    || typeof receipt.sourceWorkspaceRoot !== "string"
+    || receipt.sourceWorkspaceRoot.length === 0
+    || receipt.controllerWorkspaceRoot === receipt.sourceWorkspaceRoot
+    || !validForeignMutationClasses(receipt.mutationClasses)
+    || !validExecutionIsolation(receipt.executionIsolation, receipt)
+    || !validForeignWorkspace(receipt.foreignWorkspace, receipt.sourceWorkspaceRoot)
+    || receipt.inputArtifacts !== undefined
+      && (!hasExactKeys(receipt.inputArtifacts, ["stdin"])
+        || !validOutputArtifact(receipt.inputArtifacts.stdin))
+    || !validV4MutationTruth(receipt)
+  )) {
+    return false;
+  }
   if (receipt.signatureRef !== undefined) {
     if (!hasExactKeys(receipt.signatureRef, ["path", "sha256"])
       || typeof receipt.signatureRef.path !== "string"

package/packages/attest/src/quick.mjs

@@ -15,10 +15,24 @@ import {
 } from "./quick-receipt-contract.mjs";
 import { captureDependencyEnvironment } from "./dependency-environment.mjs";
 import { captureWorkspaceSnapshot } from "./workspace-snapshot.mjs";
+import {
+  captureCanonicalCandidateIdentityV1,
+  captureForeignWorkspaceFilesystemIdentityV1,
+} from "./candidate-identity.mjs";
 
 export { validQuickReceiptShape } from "./quick-receipt-contract.mjs";
 
 export const SUPPORTED_QUICK_CORE_IDENTITIES = Object.freeze([
+  {
+    contractVersion: "0.2",
+    coreVersion: "0.21.0",
+    coreManifestSha256: "sha256:f85b9bf8c32705d5f5dfebdb653e83ac8d1ac0468214c17f230cbd2de04246fd",
+  },
+  {
+    contractVersion: "0.2",
+    coreVersion: "0.20.1",
+    coreManifestSha256: "sha256:8af2b9792731efa37f596255a7677dcec6e2fd3cc079dfdb0e6ff29e8017e784",
+  },
   {
     contractVersion: "0.2",
     coreVersion: "0.20.0",
@@ -271,19 +285,25 @@ function attestQuickReceiptDetailsFromBytesWithCatalog({
   const selectedWorkspaceRoot = workspaceRoot === undefined
     ? undefined
     : realpathSync(workspaceRoot);
+  const foreignReceipt = receipt.schemaVersion === "OwlCodaQuickVerificationReceiptV4";
   if (selectedWorkspaceRoot === undefined) {
     issues.push("current_workspace_not_checked");
   }
   let receiptWorkspaceRoot;
+  let receiptSourceRoot;
   if (selectedWorkspaceRoot !== undefined) {
     try {
-      receiptWorkspaceRoot = realpathSync(
-        receipt.schemaVersion === "OwlCodaQuickVerificationReceiptV3"
+      receiptWorkspaceRoot = realpathSync(foreignReceipt
+        ? receipt.controllerWorkspaceRoot
+        : receipt.schemaVersion === "OwlCodaQuickVerificationReceiptV3"
           ? receipt.sourceWorkspaceRoot
-          : receipt.exactCommand.cwd,
-      );
+          : receipt.exactCommand.cwd);
+      receiptSourceRoot = realpathSync(foreignReceipt
+        ? receipt.sourceWorkspaceRoot
+        : receiptWorkspaceRoot);
     } catch {
       receiptWorkspaceRoot = undefined;
+      receiptSourceRoot = undefined;
     }
   }
   const commandWorkspaceMatches = selectedWorkspaceRoot !== undefined
@@ -317,10 +337,25 @@ function attestQuickReceiptDetailsFromBytesWithCatalog({
   const ignoredPaths = receipt.workspaceAfter.ignoredPathsBound === true
     ? receipt.workspaceAfter.ignoredPathBindings.map(entry => entry.path)
     : [];
-  const currentSourceValid = selectedWorkspaceRoot === undefined
-    || commandWorkspaceMatches
-      && captureWorkspaceSnapshot(selectedWorkspaceRoot, { ignoredPaths }).sourceFingerprint
-        === receipt.workspaceAfter.sourceFingerprint;
+  let currentSourceValid = selectedWorkspaceRoot === undefined;
+  if (selectedWorkspaceRoot !== undefined && commandWorkspaceMatches && receiptSourceRoot !== undefined) {
+    try {
+      currentSourceValid = captureWorkspaceSnapshot(receiptSourceRoot, { ignoredPaths }).sourceFingerprint
+          === receipt.workspaceAfter.sourceFingerprint;
+      if (foreignReceipt) {
+        const currentCandidate = captureCanonicalCandidateIdentityV1(receiptSourceRoot);
+        const currentFilesystem = captureForeignWorkspaceFilesystemIdentityV1(receiptSourceRoot);
+        currentSourceValid = currentSourceValid
+          && receipt.foreignWorkspace.zeroWriteObserved === true
+          && currentCandidate.candidateFingerprint
+            === receipt.foreignWorkspace.candidateAfter.candidateFingerprint
+          && currentFilesystem.filesystemFingerprint
+            === receipt.foreignWorkspace.filesystemAfter.filesystemFingerprint;
+      }
+    } catch {
+      currentSourceValid = false;
+    }
+  }
   const dependencyEnvironmentValid = dependencyEnvironmentCurrent(
     receipt.executionIsolation?.dependencyEnvironment,
     materials,

package/{registry-release-policy-v1.json → registry-release-policy-v2.json}

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": "OwlCodaRunKitRegistryReleasePolicyV1",
-  "status": "release_candidate_unpublished",
+  "schemaVersion": "OwlCodaRunKitRegistryReleasePolicyV2",
+  "status": "release_artifact_registry_gated",
   "packageName": "owlrunkit",
-  "candidateVersion": "0.20.0",
+  "artifactVersion": "0.21.0",
   "registry": "https://registry.npmjs.org",
   "registryRequiredBeforeAdoption": true,
   "exactVersionRequired": true,
@@ -21,14 +21,13 @@
     "symlink",
     "workspace"
   ],
-  "currentPublishedRelease": {
+  "rollbackRelease": {
     "packageName": "owlrunkit",
-    "version": "0.19.2",
-    "shasum": "f9b0f797fe9f79878374380db0756223accd61dc",
-    "integrity": "sha512-rFEnbOtPuybztz8EZbcQSY3tGycCAuTkg+qGDwcKaTPjdJRhsXS4OB2HLwDBiILIV6BFyRPSQ7zanObT4jd58g==",
-    "tarballUrl": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.19.2.tgz"
+    "version": "0.20.0",
+    "shasum": "b123f5ea33a4f500961a0df3226ed0ca409d111d",
+    "integrity": "sha512-VcXUh+q8DwR6RoO9JDoUMEzFrpFRBpSvpqgHvIY15Z+Oo+A31Ij2kFO5wCFki80nd6Tl/YT70t7UV2aG0TZ0GQ==",
+    "tarballUrl": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.20.0.tgz"
   },
-  "registryRelease": null,
   "registryEvidenceMustBeExternal": true,
   "registryEvidenceSchemaVersion": "OwlCodaRunKitRegistryReleaseEvidenceV1",
   "embeddedAttestComponentVersion": "0.2.0",

package/sbom.spdx.json

@@ -2,8 +2,8 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "owlrunkit-0.20.0",
-  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.20.0",
+  "name": "owlrunkit-0.21.0",
+  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.21.0",
   "creationInfo": {
     "created": "2026-07-29T00:00:00Z",
     "creators": [
@@ -14,7 +14,7 @@
     {
       "name": "owlrunkit",
       "SPDXID": "SPDXRef-Package-OwlRunKit",
-      "versionInfo": "0.20.0",
+      "versionInfo": "0.21.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "GPL-3.0-or-later",
@@ -24,7 +24,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/owlrunkit@0.20.0"
+          "referenceLocator": "pkg:npm/owlrunkit@0.21.0"
         }
       ]
     }

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

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { parseProjectControlState } from "./project-control-parser.mjs";
 
 export const CONTRACT_VERSION = "0.2";
-export const CORE_VERSION = "0.20.0";
+export const CORE_VERSION = "0.21.0";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
@@ -28,6 +28,7 @@ const CORE_FILES = [
   "deployment-workflow.mjs",
   "efficiency-metrics.mjs",
   "fleet-discovery.mjs",
+  "fleet-skill-plan.mjs",
   "finalize.mjs",
   "formal-workflow.mjs",
   "formal-preflight.mjs",
@@ -107,11 +108,13 @@ const CORE_FILES = [
   "schemas/fleet-discovery-v1.schema.json",
   "schemas/fleet-manifest-v1.schema.json",
   "schemas/fleet-root-registry-v1.schema.json",
+  "schemas/fleet-skill-upgrade-plan-v1.schema.json",
   "schemas/formal-check-v2.schema.json",
   "schemas/formal-envelope-preflight-v1.schema.json",
   "schemas/formal-evidence-summary-v1.schema.json",
   "schemas/formal-supplemental-evidence-v1.schema.json",
   "schemas/human-status-v1.schema.json",
+  "schemas/inspect-compact-v1.schema.json",
   "schemas/onboarding-bootstrap-plan-v1.schema.json",
   "schemas/onboarding-bootstrap-receipt-v1.schema.json",
   "schemas/outcome-summary-v1.schema.json",
@@ -150,6 +153,7 @@ const CORE_FILES = [
   "schemas/candidate-transfer-packet-v1.schema.json",
   "schemas/team-acceptance-packet-v2.schema.json",
   "schemas/team-delivery-status-v1.schema.json",
+  "schemas/team-delivery-status-v2.schema.json",
   "schemas/team-packet-validation-v1.schema.json",
   "schemas/team-recommendation-v1.schema.json",
   "schemas/team-task-packet-v2.schema.json",
@@ -162,10 +166,15 @@ const CORE_FILES = [
   "schemas/team-project-event-v3.schema.json",
   "schemas/team-project-event-v4.schema.json",
   "schemas/team-project-event-v5.schema.json",
+  "schemas/team-project-event-v6.schema.json",
+  "schemas/team-project-event-v7.schema.json",
   "schemas/team-project-successor-receipt-v1.schema.json",
   "schemas/team-project-status-v1.schema.json",
   "schemas/team-project-status-v2.schema.json",
   "schemas/team-project-status-v3.schema.json",
+  "schemas/team-project-status-v4.schema.json",
+  "schemas/external-gate-v1.schema.json",
+  "schemas/delivery-lifecycle-v1.schema.json",
   "schemas/usage-mode-recommendation-v1.schema.json",
   "schemas/usage-mode-recommendation-v2.schema.json",
   "schemas/verification-envelope-v1.schema.json",
@@ -199,10 +208,14 @@ const CORE_FILES = [
 ];
 
 const CORE_DEPENDENCY_FILES = [
+  "packages/attest/src/candidate-identity.mjs",
   "packages/attest/src/dependency-environment.mjs",
+  "packages/attest/schemas/canonical-candidate-identity-v1.schema.json",
+  "packages/attest/schemas/foreign-workspace-filesystem-identity-v1.schema.json",
   "packages/attest/schemas/workspace-snapshot-v1.schema.json",
   "packages/attest/schemas/workspace-snapshot-v2.schema.json",
   "packages/attest/schemas/quick-verification-receipt-v3.schema.json",
+  "packages/attest/schemas/quick-verification-receipt-v4.schema.json",
   "packages/attest/src/formal.mjs",
   "packages/attest/src/offline-bundle.mjs",
   "packages/attest/src/quick-receipt-contract.mjs",

package/scripts/runkit-contract/fleet-skill-plan.mjs

@@ -0,0 +1,223 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  currentCoreIdentity,
+  validateProjectConfigV2,
+} from "./core-contract.mjs";
+import { discoverFleet } from "./fleet-discovery.mjs";
+import { inspectInstalledSkillCompatibility } from "./install-codex-skill.mjs";
+import { inspectProjectControlState } from "./project-control-state.mjs";
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function fleetSourceArguments({
+  workspaceRoots,
+  fleetManifestPath,
+  fleetRoots,
+  fleetRegistryPath,
+}, { install = false } = {}) {
+  if (Array.isArray(workspaceRoots)) {
+    const flag = install ? "--workspace" : "--workspace-root";
+    return workspaceRoots.flatMap(root => [flag, shellQuote(root)]).join(" ");
+  }
+  if (Array.isArray(fleetRoots)) {
+    return fleetRoots.flatMap(root => ["--fleet-root", shellQuote(root)]).join(" ");
+  }
+  if (typeof fleetManifestPath === "string") {
+    return `--fleet-manifest ${shellQuote(fleetManifestPath)}`;
+  }
+  return typeof fleetRegistryPath === "string"
+    ? `--registry ${shellQuote(fleetRegistryPath)}`
+    : "";
+}
+
+function validLegacyConfigV1(config) {
+  return config?.schemaVersion === "OwlCodaRunKitConfigV1"
+    && config?.core?.contractVersion === "0.1"
+    && config?.authorizationPolicy === "external_explicit_authority_required";
+}
+
+async function inspectAffectedProject(workspaceRoot) {
+  const blockers = [];
+  const control = inspectProjectControlState({ workspaceRoot }).upgradeSafety;
+  for (const artifactId of control.activeRunIds) {
+    blockers.push({ code: "active_execution", workspaceRoot, artifactId });
+  }
+  for (const artifactId of control.activeLeaseIds) {
+    blockers.push({ code: "active_lease", workspaceRoot, artifactId });
+  }
+  for (const issue of control.issues) {
+    blockers.push({ code: "control_state_invalid", workspaceRoot, detail: issue });
+  }
+
+  const configPath = path.join(workspaceRoot, ".owlcoda/runkit/config.json");
+  let config = null;
+  try {
+    config = JSON.parse((await readFile(configPath)).toString("utf8"));
+  } catch (error) {
+    blockers.push({
+      code: "project_config_invalid",
+      workspaceRoot,
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+  if (config !== null) {
+    const validation = config.schemaVersion === "OwlCodaRunKitConfigV2"
+      ? validateProjectConfigV2(config)
+      : null;
+    if ((validation !== null && !validation.valid)
+      || (validation === null && !validLegacyConfigV1(config))) {
+      blockers.push({
+        code: "project_config_invalid",
+        workspaceRoot,
+        detail: validation?.issues?.join(",") ?? "unsupported_config",
+      });
+    }
+  }
+
+  return {
+    project: {
+      workspaceRoot,
+      configPath,
+      configCoreVersion: config?.core?.coreVersion ?? null,
+      activeRunIds: [...control.activeRunIds],
+      activeLeaseIds: [...control.activeLeaseIds],
+      upgradeSafe: blockers.length === 0,
+    },
+    blockers,
+  };
+}
+
+export async function planFleetSkillUpgradeV1({
+  repositoryRoot,
+  targetRoot,
+  archiveRoot,
+  workspaceRoots = null,
+  fleetManifestPath = null,
+  fleetRoots = null,
+  fleetRegistryPath = null,
+} = {}) {
+  for (const [name, value] of Object.entries({ repositoryRoot, targetRoot, archiveRoot })) {
+    if (typeof value !== "string" || value.length === 0) {
+      throw new Error(`${name} is required`);
+    }
+  }
+  const resolvedRepositoryRoot = path.resolve(repositoryRoot);
+  const resolvedTargetRoot = path.resolve(targetRoot);
+  const resolvedArchiveRoot = path.resolve(archiveRoot);
+  const source = { workspaceRoots, fleetManifestPath, fleetRoots, fleetRegistryPath };
+  const blockers = [];
+  let discovery = null;
+  try {
+    discovery = await discoverFleet(source);
+  } catch (error) {
+    blockers.push({
+      code: error?.message === "fleet_registry_missing"
+        ? "fleet_registry_missing"
+        : "fleet_discovery_failed",
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+  if (discovery !== null && !discovery.complete) {
+    for (const workspaceRoot of discovery.unreachableRoots) {
+      blockers.push({ code: "fleet_root_unreachable", workspaceRoot });
+    }
+  }
+
+  const affectedProjects = [];
+  for (const workspaceRoot of discovery?.workspaceRoots ?? []) {
+    const inspected = await inspectAffectedProject(workspaceRoot);
+    affectedProjects.push(inspected.project);
+    blockers.push(...inspected.blockers);
+  }
+  affectedProjects.sort((left, right) => (
+    left.workspaceRoot < right.workspaceRoot ? -1 : left.workspaceRoot > right.workspaceRoot ? 1 : 0
+  ));
+
+  const sharedSkill = await inspectInstalledSkillCompatibility({
+    targetRoot: resolvedTargetRoot,
+  });
+  if (new Set(["unmanaged", "drifted"]).has(sharedSkill.status)) {
+    blockers.push({ code: "shared_skill_integrity_invalid", detail: sharedSkill.status });
+  }
+  blockers.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right), "en"));
+
+  const planSourceArgs = fleetSourceArguments(source);
+  const installSourceArgs = fleetSourceArguments(source, { install: true });
+  const commonPlan = [
+    "npx --no-install owlrunkit fleet skill-plan",
+    `--skill-root ${shellQuote(resolvedTargetRoot)}`,
+    `--archive-root ${shellQuote(resolvedArchiveRoot)}`,
+    planSourceArgs,
+  ].filter(Boolean).join(" ");
+  const installerPath = path.join(
+    resolvedRepositoryRoot,
+    "scripts/runkit-contract/install-codex-skill.mjs",
+  );
+  const installCommand = [
+    `node ${shellQuote(installerPath)} install`,
+    `--repository ${shellQuote(resolvedRepositoryRoot)}`,
+    `--target ${shellQuote(resolvedTargetRoot)}`,
+    `--archive ${shellQuote(resolvedArchiveRoot)}`,
+    installSourceArgs,
+  ].filter(Boolean).join(" ");
+  const rollbackCommand = [
+    `node ${shellQuote(installerPath)} restore`,
+    `--target ${shellQuote(resolvedTargetRoot)}`,
+    `--archive ${shellQuote(resolvedArchiveRoot)}`,
+    "--receipt <upgrade-receipt.json>",
+  ].join(" ");
+
+  return {
+    schemaVersion: "OwlCodaRunKitFleetSkillUpgradePlanV1",
+    status: blockers.length === 0 ? "ready" : "blocked",
+    expectedCore: currentCoreIdentity(),
+    sharedSkill: {
+      targetRoot: resolvedTargetRoot,
+      status: sharedSkill.status,
+      installedSkillVersion: sharedSkill.installedSkillVersion ?? null,
+      installedConfigCoreVersion: sharedSkill.installedConfigCoreVersion ?? null,
+      issues: sharedSkill.issues ?? [],
+    },
+    discovery: discovery === null ? null : {
+      source: discovery.source,
+      complete: discovery.complete,
+      workspaceCount: discovery.workspaceRoots.length,
+      unreachableRoots: discovery.unreachableRoots,
+    },
+    affectedProjects,
+    blockers,
+    commands: {
+      dryRun: commonPlan,
+      install: installCommand,
+      rollback: rollbackCommand,
+    },
+    authorizationGranted: false,
+  };
+}
+
+export function formatFleetSkillUpgradePlanHumanV1(plan) {
+  const lines = [
+    `Shared Skill fleet plan: ${plan.status}.`,
+    `Expected Core: ${plan.expectedCore.coreVersion} (${plan.expectedCore.coreManifestSha256}).`,
+    `Installed Skill: ${plan.sharedSkill.status} (${plan.sharedSkill.installedSkillVersion ?? "unknown"}).`,
+    `Affected projects: ${plan.affectedProjects.length}.`,
+  ];
+  if (plan.blockers.length > 0) {
+    lines.push("Blockers:");
+    for (const blocker of plan.blockers) {
+      lines.push(`- ${blocker.code}${blocker.workspaceRoot ? `: ${blocker.workspaceRoot}` : ""}${blocker.artifactId ? ` (${blocker.artifactId})` : ""}`);
+    }
+  }
+  lines.push(
+    `Dry run: ${plan.commands.dryRun}`,
+    `Install after blockers clear: ${plan.commands.install}`,
+    `Rollback after installation: ${plan.commands.rollback}`,
+    "Authority: not granted; no shared Skill or project was modified.",
+    "",
+  );
+  return lines.join("\n");
+}

package/scripts/runkit-contract/formal-workflow.mjs

@@ -1394,7 +1394,9 @@ export function resumeCompletedFormalFinishV1({
     };
   }
   if (
-    new Set(["0.19.2", "0.20.0"]).has(closeout.artifact.core?.coreVersion)
+    new Set(["0.19.2", "0.20.0", "0.20.1", "0.21.0"]).has(
+      closeout.artifact.core?.coreVersion,
+    )
     && (
       !hasExactKeys(formalEvidenceBinding, [
         "schemaVersion",