owlrunkit 0.13.0 → 0.14.0

package/scripts/runkit-contract/profile-onboarding.mjs

@@ -0,0 +1,332 @@
+import {
+  existsSync,
+} from "node:fs";
+import path from "node:path";
+
+import {
+  readWorkspaceJsonBounded,
+  resolveBoundedWorkspaceRoot,
+} from "./onboarding-doctor.mjs";
+import { resolveProfileImpactDetailed } from "./profile-impact.mjs";
+import {
+  safeIdentifier,
+  safeRelativePath,
+} from "./provenance-common.mjs";
+
+function command(id, script) {
+  return {
+    id,
+    cwd: ".",
+    executable: "npm",
+    argv: ["run", script],
+  };
+}
+
+function detectedScripts(manifest) {
+  return Object.keys(manifest.scripts ?? {}).sort();
+}
+
+function profileCandidates(root, manifest) {
+  const scripts = new Set(detectedScripts(manifest));
+  const candidates = [];
+  if (
+    existsSync(path.join(root, "prisma"))
+    || [...scripts].some((script) => /^(db:|prisma)/.test(script))
+  ) {
+    const commands = [...scripts]
+      .filter((script) => /^(db:|prisma)/.test(script))
+      .map((script) => command(`npm-${script.replaceAll(":", "-")}`, script));
+    candidates.push({
+      id: "database",
+      paths: ["prisma/**"],
+      role: "primary",
+      primary: false,
+      requiresProfileIds: [],
+      commands,
+    });
+  }
+  if (
+    existsSync(path.join(root, "package.json"))
+    && [...scripts].some((script) => ["build", "lint", "test", "typecheck"].includes(script))
+  ) {
+    const commands = ["build", "lint", "test", "typecheck"]
+      .filter((script) => scripts.has(script))
+      .map((script) => command(`npm-${script}`, script));
+    candidates.push({
+      id: "node-quality",
+      paths: ["src/**", "tests/**"],
+      role: "primary",
+      primary: false,
+      requiresProfileIds: [],
+      commands,
+    });
+  }
+  if (
+    existsSync(path.join(root, "playwright.config.ts"))
+    || existsSync(path.join(root, "playwright.config.js"))
+    || scripts.has("e2e")
+  ) {
+    const commands = scripts.has("e2e") ? [command("npm-e2e", "e2e")] : [];
+    candidates.push({
+      id: "web-e2e",
+      paths: ["playwright.config.ts", "tests/e2e/**"],
+      role: "primary",
+      primary: false,
+      requiresProfileIds: [],
+      commands,
+    });
+  }
+  return candidates.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function detectProfiles({ workspaceRoot } = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const manifest = readWorkspaceJsonBounded(root, "package.json");
+  const candidates = profileCandidates(root, manifest);
+  const primaryCandidates = candidates.filter((profile) => profile.role === "primary");
+  return {
+    schemaVersion: "OwlCodaRunKitProfileDetectionV1",
+    status: "profiles_detected",
+    dryRun: true,
+    writesPerformed: 0,
+    candidates,
+    primaryProfileId: primaryCandidates.length === 1 ? primaryCandidates[0].id : null,
+    warnings: primaryCandidates.length > 1
+      ? [`ambiguous_primary_profile:${primaryCandidates.map((profile) => profile.id).join(",")}`]
+      : [],
+    detectedScripts: detectedScripts(manifest),
+    authorizationGranted: false,
+  };
+}
+
+function exactKeys(value, allowed) {
+  return value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function representativePath(rule) {
+  return rule.endsWith("/**")
+    ? `${rule.slice(0, -3)}/__owlrunkit_profile_surface__`
+    : rule;
+}
+
+function validateProfileDocument(config) {
+  const issues = [];
+  if (
+    !exactKeys(config, ["schemaVersion", "profiles"])
+    || config.schemaVersion !== "OwlCodaRunKitProfilesV1"
+    || !Array.isArray(config.profiles)
+    || config.profiles.length === 0
+  ) {
+    return ["profiles_document_invalid"];
+  }
+
+  const ids = new Set();
+  const commandIds = new Set();
+  for (const profile of config.profiles) {
+    if (!exactKeys(profile, [
+      "commands",
+      "id",
+      "paths",
+      "primary",
+      "requiresProfileIds",
+      "role",
+    ])) {
+      issues.push("profile_shape_invalid");
+      continue;
+    }
+    if (typeof profile.id !== "string" || profile.id.length === 0) {
+      issues.push("profile_id_invalid");
+    } else if (ids.has(profile.id)) {
+      issues.push(`duplicate_profile_id:${profile.id}`);
+    } else {
+      ids.add(profile.id);
+    }
+    if (!Array.isArray(profile.paths) || profile.paths.length === 0) {
+      issues.push(`profile_paths_missing:${profile.id ?? "unknown"}`);
+    }
+    if (profile.role !== undefined && !["primary", "supporting"].includes(profile.role)) {
+      issues.push(`profile_role_invalid:${profile.id ?? "unknown"}`);
+    }
+    if (profile.primary !== undefined && typeof profile.primary !== "boolean") {
+      issues.push(`profile_primary_invalid:${profile.id ?? "unknown"}`);
+    }
+    if (
+      profile.requiresProfileIds !== undefined
+      && (
+        !Array.isArray(profile.requiresProfileIds)
+        || profile.requiresProfileIds.some((id) => typeof id !== "string" || id.length === 0)
+        || new Set(profile.requiresProfileIds).size !== profile.requiresProfileIds.length
+      )
+    ) {
+      issues.push(`profile_requirements_invalid:${profile.id ?? "unknown"}`);
+    }
+    if (profile.commands !== undefined) {
+      if (!Array.isArray(profile.commands)) {
+        issues.push(`profile_commands_invalid:${profile.id ?? "unknown"}`);
+      } else {
+        for (const entry of profile.commands) {
+          if (
+            !exactKeys(entry, ["argv", "cwd", "executable", "id"])
+            || typeof entry.id !== "string"
+            || entry.id.length === 0
+            || typeof entry.cwd !== "string"
+            || entry.cwd.length === 0
+            || typeof entry.executable !== "string"
+            || entry.executable.length === 0
+            || !Array.isArray(entry.argv)
+            || entry.argv.some((argument) => typeof argument !== "string" || argument.length === 0)
+          ) {
+            issues.push(`profile_command_invalid:${profile.id ?? "unknown"}`);
+            break;
+          }
+          try {
+            safeIdentifier(entry.id, "profile command id");
+          } catch {
+            issues.push(`profile_command_id_invalid:${profile.id}:${entry.id}`);
+          }
+          try {
+            safeRelativePath(entry.cwd, "profile command cwd", { allowDot: true });
+          } catch {
+            issues.push(`profile_command_cwd_invalid:${profile.id}:${entry.id}`);
+          }
+          if (commandIds.has(entry.id)) {
+            issues.push(`duplicate_profile_command_id:${entry.id}`);
+          } else {
+            commandIds.add(entry.id);
+          }
+        }
+      }
+    }
+  }
+  if (issues.length > 0) return [...new Set(issues)].sort();
+
+  try {
+    const changedPaths = config.profiles.flatMap((profile) =>
+      profile.paths.map(representativePath));
+    resolveProfileImpactDetailed({ changedPaths, profiles: config.profiles });
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+  }
+
+  for (const profile of config.profiles) {
+    for (const requiredId of profile.requiresProfileIds ?? []) {
+      if (!ids.has(requiredId)) {
+        issues.push(`required_profile_missing:${profile.id}:${requiredId}`);
+      }
+    }
+  }
+  const actionable = config.profiles.filter((profile) =>
+    (profile.role ?? "primary") === "primary"
+    && Array.isArray(profile.commands)
+    && profile.commands.length > 0);
+  if (actionable.length === 0) issues.push("actionable_primary_profile_missing");
+  const explicitPrimaryIds = actionable
+    .filter((profile) => profile.primary === true)
+    .map((profile) => profile.id)
+    .sort();
+  if (explicitPrimaryIds.length > 1) {
+    issues.push(`ambiguous_primary_profile:${explicitPrimaryIds.join(",")}`);
+  } else if (explicitPrimaryIds.length === 0 && actionable.length > 1) {
+    issues.push(`ambiguous_primary_profile:${actionable.map((profile) => profile.id).sort().join(",")}`);
+  }
+  return [...new Set(issues)].sort();
+}
+
+export function validateProfiles({ workspaceRoot } = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const issues = [];
+  let profileIds = [];
+  try {
+    const config = readWorkspaceJsonBounded(
+      root,
+      path.join(".owlcoda", "runkit", "profiles.json"),
+    );
+    profileIds = Array.isArray(config.profiles)
+      ? config.profiles
+        .map((profile) => profile?.id)
+        .filter((id) => typeof id === "string")
+        .sort()
+      : [];
+    issues.push(...validateProfileDocument(config));
+    if (issues.length === 0) {
+      const detected = detectProfiles({ workspaceRoot: root });
+      const detectedPaths = detected.candidates.flatMap((profile) =>
+        profile.paths.map(representativePath));
+      if (detectedPaths.length > 0) {
+        const impact = resolveProfileImpactDetailed({
+          changedPaths: detectedPaths,
+          profiles: config.profiles,
+        });
+        issues.push(...impact.uncoveredPaths.map((value) =>
+          `uncovered_detected_surface:${value}`));
+        issues.push(...impact.warnings
+          .filter((warning) => warning.startsWith("supporting_only_match:"))
+          .map((warning) => `detected_surface_${warning}`));
+      }
+    }
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+  }
+  const valid = issues.length === 0;
+  return {
+    schemaVersion: "OwlCodaRunKitProfilesValidationV1",
+    status: valid ? "valid" : "invalid",
+    valid,
+    exitCode: valid ? 0 : 2,
+    profileIds,
+    issues: [...new Set(issues)].sort(),
+    authorizationGranted: false,
+  };
+}
+
+export function resolveProfilesImpact({ workspaceRoot, changedPaths } = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const config = readWorkspaceJsonBounded(
+    root,
+    path.join(".owlcoda", "runkit", "profiles.json"),
+  );
+  const documentIssues = validateProfileDocument(config);
+  if (documentIssues.length > 0) {
+    return {
+      schemaVersion: "OwlCodaRunKitProfileImpactV1",
+      status: "profile_impact_blocked",
+      valid: false,
+      exitCode: 2,
+      changedPaths: [...new Set(changedPaths)].sort(),
+      decision: "invalid_profiles",
+      primaryProfileId: null,
+      directProfileIds: [],
+      transitiveProfileIds: [],
+      supportingProfileIds: [],
+      selectedProfileIds: [],
+      uncoveredPaths: [],
+      warnings: [],
+      issues: documentIssues,
+      authorizationGranted: false,
+    };
+  }
+  const impact = resolveProfileImpactDetailed({
+    changedPaths,
+    profiles: config.profiles,
+  });
+  const issues = [
+    ...impact.uncoveredPaths.map((value) => `uncovered_changed_path:${value}`),
+    ...impact.warnings.filter((warning) =>
+      warning.startsWith("supporting_only_match:")
+      || warning.startsWith("ambiguous_primary_profile:")),
+  ];
+  const valid = impact.decision === "targeted_profiles" && issues.length === 0;
+  return {
+    schemaVersion: "OwlCodaRunKitProfileImpactV1",
+    status: valid ? "profile_impact_resolved" : "profile_impact_blocked",
+    valid,
+    exitCode: valid ? 0 : 2,
+    changedPaths: [...new Set(changedPaths)].sort(),
+    ...impact,
+    issues: [...new Set(issues)].sort(),
+    authorizationGranted: false,
+  };
+}

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

@@ -32,12 +32,12 @@ function decision(policy, issueCodes) {
   };
 }
 
-function expectedTarballUrl(policy) {
-  const tarballName = policy.packageName.split("/").at(-1);
-  return `${OFFICIAL_NPM_REGISTRY}/${policy.packageName}/-/${tarballName}-${policy.candidateVersion}.tgz`;
+export function expectedRegistryTarballUrl(packageName, version) {
+  const tarballName = packageName.split("/").at(-1);
+  return `${OFFICIAL_NPM_REGISTRY}/${packageName}/-/${tarballName}-${version}.tgz`;
 }
 
-function validSha512Integrity(value) {
+export function isCanonicalSha512Integrity(value) {
   if (typeof value !== "string") return false;
   const match = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(value);
   if (!match) return false;
@@ -49,9 +49,12 @@ function validReleaseEvidence(policy, release) {
   if (
     policy.registry !== OFFICIAL_NPM_REGISTRY
     || Object.keys(release).sort().join("\n") !== RELEASE_EVIDENCE_FIELDS.join("\n")
-    || !/^[0-9a-f]{40}$/.test(release.shasum)
-    || !validSha512Integrity(release.integrity)
-    || release.tarballUrl !== expectedTarballUrl(policy)
+    || !/^[0-9a-f]{40}$/i.test(release.shasum)
+    || !isCanonicalSha512Integrity(release.integrity)
+    || release.tarballUrl !== expectedRegistryTarballUrl(
+      policy.packageName,
+      policy.candidateVersion,
+    )
   ) {
     return false;
   }

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

@@ -0,0 +1,197 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+
+import {
+  OFFICIAL_NPM_REGISTRY,
+  evaluateRegistryAdoption,
+} from "./registry-adoption-gate.mjs";
+import {
+  readLocalInstallBinding,
+  readRegistryExact,
+  resolveBoundedWorkspaceRoot,
+} from "./onboarding-doctor.mjs";
+import { writeJsonExclusiveAtomically } from "./provenance-common.mjs";
+
+const PACKAGE_NAME = "owlrunkit";
+const CANDIDATE_VERSION = "0.14.0";
+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,