@kal-elsam/kairo-runtime 0.4.2 → 0.5.0

package/src/global/integrations/sdd-persona.js

@@ -0,0 +1,71 @@
+import { SDD_MANAGED_AGENT_IDS, SDD_PERSONA_IDS } from "./sdd-destinations.js";
+import { SDD_FILE_OUTCOMES, SDD_PLAN_ACTIONS } from "./sdd-evidence.js";
+
+export const SDD_PERSONA_GATE = "sdd.personaAgentIds";
+export const SDD_PERSONA_HEALTH = Object.freeze({
+  OFF: "off", CONFIGURED: "configured", SYNC_REQUIRED: "sync_required", CONFLICT: "conflict"
+});
+
+export function normalizePersonaAgentIds(ids = []) {
+  const managed = new Set(SDD_MANAGED_AGENT_IDS);
+  return [...new Set((ids ?? []).filter((id) => managed.has(id)))].sort();
+}
+
+export function derivePersona(ids) {
+  return normalizePersonaAgentIds(ids).length ? "teaching" : "off";
+}
+
+export function samePersonaAgentIds(a, b) {
+  const left = normalizePersonaAgentIds(a), right = normalizePersonaAgentIds(b);
+  return left.length === right.length && left.every((id, i) => id === right[i]);
+}
+
+function result(before, after, admitted, rejected) {
+  return { before, after, admitted, rejected, persona: derivePersona(after), personaChanged: !samePersonaAgentIds(before, after) };
+}
+
+export function planPersonaTransition({
+  requestedPersona = "off", selectedAgentIds = [], currentPersonaAgentIds = [], actions = [],
+  preservePersona = false
+} = {}) {
+  if (!SDD_PERSONA_IDS.includes(requestedPersona)) {
+    throw new Error(`Persona "${requestedPersona}" is invalid. Use: ${SDD_PERSONA_IDS.join(", ")}.`);
+  }
+  const before = normalizePersonaAgentIds(currentPersonaAgentIds);
+  if (preservePersona) return result(before, before, [], []);
+  const selected = normalizePersonaAgentIds(selectedAgentIds);
+  if (requestedPersona === "off") {
+    return result(before, before.filter((id) => !selected.includes(id)), selected.filter((id) => before.includes(id)), []);
+  }
+  const admitted = selected.filter((id) => {
+    const mine = actions.filter((e) => e.agentIds?.includes(id));
+    return mine.length && mine.every((e) => e.action !== SDD_PLAN_ACTIONS.CONFLICT);
+  });
+  const kept = before.filter((id) => !selected.includes(id) || admitted.includes(id));
+  return result(before, normalizePersonaAgentIds([...kept, ...admitted]), admitted, selected.filter((id) => !admitted.includes(id)));
+}
+
+export function finalizePersonaTransition(planned, files, requestedPersona, { preservePersona = false } = {}) {
+  if (preservePersona || requestedPersona === "off" || !planned) return planned ?? result([], [], [], []);
+  const selected = normalizePersonaAgentIds([...planned.admitted, ...planned.rejected]);
+  const admitted = selected.filter((id) => {
+    const mine = files.filter((e) => e.agentIds?.includes(id));
+    return mine.length && mine.every((e) => e.outcome === SDD_FILE_OUTCOMES.APPLIED || e.outcome === SDD_FILE_OUTCOMES.NOOP);
+  });
+  const kept = planned.before.filter((id) => !selected.includes(id) || admitted.includes(id));
+  return result(planned.before, normalizePersonaAgentIds([...kept, ...admitted]), admitted, selected.filter((id) => !admitted.includes(id)));
+}
+
+export function classifyPersonaHealth({
+  personaAgentIds = [], assetPresent = false, gatePresent = false, incompleteAgentIds = []
+} = {}) {
+  if (!normalizePersonaAgentIds(personaAgentIds).length) {
+    return { status: SDD_PERSONA_HEALTH.OFF, personaActive: false, reason: "No consumers." };
+  }
+  if (!assetPresent) return { status: SDD_PERSONA_HEALTH.CONFLICT, personaActive: false, reason: "Asset missing." };
+  if (!gatePresent) return { status: SDD_PERSONA_HEALTH.SYNC_REQUIRED, personaActive: false, reason: "Gate missing." };
+  if (incompleteAgentIds.length) {
+    return { status: SDD_PERSONA_HEALTH.CONFLICT, personaActive: false, reason: `Incomplete: ${incompleteAgentIds.join(", ")}.` };
+  }
+  return { status: SDD_PERSONA_HEALTH.CONFIGURED, personaActive: true, reason: "Aligned." };
+}

