owlrunkit 0.13.0 → 0.15.0

package/scripts/runkit-contract/registry-adoption.mjs

@@ -0,0 +1,198 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+
+import {
+  OFFICIAL_NPM_REGISTRY,
+  evaluateRegistryAdoption,
+} from "./registry-adoption-gate.mjs";
+import { CORE_VERSION } from "./core-contract.mjs";
+import {
+  readLocalInstallBinding,
+  readRegistryExact,
+  resolveBoundedWorkspaceRoot,
+} from "./onboarding-doctor.mjs";
+import { writeJsonExclusiveAtomically } from "./provenance-common.mjs";
+
+const PACKAGE_NAME = "owlrunkit";
+const CANDIDATE_VERSION = CORE_VERSION;
+const EXACT_SPEC = `${PACKAGE_NAME}@${CANDIDATE_VERSION}`;
+
+const POLICY = Object.freeze({
+  schemaVersion: "OwlCodaRunKitRegistryReleasePolicyV1",
+  status: "registry_verified",
+  packageName: PACKAGE_NAME,
+  candidateVersion: CANDIDATE_VERSION,
+  registry: OFFICIAL_NPM_REGISTRY,
+  registryRequiredBeforeAdoption: true,
+  exactVersionRequired: true,
+  requiredRegistryBindings: [
+    "packageName",
+    "version",
+    "shasum",
+    "integrity",
+    "tarballUrl",
+  ],
+  forbiddenAdoptionSources: [
+    "directory",
+    "file",
+    "git",
+    "local_tarball",
+    "symlink",
+    "workspace",
+  ],
+  currentPublishedRelease: null,
+  registryRelease: null,
+  registryEvidenceMustBeExternal: true,
+  registryEvidenceSchemaVersion: "OwlCodaRunKitRegistryReleaseEvidenceV1",
+  embeddedAttestComponentVersion: "0.2.0",
+  standaloneAttestPublicationRequired: false,
+  signatureRequired: false,
+  githubActionRequired: false,
+  foreignProjectWriteAuthorized: false,
+  authorizationGranted: false,
+});
+
+function ineligible(issueCodes) {
+  return {
+    schemaVersion: "OwlCodaRunKitRegistryAdoptionResultV1",
+    status: "ineligible",
+    decision: "INELIGIBLE",
+    issueCodes,
+    packageName: PACKAGE_NAME,
+    version: CANDIDATE_VERSION,
+    authorizationGranted: false,
+  };
+}
+
+function assertRealDirectory(directory, label) {
+  const stat = lstatSync(directory);
+  if (stat.isSymbolicLink() || !stat.isDirectory() || realpathSync(directory) !== path.resolve(directory)) {
+    throw new Error(`${label} must be a real directory without symlink ancestors.`);
+  }
+}
+
+function adoptionRoot(workspaceRoot) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const owlcodaRoot = path.join(root, ".owlcoda");
+  const runtimeRoot = path.join(owlcodaRoot, "runkit");
+  assertRealDirectory(owlcodaRoot, ".owlcoda");
+  assertRealDirectory(runtimeRoot, "RunKit runtime");
+  const target = path.join(runtimeRoot, "adoption");
+  if (!existsSync(target)) mkdirSync(target);
+  assertRealDirectory(target, "RunKit adoption directory");
+  return target;
+}
+
+export async function runRegistryAdoption({
+  workspaceRoot,
+  exactSpec,
+  registryClient,
+  timeoutMs = 1_500,
+} = {}) {
+  if (exactSpec !== EXACT_SPEC) return ineligible(["exact_registry_spec_required"]);
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const local = readLocalInstallBinding({ workspaceRoot: root });
+  if (local.status !== "bound") {
+    return ineligible(local.issueCodes ?? ["registry_install_binding_mismatch"]);
+  }
+  const observedRelease = registryClient
+    ? await registryClient.readExact({
+        registry: OFFICIAL_NPM_REGISTRY,
+        packageName: PACKAGE_NAME,
+        version: CANDIDATE_VERSION,
+      })
+    : await readRegistryExact({
+        registryUrl: OFFICIAL_NPM_REGISTRY,
+        packageName: PACKAGE_NAME,
+        version: CANDIDATE_VERSION,
+        timeoutMs,
+      });
+  const release = observedRelease.status === "registry_verified"
+    ? {
+        schemaVersion: "OwlCodaRunKitRegistryReleaseEvidenceV1",
+        ...observedRelease,
+      }
+    : observedRelease;
+  if (release.status !== "registry_verified") {
+    return ineligible(release.issueCodes ?? ["registry_release_not_verified"]);
+  }
+  const install = {
+    kind: "registry",
+    requestedSpec: EXACT_SPEC,
+    packageName: local.packageName,
+    version: local.version,
+    shasum: release.shasum,
+    integrity: local.integrity,
+    resolved: local.resolved,
+  };
+  const decision = evaluateRegistryAdoption({
+    policy: POLICY,
+    releaseEvidence: release,
+    install,
+  });
+  if (decision.decision !== "ELIGIBLE") return ineligible(decision.issueCodes);
+
+  const relativeEvidencePath = `.owlcoda/runkit/adoption/${PACKAGE_NAME}-${CANDIDATE_VERSION}.json`;
+  const evidencePath = path.join(adoptionRoot(root), `${PACKAGE_NAME}-${CANDIDATE_VERSION}.json`);
+  const evidence = {
+    schemaVersion: "OwlCodaRunKitRegistryAdoptionEvidenceV1",
+    status: "adopted",
+    decision: "ELIGIBLE",
+    packageName: PACKAGE_NAME,
+    version: CANDIDATE_VERSION,
+    exactSpec: EXACT_SPEC,
+    registryRelease: {
+      registry: release.registry,
+      packageName: release.packageName,
+      version: release.version,
+      shasum: release.shasum,
+      integrity: release.integrity,
+      tarballUrl: release.tarballUrl,
+    },
+    installedBinding: {
+      requestedSpec: local.requestedSpec,
+      packageName: local.packageName,
+      version: local.version,
+      resolved: local.resolved,
+      integrity: local.integrity,
+    },
+    authority: {
+      git: false,
+      release: false,
+      foreignProjectWrite: false,
+    },
+    authorizationGranted: false,
+  };
+  writeJsonExclusiveAtomically(evidencePath, evidence);
+  return {
+    schemaVersion: "OwlCodaRunKitRegistryAdoptionResultV1",
+    status: "adopted",
+    decision: "ELIGIBLE",
+    evidencePath: relativeEvidencePath,
+    issueCodes: [],
+    packageName: PACKAGE_NAME,
+    version: CANDIDATE_VERSION,
+    authorizationGranted: false,
+  };
+}
+
+export function formatAdoptionHuman(result) {
+  if (result.status === "adopted") {
+    return [
+      `Adopted ${result.packageName}@${result.version}`,
+      `Evidence: ${result.evidencePath}`,
+      "Git and release authority remain false.",
+      "",
+    ].join("\n");
+  }
+  return [
+    `Adoption blocked: ${result.issueCodes.join(", ")}`,
+    "No adoption evidence was written.",
+    "",
+  ].join("\n");
+}

