owlrunkit 0.15.0 → 0.16.0

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

@@ -1,8 +1,14 @@
+import { createHash } from "node:crypto";
 import {
   existsSync,
   lstatSync,
+  linkSync,
+  mkdirSync,
+  readFileSync,
   readdirSync,
   realpathSync,
+  rmSync,
+  writeFileSync,
 } from "node:fs";
 import path from "node:path";
 
@@ -36,6 +42,355 @@ function resolveRegularExecutable(name) {
   return null;
 }
 
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, nested]) => `${JSON.stringify(key)}:${canonicalJson(nested)}`)
+      .join(",")}}`;
+  }
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) throw new Error("profile_detection_noncanonical_value");
+  return encoded;
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function boundedRegularFile(root, relativePath) {
+  safeRelativePath(relativePath, "profile detection input");
+  const absolute = path.resolve(root, relativePath);
+  const relative = path.relative(root, absolute);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`profile_detection_input_outside_workspace:${relativePath}`);
+  }
+  const stat = lstatSync(absolute);
+  const resolved = realpathSync(absolute);
+  if (
+    stat.isSymbolicLink()
+    || !stat.isFile()
+    || resolved !== absolute
+  ) {
+    throw new Error(`profile_detection_input_not_regular:${relativePath}`);
+  }
+  return absolute;
+}
+
+function insideRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative !== ".."
+    && !relative.startsWith(`..${path.sep}`)
+    && !path.isAbsolute(relative);
+}
+
+function ensureDirectoryChain(root, relativeDirectory) {
+  let current = root;
+  for (const segment of relativeDirectory.split("/")) {
+    current = path.join(current, segment);
+    try {
+      lstatSync(current);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      mkdirSync(current);
+    }
+    const stat = lstatSync(current);
+    const resolved = realpathSync(current);
+    if (
+      stat.isSymbolicLink()
+      || !stat.isDirectory()
+      || resolved !== current
+      || !insideRoot(root, resolved)
+    ) {
+      throw new Error("profile_apply_directory_untrusted");
+    }
+  }
+  return current;
+}
+
+function regularExecutable(value) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) return null;
+  try {
+    const resolved = realpathSync(value);
+    const stat = lstatSync(resolved);
+    return stat.isFile() && !stat.isSymbolicLink() ? resolved : null;
+  } catch {
+    return null;
+  }
+}
+
+function toolIdentity(executable, argvPrefix, version) {
+  const launcher = regularExecutable(argvPrefix[0] ?? executable);
+  if (!launcher || typeof version !== "string" || !/^[0-9]+\.[0-9]+\.[0-9]+/.test(version)) {
+    return null;
+  }
+  return {
+    version,
+    executableSha256: sha256(readFileSync(executable)),
+    launcherSha256: sha256(readFileSync(launcher)),
+  };
+}
+
+function defaultProjectNpm(root, manifest) {
+  try {
+    if (
+      typeof manifest.packageManager === "string"
+      && !manifest.packageManager.startsWith("npm@")
+    ) return null;
+    const lockPath = boundedRegularFile(root, "package-lock.json");
+    const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+    if (!Number.isInteger(lock.lockfileVersion)) return null;
+    const executable = regularExecutable(process.execPath);
+    if (!executable) return null;
+    const npmEntry = path.join(
+      path.dirname(executable),
+      process.platform === "win32" ? "npm.cmd" : "npm",
+    );
+    const npmCli = regularExecutable(npmEntry);
+    if (!npmCli || process.platform === "win32") return null;
+    const npmManifestPath = path.resolve(npmCli, "..", "..", "package.json");
+    const npmManifest = JSON.parse(readFileSync(npmManifestPath, "utf8"));
+    if (
+      npmManifest.name !== "npm"
+      || typeof npmManifest.version !== "string"
+      || (
+        typeof manifest.packageManager === "string"
+        && manifest.packageManager.startsWith("npm@")
+        && manifest.packageManager.slice(4) !== npmManifest.version
+      )
+    ) {
+      return null;
+    }
+    const identity = toolIdentity(executable, [npmCli], npmManifest.version);
+    if (!identity) return null;
+    return {
+      status: "resolved",
+      confidence: "high",
+      source: "project_lockfile",
+      packageManager: "npm",
+      executable,
+      argvPrefix: [npmCli],
+      inputFiles: ["package.json", "package-lock.json"],
+      issueCodes: [],
+      ...identity,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function selectedPackageManager(root, manifest) {
+  const declared = typeof manifest.packageManager === "string"
+    ? /^(npm|pnpm|yarn|bun)@([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)$/
+      .exec(manifest.packageManager)
+    : null;
+  const lockfiles = [
+    { manager: "npm", refs: ["package-lock.json"] },
+    { manager: "pnpm", refs: ["pnpm-lock.yaml"] },
+    { manager: "yarn", refs: ["yarn.lock"] },
+    { manager: "bun", refs: ["bun.lock", "bun.lockb"] },
+  ].flatMap(entry => entry.refs
+    .filter(ref => existsSync(path.join(root, ref)))
+    .map(ref => ({ manager: entry.manager, ref })));
+  if (lockfiles.length !== 1) return {
+    manager: declared?.[1] ?? null,
+    version: declared?.[2] ?? null,
+    lockfile: null,
+  };
+  if (declared && declared[1] !== lockfiles[0].manager) {
+    return {
+      manager: declared[1],
+      version: declared[2],
+      lockfile: null,
+    };
+  }
+  return {
+    manager: declared?.[1] ?? lockfiles[0].manager,
+    version: declared?.[2] ?? null,
+    lockfile: lockfiles[0].ref,
+  };
+}
+
+function defaultProjectInstalledManager(root, manifest) {
+  const selected = selectedPackageManager(root, manifest);
+  if (
+    selected.manager === null
+    || selected.manager === "npm"
+    || selected.version === null
+    || selected.lockfile === null
+  ) return null;
+  try {
+    boundedRegularFile(root, selected.lockfile);
+    const requestedPackageRoot = path.join(
+      root,
+      "node_modules",
+      selected.manager,
+    );
+    const packageRoot = realpathSync(requestedPackageRoot);
+    if (!insideRoot(root, packageRoot)) return null;
+    const managerManifestPath = path.join(packageRoot, "package.json");
+    const managerManifestStat = lstatSync(managerManifestPath);
+    if (
+      managerManifestStat.isSymbolicLink()
+      || !managerManifestStat.isFile()
+      || realpathSync(managerManifestPath) !== managerManifestPath
+    ) return null;
+    const managerManifest = JSON.parse(readFileSync(managerManifestPath, "utf8"));
+    if (
+      managerManifest.name !== selected.manager
+      || managerManifest.version !== selected.version
+    ) return null;
+    const declaredBin = typeof managerManifest.bin === "string"
+      ? managerManifest.bin
+      : managerManifest.bin?.[selected.manager];
+    if (typeof declaredBin !== "string" || declaredBin.length === 0) return null;
+    safeRelativePath(declaredBin, "project package manager bin");
+    const launcher = realpathSync(path.join(packageRoot, declaredBin));
+    const launcherStat = lstatSync(launcher);
+    if (
+      !insideRoot(root, launcher)
+      || launcherStat.isSymbolicLink()
+      || !launcherStat.isFile()
+    ) return null;
+    const executable = regularExecutable(process.execPath);
+    if (!executable) return null;
+    const identity = toolIdentity(executable, [launcher], selected.version);
+    if (!identity) return null;
+    const managerManifestRef = path.relative(root, managerManifestPath)
+      .split(path.sep)
+      .join("/");
+    const launcherRef = path.relative(root, launcher)
+      .split(path.sep)
+      .join("/");
+    return {
+      status: "resolved",
+      confidence: "high",
+      source: "project_install",
+      packageManager: selected.manager,
+      executable,
+      argvPrefix: [launcher],
+      inputFiles: [
+        "package.json",
+        selected.lockfile,
+        managerManifestRef,
+        launcherRef,
+      ].sort(),
+      issueCodes: [],
+      ...identity,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function resolveProjectTool(root, manifest, projectToolResolver) {
+  const selected = selectedPackageManager(root, manifest);
+  const packageManager = selected.manager ?? "npm";
+  if (typeof projectToolResolver === "function") {
+    try {
+      const resolved = projectToolResolver({
+        workspaceRoot: root,
+        tool: packageManager,
+        manifest: structuredClone(manifest),
+      });
+      const executable = regularExecutable(resolved?.executable);
+      const argvPrefix = Array.isArray(resolved?.argvPrefix)
+        && resolved.argvPrefix.every(value => typeof value === "string" && value.length > 0)
+        ? [...resolved.argvPrefix]
+        : null;
+      const inputFiles = Array.isArray(resolved?.inputFiles)
+        && resolved.inputFiles.every(value => typeof value === "string" && value.length > 0)
+        ? [...new Set(resolved.inputFiles)].sort()
+        : null;
+      const authoritativeSource = new Set([
+        "project_install",
+        "project_lockfile",
+        "project_toolchain",
+      ]).has(resolved?.source);
+      const identity = executable && argvPrefix
+        ? toolIdentity(executable, argvPrefix, resolved?.version)
+        : null;
+      const lockBound = inputFiles?.includes("package.json")
+        && inputFiles.some(ref => [
+          "bun.lock",
+          "bun.lockb",
+          "package-lock.json",
+          "pnpm-lock.yaml",
+          "yarn.lock",
+        ].includes(ref));
+      if (
+        resolved?.status === "resolved"
+        && executable
+        && argvPrefix
+        && inputFiles
+        && identity
+      ) {
+        const high = resolved.confidence === "high"
+          && authoritativeSource
+          && lockBound;
+        return {
+          status: "resolved",
+          confidence: high ? "high" : "review_required",
+          source: String(resolved.source ?? "injected_resolver"),
+          packageManager,
+          executable,
+          argvPrefix,
+          inputFiles,
+          issueCodes: high ? [] : ["project_tool_resolution_not_authoritative"],
+          ...identity,
+        };
+      }
+      return {
+        status: "invalid",
+        confidence: "review_required",
+        source: "injected_resolver",
+        packageManager,
+        executable: null,
+        argvPrefix: [],
+        inputFiles: [],
+        version: null,
+        executableSha256: null,
+        launcherSha256: null,
+        issueCodes: ["project_tool_resolution_invalid"],
+      };
+    } catch {
+      return {
+        status: "invalid",
+        confidence: "review_required",
+        source: "injected_resolver",
+        packageManager,
+        executable: null,
+        argvPrefix: [],
+        inputFiles: [],
+        version: null,
+        executableSha256: null,
+        launcherSha256: null,
+        issueCodes: ["project_tool_resolution_failed"],
+      };
+    }
+  }
+
+  const installedManager = defaultProjectInstalledManager(root, manifest);
+  if (installedManager) return installedManager;
+  const projectNpm = defaultProjectNpm(root, manifest);
+  if (projectNpm) return projectNpm;
+  const executable = resolveRegularExecutable(packageManager);
+  return {
+    status: executable ? "resolved" : "unavailable",
+    confidence: "review_required",
+    source: executable ? "path_fallback" : "unavailable",
+    packageManager,
+    executable,
+    argvPrefix: [],
+    inputFiles: [],
+    version: null,
+    executableSha256: executable ? sha256(readFileSync(executable)) : null,
+    launcherSha256: null,
+    issueCodes: ["project_tool_resolution_not_authoritative"],
+  };
+}
+
 function command(id, script, executable) {
   return {
     id,
@@ -45,12 +400,20 @@ function command(id, script, executable) {
   };
 }
 
-function workspaceCommand(id, workspacePath, script, executable) {
+function workspaceCommand(
+  id,
+  workspacePath,
+  script,
+  executable,
+  useWorkspaceCwd = false,
+) {
   return {
     id,
-    cwd: ".",
+    cwd: useWorkspaceCwd ? workspacePath : ".",
     executable,
-    argv: ["run", "--workspace", workspacePath, script],
+    argv: useWorkspaceCwd
+      ? ["run", script]
+      : ["run", "--workspace", workspacePath, script],
   };
 }
 
@@ -155,7 +518,12 @@ function profileIdForWorkspace(workspacePath) {
   return `workspace-${workspacePath.replace(/[^A-Za-z0-9._-]+/g, "-")}`;
 }
 
-function workspaceProfiles(workspaces, npmExecutable) {
+function workspaceProfiles(
+  workspaces,
+  npmExecutable,
+  packageManager = "npm",
+  useWorkspaceCwd = false,
+) {
   return workspaces
     .map((workspace) => {
       const qualityScripts = workspace.scripts.filter((script) =>
@@ -170,10 +538,11 @@ function workspaceProfiles(workspaces, npmExecutable) {
         requiresProfileIds: [],
         commands: npmExecutable
           ? qualityScripts.map((script) => workspaceCommand(
-              `npm-${profileId}-${script}`,
+              `${packageManager}-${profileId}-${script}`,
               workspace.path,
               script,
               npmExecutable,
+              useWorkspaceCwd,
             ))
           : [],
       };
@@ -181,17 +550,32 @@ function workspaceProfiles(workspaces, npmExecutable) {
     .filter(Boolean);
 }
 
-function profileCandidates(root, manifest, npmExecutable, workspaces) {
+function profileCandidates(
+  root,
+  manifest,
+  npmExecutable,
+  workspaces,
+  packageManager = "npm",
+  useWorkspaceCwd = false,
+  includeLegacyDatabaseProfile = false,
+) {
   const scripts = new Set(detectedScripts(manifest));
   const candidates = [];
   if (
-    existsSync(path.join(root, "prisma"))
-    || [...scripts].some((script) => /^(db:|prisma)/.test(script))
+    includeLegacyDatabaseProfile
+    && (
+      existsSync(path.join(root, "prisma"))
+      || [...scripts].some((script) => /^(db:|prisma)/.test(script))
+    )
   ) {
     const commands = [...scripts]
       .filter((script) => /^(db:|prisma)/.test(script))
       .map((script) => npmExecutable
-        ? command(`npm-${script.replaceAll(":", "-")}`, script, npmExecutable)
+        ? command(
+            `${packageManager}-${script.replaceAll(":", "-")}`,
+            script,
+            npmExecutable,
+          )
         : null)
       .filter(Boolean);
     candidates.push({
@@ -209,7 +593,9 @@ function profileCandidates(root, manifest, npmExecutable, workspaces) {
   ) {
     const commands = ["build", "lint", "test", "typecheck"]
       .filter((script) => scripts.has(script))
-      .map((script) => npmExecutable ? command(`npm-${script}`, script, npmExecutable) : null)
+      .map((script) => npmExecutable
+        ? command(`${packageManager}-${script}`, script, npmExecutable)
+        : null)
       .filter(Boolean);
     candidates.push({
       id: "node-quality",
@@ -226,7 +612,7 @@ function profileCandidates(root, manifest, npmExecutable, workspaces) {
     || scripts.has("e2e")
   ) {
     const commands = scripts.has("e2e") && npmExecutable
-      ? [command("npm-e2e", "e2e", npmExecutable)]
+      ? [command(`${packageManager}-e2e`, "e2e", npmExecutable)]
       : [];
     candidates.push({
       id: "web-e2e",
@@ -237,7 +623,12 @@ function profileCandidates(root, manifest, npmExecutable, workspaces) {
       commands,
     });
   }
-  candidates.push(...workspaceProfiles(workspaces, npmExecutable));
+  candidates.push(...workspaceProfiles(
+    workspaces,
+    npmExecutable,
+    packageManager,
+    useWorkspaceCwd,
+  ));
   return candidates.sort((left, right) => left.id.localeCompare(right.id));
 }
 
@@ -246,7 +637,15 @@ export function detectProfiles({ workspaceRoot } = {}) {
   const manifest = readWorkspaceJsonBounded(root, "package.json");
   const npmExecutable = resolveRegularExecutable("npm");
   const discovered = discoverWorkspaces(root, manifest);
-  const candidates = profileCandidates(root, manifest, npmExecutable, discovered.workspaces);
+  const candidates = profileCandidates(
+    root,
+    manifest,
+    npmExecutable,
+    discovered.workspaces,
+    "npm",
+    false,
+    true,
+  );
   const primaryCandidates = candidates.filter((profile) => profile.role === "primary");
   const warnings = primaryCandidates.length > 1
     ? [`ambiguous_primary_profile:${primaryCandidates.map((profile) => profile.id).join(",")}`]
@@ -277,6 +676,435 @@ export function detectProfiles({ workspaceRoot } = {}) {
   };
 }
 
+function detectedInputManifest(root, workspaces, toolBinding) {
+  const refs = new Set([
+    "package.json",
+    ...[
+      "bun.lock",
+      "bun.lockb",
+      "package-lock.json",
+      "pnpm-lock.yaml",
+      "yarn.lock",
+    ].filter(ref => existsSync(path.join(root, ref))),
+    ...workspaces.map(workspace => `${workspace.path}/package.json`),
+    ...toolBinding.inputFiles,
+  ]);
+  return [...refs]
+    .sort()
+    .map((ref) => {
+      const absolute = boundedRegularFile(root, ref);
+      return {
+        path: ref,
+        sha256: sha256(readFileSync(absolute)),
+      };
+    });
+}
+
+function bindCommandsToProjectTool(profiles, toolBinding) {
+  return profiles.map(profile => ({
+    ...profile,
+    commands: profile.commands.map(entry => ({
+      ...entry,
+      executable: toolBinding.executable,
+      argv: [...toolBinding.argvPrefix, ...entry.argv],
+    })),
+  }));
+}
+
+function proposedProfileDocument(candidates, inputManifest) {
+  const actionable = candidates.filter(profile => profile.commands.length > 0);
+  const selectedPrimary = actionable.find(profile => profile.id === "node-quality")
+    ?? actionable[0]
+    ?? null;
+  const rootSurfacePaths = inputManifest
+    .map(entry => entry.path)
+    .filter(ref => !ref.includes("/"));
+  return {
+    schemaVersion: "OwlCodaRunKitProfilesV1",
+    profiles: candidates.map(profile => ({
+      ...profile,
+      paths: [...new Set([
+        ...profile.paths,
+        ...(profile.id === selectedPrimary?.id ? rootSurfacePaths : []),
+      ])].sort(),
+      primary: profile.id === selectedPrimary?.id,
+    })),
+  };
+}
+
+function profilesFileHash(root) {
+  const ref = path.join(root, ".owlcoda", "runkit", "profiles.json");
+  if (!existsSync(ref)) return null;
+  return sha256(readFileSync(boundedRegularFile(
+    root,
+    path.join(".owlcoda", "runkit", "profiles.json"),
+  )));
+}
+
+function exactRegularFileBytes(absolutePath, expectedBytes) {
+  try {
+    const stat = lstatSync(absolutePath);
+    return !stat.isSymbolicLink()
+      && stat.isFile()
+      && realpathSync(absolutePath) === absolutePath
+      && readFileSync(absolutePath, "utf8") === expectedBytes;
+  } catch {
+    return false;
+  }
+}
+
+function commitCreateOnlyStagedFile(stagedPath, finalPath, expectedBytes) {
+  if (!exactRegularFileBytes(stagedPath, expectedBytes)) {
+    throw new Error("profile_apply_staged_file_invalid");
+  }
+  try {
+    linkSync(stagedPath, finalPath);
+  } catch (error) {
+    if (
+      error?.code !== "EEXIST"
+      || !exactRegularFileBytes(finalPath, expectedBytes)
+    ) {
+      throw error;
+    }
+  }
+  rmSync(stagedPath, { force: true });
+}
+
+function recoverProfileApplyTransaction({
+  root,
+  transactionRoot,
+  profilesPath,
+  profilesBytes,
+  receiptAbsolutePath,
+  receiptBytes,
+  receipt,
+}) {
+  const transactionStat = lstatSync(transactionRoot);
+  if (
+    transactionStat.isSymbolicLink()
+    || !transactionStat.isDirectory()
+    || realpathSync(transactionRoot) !== transactionRoot
+    || !insideRoot(root, transactionRoot)
+  ) {
+    throw new Error("profile_apply_transaction_directory_untrusted");
+  }
+  const entries = readdirSync(transactionRoot).sort();
+  if (entries.some((entry) => !["profiles.json", "receipt.json"].includes(entry))) {
+    throw new Error("profile_apply_transaction_contents_untrusted");
+  }
+  const stagedProfiles = path.join(transactionRoot, "profiles.json");
+  const stagedReceipt = path.join(transactionRoot, "receipt.json");
+  const currentProfilesSha256 = profilesFileHash(root);
+  const receiptExists = existsSync(receiptAbsolutePath);
+  if (
+    currentProfilesSha256 === null
+    && !exactRegularFileBytes(stagedProfiles, profilesBytes)
+  ) {
+    throw new Error("profile_apply_transaction_staged_profile_mismatch");
+  }
+  if (
+    currentProfilesSha256 !== null
+    && currentProfilesSha256 !== receipt.appliedProfilesSha256
+  ) {
+    throw new Error("profile_apply_transaction_profile_mismatch");
+  }
+  if (
+    currentProfilesSha256 !== null
+    && existsSync(stagedProfiles)
+    && !exactRegularFileBytes(stagedProfiles, profilesBytes)
+  ) {
+    throw new Error("profile_apply_transaction_staged_profile_mismatch");
+  }
+  if (
+    receiptExists
+      ? !exactRegularFileBytes(receiptAbsolutePath, receiptBytes)
+      : !exactRegularFileBytes(stagedReceipt, receiptBytes)
+  ) {
+    throw new Error("profile_apply_transaction_receipt_mismatch");
+  }
+  let profilesCommittedByRecovery = false;
+  try {
+    if (currentProfilesSha256 === null) {
+      commitCreateOnlyStagedFile(stagedProfiles, profilesPath, profilesBytes);
+      profilesCommittedByRecovery = true;
+    } else {
+      rmSync(stagedProfiles, { force: true });
+    }
+    if (receiptExists) {
+      rmSync(stagedReceipt, { force: true });
+    } else {
+      commitCreateOnlyStagedFile(
+        stagedReceipt,
+        receiptAbsolutePath,
+        receiptBytes,
+      );
+    }
+  } catch (error) {
+    if (
+      profilesCommittedByRecovery
+      && profilesFileHash(root) === receipt.appliedProfilesSha256
+    ) {
+      try {
+        linkSync(profilesPath, stagedProfiles);
+      } catch (linkError) {
+        if (
+          linkError?.code !== "EEXIST"
+          || !exactRegularFileBytes(stagedProfiles, profilesBytes)
+        ) {
+          throw linkError;
+        }
+      }
+      rmSync(profilesPath);
+    }
+    throw error;
+  }
+  rmSync(transactionRoot, { recursive: true });
+  return receipt;
+}
+
+export function detectProfilesV2({
+  workspaceRoot,
+  projectToolResolver,
+} = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  const manifest = readWorkspaceJsonBounded(root, "package.json");
+  const discovered = discoverWorkspaces(root, manifest);
+  const toolBinding = resolveProjectTool(root, manifest, projectToolResolver);
+  const rawCandidates = profileCandidates(
+    root,
+    manifest,
+    toolBinding.executable,
+    discovered.workspaces,
+    toolBinding.packageManager,
+    true,
+  );
+  const candidates = bindCommandsToProjectTool(rawCandidates, toolBinding);
+  let inputManifest = [];
+  const issueCodes = [
+    ...toolBinding.issueCodes,
+    ...discovered.warnings,
+  ];
+  try {
+    inputManifest = detectedInputManifest(root, discovered.workspaces, toolBinding);
+  } catch (error) {
+    issueCodes.push(error instanceof Error ? error.message : String(error));
+  }
+  const proposedProfiles = proposedProfileDocument(candidates, inputManifest);
+  issueCodes.push(...validateProfileDocument(proposedProfiles));
+  const qualityIssues = [...new Set(issueCodes)].sort();
+  const confidence = qualityIssues.length === 0 && toolBinding.confidence === "high"
+    ? "high"
+    : "review_required";
+  const currentProfilesSha256 = profilesFileHash(root);
+  const applyStatus = currentProfilesSha256 !== null
+    ? "profiles_already_exists"
+    : confidence === "high"
+      ? "ready_to_apply"
+      : "review_required";
+  const body = {
+    schemaVersion: "OwlCodaRunKitProfileDetectionV2",
+    status: "profiles_detected",
+    dryRun: true,
+    writesPerformed: 0,
+    confidence,
+    applyStatus,
+    issueCodes: qualityIssues,
+    proposedProfiles,
+    candidates,
+    primaryProfileId: proposedProfiles.profiles.find(profile => profile.primary)?.id ?? null,
+    inputManifest,
+    toolBinding: {
+      status: toolBinding.status,
+      confidence: toolBinding.confidence,
+      source: toolBinding.source,
+      packageManager: toolBinding.packageManager,
+      executable: toolBinding.executable,
+      argvPrefix: [...toolBinding.argvPrefix],
+      version: toolBinding.version,
+      executableSha256: toolBinding.executableSha256,
+      launcherSha256: toolBinding.launcherSha256,
+    },
+    currentProfilesSha256,
+    detectedScripts: detectedScripts(manifest),
+    detectedWorkspaces: discovered.workspaces,
+    authorizationGranted: false,
+  };
+  return {
+    ...body,
+    detectionSha256: sha256(canonicalJson(body)),
+  };
+}
+
+function blockedApply(detection, issueCodes, currentProfilesSha256 = null) {
+  return {
+    schemaVersion: "OwlCodaRunKitProfilesApplyReceiptV1",
+    status: "profiles_apply_blocked",
+    writesPerformed: 0,
+    detectionSha256: detection?.detectionSha256 ?? null,
+    currentProfilesSha256,
+    issueCodes: [...new Set(issueCodes)].sort(),
+    authorizationGranted: false,
+  };
+}
+
+function verifyDetectionInputs(root, detection) {
+  const issues = [];
+  const { detectionSha256, ...body } = detection;
+  if (
+    detection.schemaVersion !== "OwlCodaRunKitProfileDetectionV2"
+    || detection.status !== "profiles_detected"
+    || !/^[a-f0-9]{64}$/.test(detectionSha256 ?? "")
+    || sha256(canonicalJson(body)) !== detectionSha256
+  ) {
+    issues.push("profile_detection_invalid");
+  }
+  if (detection.confidence !== "high" || detection.applyStatus !== "ready_to_apply") {
+    issues.push("profile_detection_not_ready_to_apply");
+  }
+  issues.push(...validateProfileDocument(detection.proposedProfiles));
+  const executable = regularExecutable(detection.toolBinding?.executable);
+  const launcher = regularExecutable(detection.toolBinding?.argvPrefix?.[0]);
+  if (
+    !executable
+    || !launcher
+    || sha256(readFileSync(executable)) !== detection.toolBinding.executableSha256
+    || sha256(readFileSync(launcher)) !== detection.toolBinding.launcherSha256
+  ) {
+    issues.push("profile_detection_tool_drift");
+  }
+  if (!Array.isArray(detection.inputManifest)) {
+    issues.push("profile_detection_invalid");
+  } else {
+    for (const entry of detection.inputManifest) {
+      try {
+        const actual = sha256(readFileSync(boundedRegularFile(root, entry.path)));
+        if (actual !== entry.sha256) issues.push(`profile_detection_input_drift:${entry.path}`);
+      } catch {
+        issues.push(`profile_detection_input_unavailable:${entry.path}`);
+      }
+    }
+  }
+  return [...new Set(issues)].sort();
+}
+
+export function applyDetectedProfilesV2({
+  workspaceRoot,
+  detection,
+} = {}) {
+  const root = resolveBoundedWorkspaceRoot(workspaceRoot);
+  let currentProfilesSha256;
+  try {
+    currentProfilesSha256 = profilesFileHash(root);
+  } catch {
+    return blockedApply(detection, ["profile_apply_directory_untrusted"]);
+  }
+  const issues = verifyDetectionInputs(root, detection ?? {});
+  if (issues.length > 0) return blockedApply(detection, issues);
+
+  const receiptPath = path.join(
+    ".owlcoda",
+    "runkit",
+    "profile-apply-receipts",
+    `${detection.detectionSha256}.json`,
+  );
+  let runtimeRoot;
+  let receiptRoot;
+  try {
+    runtimeRoot = ensureDirectoryChain(root, ".owlcoda/runkit");
+    receiptRoot = ensureDirectoryChain(
+      root,
+      ".owlcoda/runkit/profile-apply-receipts",
+    );
+  } catch {
+    return blockedApply(detection, ["profile_apply_directory_untrusted"]);
+  }
+  const profilesPath = path.join(runtimeRoot, "profiles.json");
+  const receiptAbsolutePath = path.join(
+    receiptRoot,
+    `${detection.detectionSha256}.json`,
+  );
+  const profilesBytes = `${JSON.stringify(detection.proposedProfiles, null, 2)}\n`;
+  const receipt = {
+    schemaVersion: "OwlCodaRunKitProfilesApplyReceiptV1",
+    status: "profiles_applied",
+    writesPerformed: 2,
+    detectionSha256: detection.detectionSha256,
+    beforeProfilesSha256: null,
+    appliedProfilesSha256: sha256(profilesBytes),
+    receiptPath,
+    issueCodes: [],
+    authorizationGranted: false,
+  };
+  const receiptBytes = `${JSON.stringify(receipt, null, 2)}\n`;
+  const transactionRoot = path.join(
+    runtimeRoot,
+    `.profile-apply-${detection.detectionSha256}.lock`,
+  );
+  if (existsSync(transactionRoot)) {
+    try {
+      return recoverProfileApplyTransaction({
+        root,
+        transactionRoot,
+        profilesPath,
+        profilesBytes,
+        receiptAbsolutePath,
+        receiptBytes,
+        receipt,
+      });
+    } catch {
+      return blockedApply(
+        detection,
+        ["profile_apply_transaction_recovery_invalid"],
+        currentProfilesSha256,
+      );
+    }
+  }
+  if (currentProfilesSha256 !== null) {
+    return blockedApply(detection, ["profiles_already_exists"], currentProfilesSha256);
+  }
+  try {
+    mkdirSync(transactionRoot);
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      return blockedApply(detection, ["profile_apply_transaction_active"]);
+    }
+    throw error;
+  }
+  let profilesCommitted = false;
+  try {
+    const current = profilesFileHash(root);
+    if (current !== null) {
+      return blockedApply(detection, ["profiles_already_exists"], current);
+    }
+    if (existsSync(receiptAbsolutePath)) {
+      return blockedApply(detection, ["profile_apply_receipt_already_exists"]);
+    }
+    const stagedProfiles = path.join(transactionRoot, "profiles.json");
+    const stagedReceipt = path.join(transactionRoot, "receipt.json");
+    writeFileSync(stagedProfiles, profilesBytes, { flag: "wx" });
+    writeFileSync(stagedReceipt, receiptBytes, { flag: "wx" });
+    commitCreateOnlyStagedFile(stagedProfiles, profilesPath, profilesBytes);
+    profilesCommitted = true;
+    commitCreateOnlyStagedFile(
+      stagedReceipt,
+      receiptAbsolutePath,
+      receiptBytes,
+    );
+    return receipt;
+  } catch {
+    if (
+      profilesCommitted
+      && existsSync(profilesPath)
+      && profilesFileHash(root) === receipt.appliedProfilesSha256
+    ) {
+      rmSync(profilesPath);
+    }
+    return blockedApply(detection, ["profile_apply_transaction_failed"]);
+  } finally {
+    rmSync(transactionRoot, { recursive: true, force: true });
+  }
+}
+
 function exactKeys(value, allowed) {
   return value
     && typeof value === "object"