package/src/global/integrations/sdd-plan.js

@@ -0,0 +1,87 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hashBuffer } from "../../hash.js";
+import { classifySddSkillFile, SDD_PLAN_ACTIONS } from "./sdd-evidence.js";
+import {
+  SDD_PERSONA_IDS,
+  SDD_SKILL_IDS,
+  groupSddSkillDestinations,
+  resolveCanonicalTeachingPersonaPath,
+  resolveSddAgentSelection
+} from "./sdd-destinations.js";
+import { planPersonaTransition } from "./sdd-persona.js";
+import { compareSkillPaths, loadCanonicalSddSkill } from "./sdd-skill-files.js";
+
+/**
+ * Deterministic dry-run planner for SDD skill materialization.
+ * Never writes, backs up, or mutates state.
+ */
+export async function planSddConfigure({
+  requestedAgentIds = null,
+  detectedAgentIds = [],
+  homeDir,
+  packageRoot,
+  persona = "off",
+  personaAgentIds = [],
+  trackedFiles = {},
+  preservePersona = false,
+  dryRun = true,
+  exists = existsSync,
+  readFileImpl = readFile
+} = {}) {
+  if (!homeDir) throw new Error("planSddConfigure requires homeDir.");
+  if (!packageRoot) throw new Error("planSddConfigure requires packageRoot.");
+  if (!SDD_PERSONA_IDS.includes(persona)) {
+    throw new Error(`Persona "${persona}" is invalid. Use: ${SDD_PERSONA_IDS.join(", ")}.`);
+  }
+
+  const agentIds = resolveSddAgentSelection({
+    requestedIds: requestedAgentIds,
+    detectedIds: detectedAgentIds
+  });
+  const destinationGroups = groupSddSkillDestinations(agentIds, homeDir);
+  const actions = [];
+
+  for (const skillId of SDD_SKILL_IDS) {
+    const { files, skillHash } = await loadCanonicalSddSkill(skillId, packageRoot);
+    for (const file of files) {
+      const canonicalHash = hashBuffer(file.bytes);
+      for (const group of destinationGroups) {
+        const destinationPath = join(group.root, skillId, ...file.relativePath.split("/"));
+        const trackedHash = trackedFiles[destinationPath] ?? null;
+        const fileExists = exists(destinationPath);
+        const diskHash = fileExists ? hashBuffer(await readFileImpl(destinationPath)) : null;
+        const classification = classifySddSkillFile({
+          exists: fileExists, canonicalHash, diskHash, trackedHash
+        });
+        actions.push({
+          skillId, relativePath: file.relativePath, destinationPath,
+          agentIds: [...group.agentIds], kind: group.kind,
+          action: classification.action, reason: classification.reason,
+          canonicalHash, skillHash, diskHash, trackedHash, writes: false, executes: false
+        });
+      }
+    }
+  }
+
+  actions.sort((a, b) => compareSkillPaths(a.skillId, b.skillId)
+    || compareSkillPaths(a.relativePath, b.relativePath)
+    || compareSkillPaths(a.destinationPath, b.destinationPath));
+
+  const summary = { create: 0, noop: 0, update: 0, conflict: 0 };
+  for (const action of actions) summary[action.action] += 1;
+  const personaTransition = planPersonaTransition({
+    requestedPersona: persona, selectedAgentIds: agentIds,
+    currentPersonaAgentIds: personaAgentIds, actions, preservePersona
+  });
+  return {
+    provider: "sdd-core", componentId: "sdd-core", dryRun: Boolean(dryRun),
+    executes: false, writes: false, requestedPersona: persona, preservePersona,
+    persona: personaTransition.persona,
+    personaPath: resolveCanonicalTeachingPersonaPath(packageRoot),
+    personaActive: personaTransition.after.length > 0, personaTransition, agentIds, actions,
+    conflicts: actions.filter((entry) => entry.action === SDD_PLAN_ACTIONS.CONFLICT),
+    summary, sessionRefreshRequired: personaTransition.personaChanged
+  };
+}

package/src/global/integrations/sdd-provider.js

