owlrunkit 0.20.0 → 0.22.0

package/packages/attest/src/quick.mjs

@@ -15,10 +15,34 @@ 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.22.0",
+    coreManifestSha256: "sha256:e79d2123d88ada0e2e31f62fabee83b1d661ca02e93a383691a502f721ae1e7e",
+  },
+  {
+    contractVersion: "0.2",
+    coreVersion: "0.21.1",
+    coreManifestSha256: "sha256:ff9e3756d6f385f1843d842c29baa6525101a84f3273148ad6b00f1187078c6e",
+  },
+  {
+    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 +295,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 +347,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.22.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.21.0",
+    "shasum": "f9ecfa41ad2ba3140258234b49d98798675651f2",
+    "integrity": "sha512-hopLyvN5vp0y3xu0H0jQbMI6DxaDSWcGYcn7tAbCa0m2OqW2G8n5kJvnr217jqPYlArQwJ2TDPRLNmp4vPEhVQ==",
+    "tarballUrl": "https://registry.npmjs.org/owlrunkit/-/owlrunkit-0.21.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.22.0",
+  "documentNamespace": "https://owlcoda.com/spdx/owlrunkit/0.22.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.22.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.22.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.22.0";
 export const RUNTIME_ROOT = ".owlcoda/runkit";
 
 const CORE_FILES = [
@@ -28,11 +28,13 @@ const CORE_FILES = [
   "deployment-workflow.mjs",
   "efficiency-metrics.mjs",
   "fleet-discovery.mjs",
+  "fleet-skill-plan.mjs",
   "finalize.mjs",
   "formal-workflow.mjs",
   "formal-preflight.mjs",
   "formal-supplemental-evidence.mjs",
   "human-status.mjs",
+  "hook-recovery.mjs",
   "inspect-presentation.mjs",
   "install-codex-skill.mjs",
   "lease-lifecycle.mjs",
@@ -107,11 +109,15 @@ 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/hook-recovery-v1.schema.json",
+  "schemas/inspect-compact-v1.schema.json",
+  "schemas/inspect-compact-v2.schema.json",
   "schemas/onboarding-bootstrap-plan-v1.schema.json",
   "schemas/onboarding-bootstrap-receipt-v1.schema.json",
   "schemas/outcome-summary-v1.schema.json",
@@ -150,8 +156,11 @@ 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-delivery-status-v3.schema.json",
   "schemas/team-packet-validation-v1.schema.json",
   "schemas/team-recommendation-v1.schema.json",
+  "schemas/team-recommendation-v2.schema.json",
   "schemas/team-task-packet-v2.schema.json",
   "schemas/visual-smoke-request-v1.schema.json",
   "schemas/visual-smoke-result-v1.schema.json",
@@ -162,10 +171,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 +213,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", "0.21.1", "0.22.0"]).has(
+      closeout.artifact.core?.coreVersion,
+    )
     && (
       !hasExactKeys(formalEvidenceBinding, [
         "schemaVersion",