package/scripts/runkit-contract/resume-execution.mjs

@@ -94,6 +94,11 @@ function assertRegularArtifact(filePath, label) {
   if (!stat.isFile()) throw new Error(`${label} must be a regular file.`);
 }
 
+function readRegularJsonArtifact(filePath, label) {
+  assertRegularArtifact(filePath, label);
+  return readJson(filePath);
+}
+
 function acquireResumeLock(workspaceRoot) {
   const runtimeRoot = path.join(workspaceRoot, RUNTIME_ROOT);
   assertSafeDirectory(workspaceRoot, runtimeRoot, "RunKit runtime root");
@@ -299,7 +304,7 @@ function validatedParentCloseout(workspaceRoot, sourceRoot, sourceRunId) {
     throw new Error("Parent closeout payload is invalid.");
   }
   if (payload.decision === "accepted") validateAcceptedParentEvidence(sourceRoot, sourceRunId, payload.verification);
-  const pin = readJson(path.join(sourceRoot, "engine-pin.json"));
+  const pin = readRegularJsonArtifact(path.join(sourceRoot, "engine-pin.json"), "Parent engine pin");
   const pinGate = validateExecutionPin({ expected: pin, actual: closeout.artifact.core });
   if (pinGate.status !== "valid") throw new Error(`Parent closeout does not match its engine pin: ${pinGate.issues.join("; ")}`);
   return {
@@ -392,7 +397,7 @@ function appendSameExecution({ workspaceRoot, sourceRunId, sourceRoot, request,
     throw new Error("Unclosed execution resume requires continuationRunId=null.");
   }
   assertSoleActiveRun(workspaceRoot, sourceRunId);
-  const pin = readJson(path.join(sourceRoot, "engine-pin.json"));
+  const pin = readRegularJsonArtifact(path.join(sourceRoot, "engine-pin.json"), "Resume engine pin");
   const pinGate = validateExecutionPin({ expected: pin, actual: currentCoreIdentity() });
   if (pinGate.status !== "valid") throw new Error(`Resume engine pin is stale: ${pinGate.issues.join("; ")}`);
   assertNoActiveWriterLease(sourceRoot);
@@ -507,6 +512,7 @@ function createContinuation({ workspaceRoot, sourceRunId, sourceRoot, request, g
       runId: targetRunId,
       state: "planned",
       enginePin,
+      goalContractSha256: sha256(goal.bytes),
       continuation: {
         parentRunId: sourceRunId,
         resumeId: request.resumeId,

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

@@ -15,6 +15,7 @@ import {
 import path from "node:path";
 
 import {
+  CORE_VERSION,
   RUNTIME_ROOT,
   acceptedCloseoutVerificationIssues,
   createCoreArtifact,
@@ -66,6 +67,120 @@ import {
   exportOfflineReceipt,
   importOfflineReceipt,
 } from "./offline-store.mjs";
+import {
+  detectProfiles,
+  resolveProfilesImpact,
+  validateProfiles,
+} from "./profile-onboarding.mjs";
+import {
+  formatDoctorHuman,
+  readAdoptionReadiness,
+  readProfileLauncherReadiness,
+  runDoctor,
+} from "./onboarding-doctor.mjs";
+import {
+  formatAdoptionHuman,
+  runRegistryAdoption,
+} from "./registry-adoption.mjs";
+import { OFFICIAL_NPM_REGISTRY } from "./registry-adoption-gate.mjs";
+
+const TOP_LEVEL_HELP = `OwlRunKit ${CORE_VERSION}
+
+Usage:
+  owlrunkit <command> [options]
+
+Start here:
+  owlrunkit doctor --workspace .
+  owlrunkit profiles detect --workspace . --dry-run
+  owlrunkit adopt --workspace . --exact owlrunkit@${CORE_VERSION}
+
+Quick Verification
+  owlrunkit quick-verify --workspace . -- <command> [args...]
+  Low-risk, source-bound reusable evidence without writer leases or acceptance.
+
+Formal Delivery
+  owlrunkit start --workspace . --run-id <id> --goal <file> \\
+    --work-item <id> --owned-path <path>
+  Use for multi-writer, long-running, migration, integration, release, funds,
+  production, or formal acceptance work.
+
+Other onboarding commands:
+  owlrunkit profiles validate --workspace .
+  owlrunkit profiles impact --workspace . --changed <path>
+  owlrunkit inspect --workspace . --json
+
+Quick receipts cannot become Formal acceptance.
+Formal accepted does not grant Git or release authority.
+Those always require separate explicit authorization.
+`;
+
+function withHumanOutput(result, humanOutput) {
+  Object.defineProperty(result, "humanOutput", {
+    configurable: false,
+    enumerable: false,
+    value: humanOutput,
+    writable: false,
+  });
+  return result;
+}
+
+function profilesReadiness(root) {
+  if (!root) return { valid: false, launcherWarnings: [] };
+  try {
+    const validation = validateProfiles({ workspaceRoot: root });
+    const launchers = readProfileLauncherReadiness({ workspaceRoot: root });
+    return {
+      valid: validation.valid === true && launchers.ready,
+      launcherWarnings: launchers.launcherWarnings,
+    };
+  } catch {
+    return { valid: false, launcherWarnings: [] };
+  }
+}
+
+function onboardingProjection(root, recovery = null) {
+  const profiles = profilesReadiness(root);
+  const adoption = root
+    ? readAdoptionReadiness({ workspaceRoot: root })
+    : { status: "missing" };
+  const profilesReady = profiles.valid;
+  const adoptionReady = adoption.status === "ok";
+  if (profilesReady && adoptionReady) {
+    return {
+      nextAllowedAction: recovery?.nextAllowedAction ?? "plan_new_execution",
+      completed: true,
+      steps: [],
+    };
+  }
+  const steps = [
+    {
+      id: "doctor",
+      command: "owlrunkit doctor --workspace .",
+    },
+    ...(!profilesReady
+      ? profiles.launcherWarnings.length > 0
+        ? [{
+            id: "profile_launchers_review",
+            command: "owlrunkit doctor --workspace .",
+          }]
+        : [{
+          id: "profiles_detect",
+          command: "owlrunkit profiles detect --workspace . --dry-run",
+        }]
+      : []),
+    ...(!adoptionReady
+      ? [{
+          id: "adopt_or_start",
+          command: `owlrunkit adopt --workspace . --exact owlrunkit@${CORE_VERSION} or owlrunkit start`,
+        }]
+      : []),
+  ];
+  return {
+    nextAllowedAction: "run_onboarding_diagnostics",
+    completed: false,
+    steps,
+  };
+}
 
 function parseOptions(values, { multi = [], boolean = [] } = {}) {
   const options = {};
@@ -592,7 +707,26 @@ function closeoutGateRejected(runId, decision, issues) {
 }
 
 async function initialize(options) {
-  return initializeProjectRunKit({ workspaceRoot: workspace(options) });
+  const root = workspace(options);
+  const initialized = await initializeProjectRunKit({ workspaceRoot: root });
+  const result = {
+    ...initialized,
+    onboarding: onboardingProjection(root),
+    nextAllowedAction: "run_onboarding_diagnostics",
+  };
+  if (options.json === true) return result;
+  return withHumanOutput(
+    result,
+    [
+      `Initialized OwlRunKit ${result.core.coreVersion} in ${result.runtimeRoot}`,
+      "",
+      "Next:",
+      "1. owlrunkit doctor --workspace .",
+      "2. owlrunkit profiles detect --workspace . --dry-run",
+      `3. owlrunkit adopt --workspace . --exact owlrunkit@${CORE_VERSION} or owlrunkit start`,
+      "",
+    ].join("\n"),
+  );
 }
 
 function plan(options) {
@@ -844,7 +978,7 @@ function inspect(options) {
           execution: executions.find(execution => execution.runId === requestedRunId),
         }
       : { mode: "summary" };
-  return { ...result, summary, view };
+  return { ...result, summary, view, onboarding: onboardingProjection(root, recovery) };
 }
 
 function closeout(options) {
@@ -1025,29 +1159,95 @@ function requestCommand(options, handler) {
 export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
   try {
     const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h") {
+      return withHumanOutput({
+        status: "help",
+        exitCode: 0,
+        authorizationGranted: false,
+      }, TOP_LEVEL_HELP);
+    }
+    if (command === "--version" || command === "-v") {
+      return withHumanOutput({
+        status: "version",
+        exitCode: 0,
+        version: CORE_VERSION,
+        authorizationGranted: false,
+      }, `owlrunkit ${CORE_VERSION}\n`);
+    }
     const separatorIndex = rest.indexOf("--");
     if (separatorIndex >= 0 && command !== "verify" && command !== "quick-verify") {
       throw new Error("Only runkit verify accepts an exact command after --.");
     }
     const optionValues = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : rest;
     const commandArgv = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : [];
-    const nested = new Set(["lease", "delivery"]).has(command);
+    const nested = new Set(["lease", "delivery", "profiles"]).has(command);
     const [action, ...nestedOptions] = nested ? optionValues : [null, ...optionValues];
     const options = parseOptions(nested ? nestedOptions : optionValues, {
-      multi: (command === "lease" && action === "acquire") || command === "start" ? ["owned-path"] : [],
+      multi: command === "profiles" && action === "impact"
+        ? ["changed"]
+        : (command === "lease" && action === "acquire") || command === "start"
+          ? ["owned-path"]
+          : [],
       boolean: command === "inspect"
         ? ["json", "verbose", "history"]
+        : command === "init"
+          ? ["json"]
+          : command === "doctor" || command === "adopt"
+            ? ["json"]
+          : command === "profiles"
+            ? ["json", "dry-run"]
         : new Set(["quick-verify", "quick-attest", "quick-metrics"]).has(command)
           ? ["json", "local"]
           : [],
     });
     if (command === "init") return await initialize(options);
+    if (command === "doctor") {
+      const timeoutMs = options["timeout-ms"] === undefined
+        ? 1_500
+        : Number.parseInt(options["timeout-ms"], 10);
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 25 || timeoutMs > 10_000) {
+        throw new Error("--timeout-ms must be an integer from 25 to 10000.");
+      }
+      const report = await runDoctor({
+        workspaceRoot: requireOption(options, "workspace"),
+        registryUrl: options.registry ?? OFFICIAL_NPM_REGISTRY,
+        timeoutMs,
+      });
+      report.exitCode = report.status === "ready" ? 0 : 2;
+      return options.json === true
+        ? report
+        : withHumanOutput(report, formatDoctorHuman(report));
+    }
+    if (command === "adopt") {
+      const result = await runRegistryAdoption({
+        workspaceRoot: requireOption(options, "workspace"),
+        exactSpec: requireOption(options, "exact"),
+      });
+      result.exitCode = result.status === "adopted" ? 0 : 2;
+      return options.json === true
+        ? result
+        : withHumanOutput(result, formatAdoptionHuman(result));
+    }
     if (command === "start") return startExecution(options);
     if (command === "plan") {
       const root = workspace(options);
       return withControlTransaction(root, () => plan(options));
     }
     if (command === "inspect") return inspect(options);
+    if (command === "profiles") {
+      const root = requireOption(options, "workspace");
+      if (action === "detect") {
+        if (options["dry-run"] !== true) throw new Error("profiles detect requires --dry-run.");
+        return detectProfiles({ workspaceRoot: root });
+      }
+      if (action === "validate") return validateProfiles({ workspaceRoot: root });
+      if (action === "impact") {
+        const changedPaths = options.changed ?? [];
+        if (changedPaths.length === 0) throw new Error("profiles impact requires --changed.");
+        return resolveProfilesImpact({ workspaceRoot: root, changedPaths });
+      }
+      throw new Error("Usage: owlrunkit profiles <detect|validate|impact> [options]");
+    }
     if (command === "lease") {
       const root = workspace(options);
       const runId = safeRunId(requireOption(options, "run-id"));
@@ -1184,7 +1384,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       return withControlTransaction(root, () => closeout(options));
     }
     if (command === "finish") return finishExecution(options);
-    throw new Error("Usage: runkit-cli.mjs <init|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
+    throw new Error("Usage: owlrunkit <init|doctor|adopt|profiles|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
   } catch (error) {
     return {
       status: "invalid_input",
@@ -1209,6 +1409,16 @@ if (isDirectExecution(import.meta.url)) {
     ? parseOptions(argv.slice(1), { boolean: ["json", "verbose", "history"] })
     : null;
   const humanInspect = inspectOptions !== null && inspectOptions.json !== true;
-  process.stdout.write(humanInspect ? formatInspectHuman(result) : `${JSON.stringify(result)}\n`);
+  const onboardingHumanCommand = new Set(["init", "doctor", "adopt", "profiles"]).has(argv[0]);
+  const interactiveOnboarding = onboardingHumanCommand
+    && !argv.includes("--json")
+    && process.stdout.isTTY === true;
+  process.stdout.write(
+    typeof result.humanOutput === "string" && (!onboardingHumanCommand || interactiveOnboarding)
+      ? result.humanOutput
+      : humanInspect
+        ? formatInspectHuman(result)
+        : `${JSON.stringify(result)}\n`,
+  );
   process.exitCode = result.exitCode;
 }

package/scripts/runkit-contract/schemas/adoption-evidence-v1.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/registry-adoption-evidence-v1.json",
+  "title": "OwlCoda RunKit Registry Adoption Evidence V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "decision",
+    "packageName",
+    "version",
+    "exactSpec",
+    "registryRelease",
+    "installedBinding",
+    "authority",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitRegistryAdoptionEvidenceV1" },
+    "status": { "const": "adopted" },
+    "decision": { "const": "ELIGIBLE" },
+    "packageName": { "const": "owlrunkit" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "exactSpec": { "type": "string", "pattern": "^owlrunkit@[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "registryRelease": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["registry", "packageName", "version", "shasum", "integrity", "tarballUrl"],
+      "properties": {
+        "registry": { "const": "https://registry.npmjs.org" },
+        "packageName": { "const": "owlrunkit" },
+        "version": { "type": "string" },
+        "shasum": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "integrity": { "type": "string", "pattern": "^sha512-" },
+        "tarballUrl": { "type": "string", "pattern": "^https://registry\\.npmjs\\.org/owlrunkit/-/owlrunkit-[0-9]+\\.[0-9]+\\.[0-9]+\\.tgz$" }
+      }
+    },
+    "installedBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requestedSpec", "packageName", "version", "resolved", "integrity"],
+      "properties": {
+        "requestedSpec": { "type": "string" },
+        "packageName": { "const": "owlrunkit" },
+        "version": { "type": "string" },
+        "resolved": { "type": "string" },
+        "integrity": { "type": "string" }
+      }
+    },
+    "authority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["git", "release", "foreignProjectWrite"],
+      "properties": {
+        "git": { "const": false },
+        "release": { "const": false },
+        "foreignProjectWrite": { "const": false }
+      }
+    },
+    "authorizationGranted": { "const": false }
+  }
+}

package/scripts/runkit-contract/schemas/verification-finalize-attempt-v1.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/verification-finalize-attempt-v1.json",
+  "title": "OwlCoda RunKit Verification Finalize Attempt V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runId",
+    "verificationId",
+    "status",
+    "gateStatus",
+    "finalizeRequestPath",
+    "finalizeRequestSha256",
+    "result",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "OwlCodaRunKitVerificationFinalizeAttemptV1"
+    },
+    "runId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
+    "verificationId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
+    "status": {
+      "const": "rejected"
+    },
+    "gateStatus": {
+      "type": "string",
+      "minLength": 1
+    },
+    "finalizeRequestPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "finalizeRequestSha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "result": {
+      "type": "object"
+    },
+    "authorizationGranted": {
+      "const": false
+    }
+  }
+}

package/scripts/runkit-contract/schemas/verification-preflight-v1.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/verification-preflight-v1.json",
+  "title": "OwlCoda RunKit Verification Preflight V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runId",
+    "verificationId",
+    "status",
+    "issueCode",
+    "executable",
+    "commandArgvSha256",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "OwlCodaRunKitVerificationPreflightV1"
+    },
+    "runId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
+    "verificationId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
+    "status": {
+      "const": "rejected"
+    },
+    "issueCode": {
+      "enum": [
+        "verify_executable_absolute_path_required",
+        "verify_executable_missing",
+        "verify_executable_not_regular_file",
+        "verify_executable_symlink_rejected"
+      ]
+    },
+    "executable": {
+      "type": "string",
+      "minLength": 1
+    },
+    "commandArgvSha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "authorizationGranted": {
+      "const": false
+    }
+  }
+}