@@ -0,0 +1,21 @@
+import { planSddConfigure } from "./sdd-plan.js";
+import { applySddConfigure } from "./sdd-apply.js";
+import { verifySddConfigure } from "./sdd-verify.js";
+import { rollbackSddReceipt } from "./sdd-rollback.js";
+
+export function createSddCoreProvider({
+  inspect = verifySddConfigure,
+  plan = planSddConfigure,
+  apply = applySddConfigure,
+  verify = verifySddConfigure,
+  rollback = rollbackSddReceipt
+} = {}) {
+  return {
+    id: "sdd-core",
+    async inspect(context = {}) { return inspect(context); },
+    async plan(context = {}) { return plan(context); },
+    async apply(context = {}) { return apply(context); },
+    async verify(context = {}) { return verify(context); },
+    async rollback(context = {}) { return rollback(context); }
+  };
+}

package/src/global/integrations/sdd-receipts.js

@@ -0,0 +1,44 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+
+export function sddIntegrationsDir(homeDir) {
+  return join(harnessHomePaths(homeDir).root, "integrations", "sdd-core");
+}
+
+export function assertSafeSddReceiptId(receiptId) {
+  if (typeof receiptId !== "string" || !/^sdd-[A-Za-z0-9-]+$/.test(receiptId)) {
+    throw new Error(`Invalid SDD receipt id "${receiptId}".`);
+  }
+}
+
+export function sddReceiptPath(homeDir, receiptId) {
+  assertSafeSddReceiptId(receiptId);
+  return join(sddIntegrationsDir(homeDir), `${receiptId}.json`);
+}
+
+/** Persist a secret-free receipt under ~/.harness/integrations/sdd-core/. */
+export async function saveSddReceipt(receipt, { homeDir } = {}) {
+  assertSafeSddReceiptId(receipt.id);
+  await mkdir(sddIntegrationsDir(homeDir), { recursive: true });
+  const path = sddReceiptPath(homeDir, receipt.id);
+  const sanitized = { ...receipt, persisted: true };
+  await writeFile(path, `${JSON.stringify(sanitized, null, 2)}\n`, "utf8");
+  return { path, receipt: sanitized };
+}
+
+export async function loadSddReceipt(receiptId, { homeDir } = {}) {
+  const path = sddReceiptPath(homeDir, receiptId);
+  if (!existsSync(path)) throw new Error(`SDD receipt not found: ${receiptId}`);
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+export async function listSddReceipts({ homeDir } = {}) {
+  const dir = sddIntegrationsDir(homeDir);
+  if (!existsSync(dir)) return [];
+  return (await readdir(dir))
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => name.slice(0, -5))
+    .sort();
+}

package/src/global/integrations/sdd-rollback.js

@@ -0,0 +1,269 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  assertExplicitApplyConsent,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "../apply-confirmation.js";
+import {
+  assertBackupPathContained,
+  assertSafePathChain,
+  deleteRegularFileIfHash,
+  hashRegularFile,
+  parentRealpath,
+  refuseSymlink,
+  replaceRegularFile,
+  resolveExpectedSddDestination,
+  snapshotRegularFile
+} from "./sdd-fs-guard.js";
+import { assertSafeSddReceiptId, loadSddReceipt, sddIntegrationsDir } from "./sdd-receipts.js";
+import { samePersonaAgentIds } from "./sdd-persona.js";
+
+export function sddReceiptBackupDir(homeDir, receiptId) {
+  assertSafeSddReceiptId(receiptId);
+  return join(sddIntegrationsDir(homeDir), "backups", receiptId);
+}
+
+export function sddBackupPathFor(homeDir, receiptId, destinationPath) {
+  return join(sddReceiptBackupDir(homeDir, receiptId), Buffer.from(destinationPath).toString("base64url"));
+}
+
+export async function backupSddDestination(destinationPath, {
+  homeDir, receiptId, managedRoot = null, snapshot = null, parentRealpath: knownParent = null
+} = {}) {
+  if (!existsSync(destinationPath) && !snapshot) return null;
+  if (managedRoot) {
+    const chain = await assertSafePathChain(destinationPath, managedRoot, homeDir);
+    if (!chain.ok) throw new Error(chain.reason);
+  }
+  const snap = snapshot ?? await snapshotRegularFile(destinationPath);
+  const backupDir = sddReceiptBackupDir(homeDir, receiptId);
+  await mkdir(backupDir, { recursive: true });
+  const backupPath = sddBackupPathFor(homeDir, receiptId, destinationPath);
+  const chain = await assertSafePathChain(backupPath, backupDir, homeDir);
+  if (!chain.ok) throw new Error(chain.reason);
+  const planted = await refuseSymlink(backupPath, "Backup");
+  if (planted) throw new Error(planted);
+  if (existsSync(backupPath)) throw new Error("Backup already exists; refusing overwrite.");
+  await replaceRegularFile(backupPath, snap.bytes, { createExclusive: true, managedRoot: backupDir, expectedParentRealpath: await parentRealpath(backupPath), trustedAnchor: homeDir });
+  return {
+    path: destinationPath, backupPath, beforeHash: snap.hash, ino: snap.ino,
+    parentRealpath: knownParent ?? await parentRealpath(destinationPath)
+  };
+}
+
+/** Bounded rollback: require complete evidence, then delete/restore only when afterHash matches. */
+export async function rollbackSddReceipt({
+  receiptId,
+  homeDir,
+  dryRun = false,
+  yes = false,
+  json = false,
+  interactive = null,
+  confirm = promptApplyConfirmation,
+  personaAgentIds = []
+} = {}) {
+  assertExplicitApplyConsent({
+    applying: !dryRun, dryRun, json, yes, interactive, command: "components rollback sdd-core"
+  });
+  const receipt = await loadSddReceipt(receiptId, { homeDir });
+
+  if (shouldPromptApplyConfirmation({ applying: true, dryRun, json, confirm: yes, interactive })) {
+    const accepted = await confirm({
+      command: `components rollback sdd-core --receipt ${receiptId}`,
+      question: `Rollback SDD receipt ${receiptId}? [Y/n]: `
+    });
+    if (!accepted) return { dryRun, cancelled: true, receiptId, actions: [] };
+  }
+
+  const evidence = await assessRollbackEvidence(receipt, { homeDir, receiptId, personaAgentIds });
+  if (!evidence.complete) {
+    return {
+      dryRun,
+      cancelled: false,
+      receiptId,
+      ok: false,
+      blocked: true,
+      reason: "Incomplete or unsafe rollback evidence; refusing all mutations.",
+      actions: evidence.actions
+    };
+  }
+
+  const actions = [];
+  const fileSteps = evidence.steps.filter((step) => step.action !== "persona");
+  const personaStep = evidence.steps.find((step) => step.action === "persona");
+  for (const step of fileSteps) {
+    if (step.action === "delete") actions.push(await executeDelete(step, { dryRun, homeDir }));
+    else if (step.action === "restore") actions.push(await executeRestore(step, { dryRun, homeDir }));
+  }
+  if (personaStep) {
+    const filesOk = actions.every((entry) => entry.ok !== false && (
+      entry.action === "delete" || entry.action === "restore"
+    ));
+    const ok = personaStep.noop || filesOk;
+    actions.push({
+      action: "persona", ok, noop: Boolean(personaStep.noop), dryRun: Boolean(dryRun),
+      before: personaStep.before, after: personaStep.after,
+      ...(ok ? {} : { reason: "Refusing persona rollback after incomplete file rollback." }),
+      ...(personaStep.noop ? { reason: "Already at before persona state." } : {})
+    });
+  }
+
+  return {
+    dryRun, cancelled: false, receiptId, blocked: false,
+    ok: actions.every((entry) => entry.ok !== false), actions
+  };
+}
+
+async function assessRollbackEvidence(receipt, { homeDir, receiptId, personaAgentIds }) {
+  const backups = new Map((receipt.backups ?? []).map((entry) => [entry.path, entry]));
+  const actions = [];
+  const steps = [];
+
+  for (const file of receipt.files ?? []) {
+    if (!file.applied) continue;
+    const expected = resolveExpectedSddDestination(file, homeDir);
+    if (!expected.ok) {
+      actions.push({ path: file.destinationPath, action: "block", ok: false, reason: expected.reason });
+      continue;
+    }
+    if (!file.afterHash) {
+      actions.push({ path: expected.path, action: "block", ok: false, reason: "Missing afterHash evidence." });
+      continue;
+    }
+    const chain = await assertSafePathChain(expected.path, expected.managedRoot, homeDir);
+    if (!chain.ok) {
+      actions.push({ path: expected.path, action: "block", ok: false, reason: chain.reason });
+      continue;
+    }
+    const backup = backups.get(file.destinationPath) ?? backups.get(expected.path);
+    const expectedParent = file.parentRealpath ?? backup?.parentRealpath ?? null;
+    if (!expectedParent) {
+      actions.push({
+        path: expected.path, action: "block", ok: false,
+        reason: "Missing parentRealpath evidence from apply."
+      });
+      continue;
+    }
+    if ((await parentRealpath(expected.path)) !== expectedParent) {
+      actions.push({
+        path: expected.path, action: "block", ok: false,
+        reason: "Parent realpath changed since apply; refusing."
+      });
+      continue;
+    }
+
+    if (file.action === "create") {
+      steps.push({
+        action: "delete", path: expected.path, afterHash: file.afterHash,
+        managedRoot: expected.managedRoot, expectedParentRealpath: expectedParent
+      });
+      continue;
+    }
+
+    if (file.action === "update") {
+      const backupCheck = await validateUpdateBackup(file, backup, {
+        homeDir, receiptId, expectedPath: expected.path
+      });
+      if (!backupCheck.ok) {
+        actions.push({ path: expected.path, action: "block", ok: false, reason: backupCheck.reason });
+        continue;
+      }
+      steps.push({
+        action: "restore",
+        path: expected.path,
+        afterHash: file.afterHash,
+        beforeHash: backupCheck.beforeHash,
+        backupPath: backupCheck.backupPath,
+        managedRoot: expected.managedRoot,
+        expectedParentRealpath: expectedParent
+      });
+    }
+  }
+
+  const transition = receipt.personaTransition;
+  if (transition?.personaChanged) {
+    if (samePersonaAgentIds(transition.before, personaAgentIds)) {
+      steps.push({ action: "persona", noop: true, before: transition.before, after: transition.after });
+    } else if (!samePersonaAgentIds(transition.after, personaAgentIds)) {
+      actions.push({
+        action: "persona", ok: false,
+        reason: "Persona state changed since apply; refusing persona rollback."
+      });
+    } else {
+      steps.push({ action: "persona", before: transition.before, after: transition.after });
+    }
+  }
+  return { complete: actions.length === 0, actions, steps };
+}
+
+async function validateUpdateBackup(file, backup, { homeDir, receiptId, expectedPath }) {
+  if (!backup?.backupPath) return { ok: false, reason: "Backup missing." };
+  const contained = assertBackupPathContained(backup.backupPath, sddReceiptBackupDir(homeDir, receiptId));
+  if (!contained.ok) return contained;
+  const expectedBackup = sddBackupPathFor(homeDir, receiptId, expectedPath);
+  if (contained.path !== expectedBackup) {
+    return { ok: false, reason: "Backup path does not match receipt destination encoding." };
+  }
+  const beforeHash = backup.beforeHash ?? file.beforeHash;
+  if (!beforeHash) return { ok: false, reason: "Missing beforeHash evidence for backup." };
+  if (!existsSync(contained.path)) return { ok: false, reason: "Backup missing." };
+  try {
+    const backupHash = await hashRegularFile(contained.path);
+    if (backupHash !== beforeHash) {
+      return { ok: false, reason: "Backup hash does not match beforeHash." };
+    }
+  } catch (error) {
+    return { ok: false, reason: error.message };
+  }
+  return { ok: true, backupPath: contained.path, beforeHash };
+}
+
+async function executeDelete(step, { dryRun, homeDir }) {
+  if (!existsSync(step.path)) {
+    return { path: step.path, action: "delete", ok: true, reason: "Already absent." };
+  }
+  if (dryRun) return { path: step.path, action: "delete", ok: true, dryRun: true };
+  try {
+    const result = await deleteRegularFileIfHash(step.path, step.afterHash, {
+      managedRoot: step.managedRoot, expectedParentRealpath: step.expectedParentRealpath, trustedAnchor: homeDir
+    });
+    if (result.skipped) return { path: step.path, action: "skip", ok: true, reason: result.reason };
+    if (!result.ok) return { path: step.path, action: "skip", ok: false, reason: result.reason };
+    return { path: step.path, action: "delete", ok: true };
+  } catch (error) {
+    return { path: step.path, action: "skip", ok: false, reason: error.message };
+  }
+}
+
+async function executeRestore(step, { dryRun, homeDir }) {
+  if (!existsSync(step.path)) {
+    return { path: step.path, action: "skip", ok: false, reason: "Updated destination missing." };
+  }
+  try {
+    const chain = await assertSafePathChain(step.path, step.managedRoot, homeDir);
+    if (!chain.ok) return { path: step.path, action: "skip", ok: false, reason: chain.reason };
+    if ((await parentRealpath(step.path)) !== step.expectedParentRealpath) {
+      return { path: step.path, action: "skip", ok: false, reason: "Parent realpath changed before restore; refusing." };
+    }
+    const destination = await snapshotRegularFile(step.path);
+    if (destination.hash !== step.afterHash) {
+      return { path: step.path, action: "skip", ok: true, reason: "File changed after apply; refusing restore." };
+    }
+    if (!existsSync(step.backupPath)) {
+      return { path: step.path, action: "skip", ok: false, reason: "Backup missing." };
+    }
+    const backup = await snapshotRegularFile(step.backupPath);
+    if (backup.hash !== step.beforeHash) {
+      return { path: step.path, action: "skip", ok: false, reason: "Backup hash does not match beforeHash." };
+    }
+    if (dryRun) {
+      return { path: step.path, action: "restore", ok: true, dryRun: true, backupPath: step.backupPath };
+    }
+    await replaceRegularFile(step.path, backup.bytes, { expectedIno: destination.ino, expectedHash: destination.hash, managedRoot: step.managedRoot, expectedParentRealpath: step.expectedParentRealpath, trustedAnchor: homeDir });
+    return { path: step.path, action: "restore", ok: true, backupPath: step.backupPath };
+  } catch (error) {
+    return { path: step.path, action: "skip", ok: false, reason: error.message };
+  }
+}

package/src/global/integrations/sdd-skill-files.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { isPathInside } from "../component-paths.js";
+import { resolveCanonicalSddSkillDir } from "./sdd-destinations.js";
+export function normalizeSkillRelativePath(p) {
+  return String(p ?? "").split(sep).join("/");
+}
+export function compareSkillPaths(left, right) {
+  const a = normalizeSkillRelativePath(left), b = normalizeSkillRelativePath(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function assertSafeRelative(root, absolutePath) {
+  const rel = normalizeSkillRelativePath(relative(root, absolutePath));
+  if (!rel || rel.startsWith("../") || rel.split("/").includes("..")
+    || (!isPathInside(root, absolutePath) && resolve(absolutePath) !== root)) {
+    throw new Error(`Skill path escapes skill root: ${rel || "."}`);
+  }
+  return rel;
+}
+function u32be(n) {
+  const buf = Buffer.allocUnsafe(4);
+  buf.writeUInt32BE(n >>> 0);
+  return buf;
+}
+export async function listSddSkillFiles(skillDir) {
+  const root = resolve(skillDir), rootStats = await lstat(root);
+  if (rootStats.isSymbolicLink()) throw new Error("Skill root is a symlink; refusing.");
+  if (!rootStats.isDirectory()) throw new Error("Skill root is not a directory; refusing.");
+  const files = [];
+  await walk(root, root, files);
+  return files.sort((a, b) => compareSkillPaths(a.relativePath, b.relativePath));
+}
+async function walk(root, dir, files) {
+  for (const name of (await readdir(dir)).sort()) {
+    const absolutePath = join(dir, name), relativePath = assertSafeRelative(root, absolutePath);
+    const stats = await lstat(absolutePath);
+    if (stats.isSymbolicLink()) throw new Error(`Symlink refused in skill: ${relativePath}`);
+    if (stats.isDirectory()) { await walk(root, absolutePath, files); continue; }
+    if (!stats.isFile()) throw new Error(`Non-regular file refused in skill: ${relativePath}`);
+    files.push({ relativePath, absolutePath });
+  }
+}
+export async function readSddSkillFiles(skillDir) {
+  return Promise.all((await listSddSkillFiles(skillDir)).map(async (e) => (
+    { ...e, bytes: await readFile(e.absolutePath) }
+  )));
+}
+export function hashSddSkillFiles(files) {
+  const hash = createHash("sha256");
+  for (const file of [...files].sort((a, b) => compareSkillPaths(a.relativePath, b.relativePath))) {
+    const path = Buffer.from(normalizeSkillRelativePath(file.relativePath), "utf8");
+    hash.update(u32be(path.length)).update(path);
+    hash.update(u32be(file.bytes.length)).update(file.bytes);
+  }
+  return hash.digest("hex");
+}
+export async function loadCanonicalSddSkill(skillId, packageRoot) {
+  const files = await readSddSkillFiles(resolveCanonicalSddSkillDir(skillId, packageRoot));
+  return { files, skillHash: hashSddSkillFiles(files) };
+}