@ikon85/agent-workflow-kit 0.34.4 → 0.34.6

package/src/lib/updateCandidate.mjs

@@ -1,8 +1,11 @@
-import { execFile } from 'node:child_process';
-import { access, cp, lstat, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import {
+  access, lstat, mkdtemp, open, readFile, realpath, rm, stat,
+} from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, relative } from 'node:path';
-import { promisify } from 'node:util';
+import {
+  isAbsolute, join, normalize, posix, relative, sep,
+} from 'node:path';
 import { writeAtomic } from './atomicWrite.mjs';
 import { validateConsumerFile } from './consumerPath.mjs';
 import { sha256File } from './hash.mjs';
@@ -10,38 +13,195 @@ import { stubSentinel } from './sentinel.mjs';
 import { STUB_TARGETS } from './bundle.mjs';
 import {
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
-  indexByPath, readManifest, writeManifest,
+  filesForInstallRole, indexByPath, readManifest, writeManifest,
 } from './manifest.mjs';
 import { checkSkill, evaluateCapability, inspectProdSections } from '../../scripts/readiness.mjs';
 
-const run = promisify(execFile);
 const exists = (path) => access(path).then(() => true, () => false);
 const pathEntryExists = (path) => lstat(path).then(() => true, (error) => {
   if (error.code === 'ENOENT') return false;
   throw error;
 });
 const MIGRATABLE_INSTRUCTION_PATHS = new Set(['CLAUDE.md', 'AGENTS.md']);
+const INTEGRATION_INPUTS = [
+  'package.json', '.claude/settings.json', '.claude/settings.local.json',
+];
+const FORBIDDEN_CANDIDATE_ROOTS = new Set(['.git', '.worktrees', 'node_modules']);
+const PLATFORM_PATH_SEMANTICS = { isAbsolute, normalize, sep };
 
-/** Copy a verification candidate without duplicating git metadata or dependencies. */
-export async function stageConsumer(consumerRoot) {
+/** Materialize only manifest state and declared Consumer inputs for verification. */
+export async function materializeUpdateCandidate({
+  consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
+  afterInputValidation = async () => {},
+}) {
   const candidateRoot = await mkdtemp(join(tmpdir(), 'agent-workflow-kit-stage-'));
-  const nodeModules = join(consumerRoot, 'node_modules');
-  await cp(consumerRoot, candidateRoot, {
-    recursive: true,
-    filter: (source) => {
-      const rel = relative(consumerRoot, source);
-      return rel !== '.git' && !rel.startsWith('.git/') &&
-        rel !== 'node_modules' && !rel.startsWith('node_modules/');
-    },
-  });
-  if (await exists(nodeModules)) await symlink(nodeModules, join(candidateRoot, 'node_modules'), 'dir');
-  return candidateRoot;
+  try {
+    const paths = candidateInputPaths({
+      pkg, manifests: [priorReadinessManifest, nextReadinessManifest],
+    });
+    for (const path of paths) {
+      await copyCandidateInput(consumerRoot, candidateRoot, path, afterInputValidation);
+    }
+    await copyDeclaredRunbooks({
+      consumerRoot, candidateRoot, manifests: [priorReadinessManifest, nextReadinessManifest],
+      afterInputValidation,
+    });
+    return candidateRoot;
+  } catch (error) {
+    await rm(candidateRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function candidateInputPaths({ pkg, manifests }) {
+  const candidates = [
+    CONSUMER_MANIFEST_NAME,
+    ...INTEGRATION_INPUTS,
+    ...filesForInstallRole(pkg).map(({ path }) => path),
+  ];
+  for (const manifest of manifests) {
+    for (const capability of Object.values(manifest?.readiness?.capabilities ?? {})) {
+      candidates.push(...(capability.evidence?.paths ?? []));
+    }
+  }
+  const paths = new Set(candidates.filter((path) => !isForbiddenCandidatePath(path)));
+  return [...paths].sort();
+}
+
+async function copyDeclaredRunbooks({
+  consumerRoot, candidateRoot, manifests, afterInputValidation,
+}) {
+  const runbooks = await declaredCandidateRunbookPaths({ candidateRoot, manifests });
+  for (const path of runbooks) {
+    await copyCandidateInput(consumerRoot, candidateRoot, path, afterInputValidation);
+  }
+}
+
+export async function declaredCandidateRunbookPaths({ candidateRoot, manifests }) {
+  const runbooks = new Set();
+  for (const manifest of manifests) {
+    for (const capability of Object.values(manifest?.readiness?.capabilities ?? {})) {
+      const evidence = capability.evidence;
+      if (evidence?.type !== 'runbook-reference') continue;
+      const declaration = await readCandidateText(candidateRoot, evidence.paths?.[0]);
+      for (const match of declaration?.matchAll(/`([^`\n]+\.md)`/g) ?? []) {
+        if (!match[1].includes('template')) runbooks.add(match[1]);
+      }
+    }
+  }
+  return [...runbooks].sort();
+}
+
+async function readCandidateText(candidateRoot, path) {
+  if (!path) return null;
+  try {
+    return await readFile(join(candidateRoot, path), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function copyCandidateInput(consumerRoot, candidateRoot, path, afterInputValidation) {
+  if (isForbiddenCandidatePath(path)) return;
+  const consumerPath = validateCandidateManifestPath(path);
+  let source;
+  try {
+    source = await validateConsumerFile(consumerRoot, consumerPath);
+  } catch (error) {
+    if (!error.message.startsWith('unsafe consumer path (not a regular file):')) throw error;
+    if (!await pathEntryExists(join(consumerRoot, path))) return;
+    throw error;
+  }
+  const root = await realpath(consumerRoot);
+  const resolved = await realpath(source);
+  assertResolvedConsumerPath(root, resolved, path);
+  const validated = await stat(resolved, { bigint: true });
+  const pathname = await lstat(source, { bigint: true });
+  if (!sameFile(validated, pathname)) {
+    throw new Error(`consumer input changed while staging: ${path}`);
+  }
+  await afterInputValidation(path);
+
+  let handle;
+  try {
+    handle = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isFile() || !sameFile(validated, opened)) {
+      throw new Error(`consumer input changed while staging: ${path}`);
+    }
+    const bytes = await handle.readFile();
+    const finished = await handle.stat({ bigint: true });
+    if (!sameFileSnapshot(opened, finished)) {
+      throw new Error(`consumer input changed while staging: ${path}`);
+    }
+    const resolvedAfter = await realpath(source);
+    assertResolvedConsumerPath(root, resolvedAfter, path);
+    const current = await stat(resolvedAfter, { bigint: true });
+    if (!sameFile(opened, current)) {
+      throw new Error(`consumer input changed while staging: ${path}`);
+    }
+    await writeAtomic(join(candidateRoot, path), bytes, Number(opened.mode));
+  } catch (error) {
+    if (error.code === 'ELOOP') {
+      throw new Error(`unsafe consumer path (not a regular file): ${path}`, { cause: error });
+    }
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+
+/**
+ * Accept the package manifest's canonical slash-separated path and translate it
+ * only after platform-independent lexical validation.
+ */
+export function validateCandidateManifestPath(path, pathSemantics = PLATFORM_PATH_SEMANTICS) {
+  if (typeof path !== 'string' || !path || path === '.' || path.includes('\\')
+      || path.split('/').includes('..')
+      || posix.isAbsolute(path) || posix.normalize(path) !== path) {
+    throw new Error(`unsafe candidate manifest path: ${path}`);
+  }
+  const platformPath = path.split('/').join(pathSemantics.sep);
+  if (pathSemantics.isAbsolute(platformPath)
+      || pathSemantics.normalize(platformPath) !== platformPath) {
+    throw new Error(`unsafe candidate manifest path: ${path}`);
+  }
+  return platformPath;
+}
+
+function isForbiddenCandidatePath(path) {
+  if (typeof path !== 'string') return false;
+  const [root] = path.split(/[\\/]/);
+  return FORBIDDEN_CANDIDATE_ROOTS.has(root);
+}
+
+function assertResolvedConsumerPath(root, resolved, path) {
+  const fromRoot = relative(root, resolved);
+  if (!fromRoot || fromRoot === '..' || fromRoot.startsWith(`..${pathSeparator()}`)
+      || isAbsolute(fromRoot)) {
+    throw new Error(`unsafe consumer path (resolved outside root): ${path}`);
+  }
+}
+
+function pathSeparator() {
+  return process.platform === 'win32' ? '\\' : '/';
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function sameFileSnapshot(left, right) {
+  return sameFile(left, right) && left.size === right.size &&
+    left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
 
 /** Activate only verified kit-owned deltas, rolling every touched path back on failure. */
 export async function activateCandidate({
   candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
-  afterGenerated = async () => {},
+  afterSnapshot = async () => {}, afterGenerated = async () => {},
+  beforeTargetRevalidation = async () => {},
 }) {
   const changed = [...preview.added, ...preview.updated];
   const generated = preview.generated ?? [];
@@ -50,10 +210,6 @@ export async function activateCandidate({
     ...changed, ...generated, ...migrations.map(({ path }) => path),
     ...preview.deleted, CONSUMER_MANIFEST_NAME,
   ];
-  const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
-  if (!currentManifest.equals(consumerManifestBefore)) {
-    throw new Error('consumer manifest changed during verification');
-  }
   const pkgIdx = indexByPath(pkg, 'files');
   for (const path of changed) {
     if (await sha256File(join(candidateRoot, path)) !== pkgIdx.get(path)?.sha256) {
@@ -72,28 +228,77 @@ export async function activateCandidate({
       throw new Error(`migrated candidate hash mismatch: ${migration.path}`);
     }
   }
+  const manifestBeforeSnapshot = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!manifestBeforeSnapshot.equals(consumerManifestBefore)) {
+    throw new Error('consumer manifest changed during verification');
+  }
   await assertConsumerStillMatchesPreview(consumerRoot, preview);
   const rollback = new Map();
-  for (const path of touched) rollback.set(path, await snapshot(join(consumerRoot, path)));
+  for (const path of touched) {
+    rollback.set(path, await snapshot(join(consumerRoot, path), path));
+  }
+  await afterSnapshot();
+  const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!currentManifest.equals(consumerManifestBefore)) {
+    throw new Error('consumer manifest changed during verification');
+  }
+  await assertConsumerStillMatchesPreview(consumerRoot, preview);
+  const applied = [];
+  const applyTarget = async (path, action) => {
+    await beforeTargetRevalidation(path);
+    await assertTargetStillMatchesSnapshot(
+      join(consumerRoot, path), rollback.get(path), path,
+    );
+    // Optimistic revalidation cannot remove the filesystem check-to-rename
+    // micro-window; it does keep every later destination behind a fresh check.
+    await action();
+    const record = { path, snapshot: null, captured: false };
+    applied.push(record);
+    record.snapshot = await snapshot(join(consumerRoot, path), path);
+    record.captured = true;
+  };
   try {
     for (const path of changed) {
-      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)), pkgIdx.get(path)?.mode);
+      const bytes = await readFile(join(candidateRoot, path));
+      await applyTarget(path, () => writeAtomic(
+        join(consumerRoot, path), bytes, pkgIdx.get(path)?.mode,
+      ));
     }
     for (const path of generated) {
-      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
+      const bytes = await readFile(join(candidateRoot, path));
+      await applyTarget(path, () => writeAtomic(join(consumerRoot, path), bytes));
     }
     for (const { path } of migrations) {
-      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
+      const bytes = await readFile(join(candidateRoot, path));
+      await applyTarget(path, () => writeAtomic(join(consumerRoot, path), bytes));
     }
     await afterGenerated();
-    for (const path of preview.deleted) await rm(join(consumerRoot, path), { force: true });
-    await writeAtomic(
-      join(consumerRoot, CONSUMER_MANIFEST_NAME),
-      await readFile(join(candidateRoot, CONSUMER_MANIFEST_NAME)),
-    );
+    for (const path of preview.deleted) {
+      await applyTarget(path, () => rm(join(consumerRoot, path), { force: true }));
+    }
+    const manifestBytes = await readFile(join(candidateRoot, CONSUMER_MANIFEST_NAME));
+    await applyTarget(CONSUMER_MANIFEST_NAME, () => writeAtomic(
+      join(consumerRoot, CONSUMER_MANIFEST_NAME), manifestBytes,
+    ));
   } catch (error) {
-    for (const path of touched.reverse()) await restore(join(consumerRoot, path), rollback.get(path));
-    error.consumerState = 'rolled-back';
+    const rollbackConflicts = [];
+    for (const record of applied.reverse()) {
+      const target = join(consumerRoot, record.path);
+      if (!record.captured
+          || !await targetStillMatchesSnapshot(target, record.snapshot, record.path)) {
+        rollbackConflicts.push(record.path);
+        continue;
+      }
+      await restore(target, rollback.get(record.path));
+    }
+    if (rollbackConflicts.length) {
+      rollbackConflicts.sort();
+      error.message = `${error.message}; rollback preserved concurrent edits: ` +
+        rollbackConflicts.join(', ');
+    }
+    error.consumerState = rollbackConflicts.length
+      ? 'rollback-conflicted'
+      : (applied.length ? 'rolled-back' : 'unchanged');
     throw error;
   }
 }
@@ -278,26 +483,49 @@ export async function readReadinessManifest(root) {
   return readManifest(join(root, READINESS_MANIFEST_PATH));
 }
 
-async function snapshot(path) {
-  if (!await exists(path)) return null;
-  const info = await stat(path);
-  return { bytes: await readFile(path), mode: info.mode };
+async function snapshot(path, displayPath = path) {
+  let before;
+  try {
+    before = await lstat(path, { bigint: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!before.isFile()) {
+    throw new Error(`unsafe consumer activation path: ${displayPath}`);
+  }
+  const bytes = await readFile(path);
+  const after = await lstat(path, { bigint: true });
+  if (!sameFileSnapshot(before, after)) {
+    throw new Error(`consumer changed during activation: ${displayPath}`);
+  }
+  return { bytes, mode: Number(before.mode), identity: before };
 }
 
-async function restore(path, saved) {
-  if (!saved) return rm(path, { force: true });
-  await writeAtomic(path, saved.bytes, saved.mode);
+async function assertTargetStillMatchesSnapshot(path, expected, displayPath) {
+  if (!await targetStillMatchesSnapshot(path, expected, displayPath)) {
+    throw new Error(`consumer changed during activation: ${displayPath}`);
+  }
 }
 
-/** Default candidate gate: run the consumer's existing npm test command. */
-export async function verifyCandidate(candidateRoot) {
-  let pkg;
+async function targetStillMatchesSnapshot(path, expected, displayPath) {
+  let current;
   try {
-    pkg = JSON.parse(await readFile(join(candidateRoot, 'package.json'), 'utf8'));
+    current = await snapshot(path, displayPath);
   } catch (error) {
-    if (error.code === 'ENOENT') throw new Error('candidate has no package.json test command');
-    throw error;
+    return false;
   }
-  if (!pkg.scripts?.test) throw new Error('candidate has no package.json test command');
-  await run('npm', ['test'], { cwd: candidateRoot });
+  return sameActivationSnapshot(expected, current);
+}
+
+function sameActivationSnapshot(expected, current) {
+  if (!expected || !current) return expected === current;
+  return expected.mode === current.mode
+    && expected.bytes.equals(current.bytes)
+    && sameFileSnapshot(expected.identity, current.identity);
+}
+
+async function restore(path, saved) {
+  if (!saved) return rm(path, { force: true });
+  await writeAtomic(path, saved.bytes, saved.mode);
 }

package/src/lib/verifyUpdateCandidate.mjs

@@ -0,0 +1,220 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { sha256File } from './hash.mjs';
+import {
+  CONSUMER_INSTALL_ROLE, CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, KIT_ORIGIN,
+  emptyConsumerManifest, filesForInstallRole,
+} from './manifest.mjs';
+import { validateCandidateManifestPath } from './updateCandidate.mjs';
+import {
+  verifyCandidateMembership, verifyChangedSyntax,
+} from './verifyUpdateCandidateArtifacts.mjs';
+import { verifyCandidateProtocol } from './verifyUpdateCandidateProtocol.mjs';
+import {
+  verifyDeletionState, verifyDerivedArtifacts, verifyTransactionPreview,
+} from './verifyUpdateCandidateTransaction.mjs';
+
+const HASH = /^[a-f0-9]{64}$/;
+const PACKAGE_KINDS = new Set(['skill', 'hook', 'doc', 'template', 'script']);
+
+/**
+ * Verify the Kit-owned staged end state without executing Consumer behavior.
+ *
+ * The trusted package manifest and transaction preview are supplied by the
+ * updater; candidate-owned metadata never establishes its own authority.
+ */
+export async function verifyUpdateCandidate(candidateRoot, context) {
+  await verifyCandidateMetadata(candidateRoot, context);
+  await verifyChangedSyntax(candidateRoot, context.preview);
+}
+
+export async function verifyCandidateMetadata(candidateRoot, context) {
+  if (!candidateRoot || !context?.pkg) {
+    throw new Error('candidate invariant transaction: trusted package manifest is required');
+  }
+  const { installable, installed, ledger } = await verifyCandidateSchema(candidateRoot, context);
+  if (!Array.isArray(context.priorConsumerManifest?.installed)) {
+    throw new Error('candidate invariant ownership: trusted prior Consumer ledger is required');
+  }
+  verifyLedgerMetadata(ledger, context);
+  const priorInstalled = uniqueEntries(context.priorConsumerManifest.installed, 'prior ledger');
+  verifyTransactionPreview(context.preview, installable, installed);
+  verifyDeletionState(installed, context.pkg, installable, context.preview);
+  await verifyCandidateMembership(candidateRoot, context);
+  for (const entry of installable) {
+    const tracked = installed.get(entry.path);
+    if (!tracked) {
+      throw new Error(`candidate invariant ownership: untracked package path ${entry.path}`);
+    }
+    validateInstalledEntry(tracked, entry, expectedOrigin(entry.path, priorInstalled, context.preview));
+    let state;
+    try {
+      state = await lstat(join(candidateRoot, entry.path));
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`candidate invariant artifact: missing ${entry.path}`);
+      }
+      throw error;
+    }
+    if (!state.isFile()) {
+      throw new Error(`candidate invariant artifact: not a regular file ${entry.path}`);
+    }
+    if (tracked.origin === KIT_ORIGIN && (state.mode & 0o777) !== entry.mode) {
+      throw new Error(`candidate invariant artifact: mode mismatch ${entry.path}`);
+    }
+    const expectedHash = tracked.origin === CONSUMER_ORIGIN
+      ? tracked.installedSha256 : entry.sha256;
+    if (await sha256File(join(candidateRoot, entry.path)) !== expectedHash) {
+      throw new Error(`candidate invariant artifact: hash mismatch ${entry.path}`);
+    }
+  }
+  await verifyDerivedArtifacts(candidateRoot, installed, context.preview);
+}
+
+export async function verifyCandidateSchema(candidateRoot, context) {
+  if (!candidateRoot || !context?.pkg) {
+    throw new Error('candidate invariant transaction: trusted package manifest is required');
+  }
+  const installable = packageArtifacts(context.pkg);
+  const ledger = await candidateLedger(candidateRoot, context);
+  const installed = uniqueEntries(ledger.installed, 'ledger');
+  await verifyCandidateProtocol(candidateRoot, context.pkg, installed);
+  return { installable, installed, ledger };
+}
+
+export { verifyUpdateCandidate as verifyCandidate };
+
+function packageArtifacts(pkg) {
+  if (typeof pkg.kitVersion !== 'string' || !pkg.kitVersion) {
+    throw new Error('candidate invariant manifest: package kitVersion is required');
+  }
+  if (!Array.isArray(pkg.files)) {
+    throw new Error('candidate invariant manifest: package files must be an array');
+  }
+  const seen = new Set();
+  for (const entry of pkg.files) {
+    if (!entry || typeof entry.path !== 'string') {
+      throw new Error('candidate invariant manifest: package entry path is required');
+    }
+    try {
+      validateCandidateManifestPath(entry.path);
+    } catch {
+      throw new Error(`candidate invariant manifest: unsafe path ${entry.path}`);
+    }
+    if (seen.has(entry.path)) {
+      throw new Error(`candidate invariant manifest: duplicate path ${entry.path}`);
+    }
+    if (!HASH.test(entry.sha256 ?? '')) {
+      throw new Error(`candidate invariant manifest: invalid hash ${entry.path}`);
+    }
+    if (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777) {
+      throw new Error(`candidate invariant manifest: invalid mode ${entry.path}`);
+    }
+    if (!PACKAGE_KINDS.has(entry.kind)) {
+      throw new Error(`candidate invariant manifest: invalid kind ${entry.path}`);
+    }
+    if ((entry.origin ?? KIT_ORIGIN) !== KIT_ORIGIN) {
+      throw new Error(`candidate invariant manifest: invalid origin ${entry.path}`);
+    }
+    if (![CONSUMER_INSTALL_ROLE, 'maintainer'].includes(
+      entry.installRole ?? CONSUMER_INSTALL_ROLE,
+    )) {
+      throw new Error(`candidate invariant manifest: invalid role ${entry.path}`);
+    }
+    seen.add(entry.path);
+  }
+  return filesForInstallRole(pkg);
+}
+
+async function candidateLedger(candidateRoot, context) {
+  const { pkg, nextReadinessManifest } = context;
+  let ledger;
+  try {
+    ledger = JSON.parse(await readFile(join(candidateRoot, CONSUMER_MANIFEST_NAME), 'utf8'));
+  } catch {
+    throw new Error('candidate invariant schema: Consumer ledger is missing or invalid JSON');
+  }
+  if (!ledger || ledger.kitVersion !== pkg.kitVersion
+      || ledger.installRole !== CONSUMER_INSTALL_ROLE
+      || !Array.isArray(ledger.installed)
+      || !Number.isInteger(ledger.readinessContractVersion)
+      || !isRecord(ledger.readinessDecisions)
+      || Object.values(ledger.readinessDecisions).some(
+        (value) => !['pending', 'not-applicable'].includes(value),
+      )) {
+    throw new Error('candidate invariant schema: Consumer ledger identity is invalid');
+  }
+  const readiness = nextReadinessManifest?.readiness;
+  if (readiness && (ledger.readinessContractVersion !== readiness.contractVersion
+      || Object.entries(ledger.readinessDecisions).some(([name, value]) => (
+        !readiness.capabilities?.[name]
+        || (value === 'not-applicable' && !readiness.capabilities[name].allowNotApplicable)
+      )))) {
+    throw new Error('candidate invariant schema: Consumer ledger readiness references are invalid');
+  }
+  return ledger;
+}
+
+function uniqueEntries(entries, source) {
+  const indexed = new Map();
+  for (const entry of entries) {
+    if (!entry || typeof entry.path !== 'string') {
+      throw new Error(`candidate invariant schema: ${source} entry path is required`);
+    }
+    try {
+      validateCandidateManifestPath(entry.path);
+    } catch {
+      throw new Error(`candidate invariant schema: unsafe ${source} path ${entry.path}`);
+    }
+    if (indexed.has(entry.path)) {
+      throw new Error(`candidate invariant schema: duplicate ${source} path ${entry.path}`);
+    }
+    indexed.set(entry.path, entry);
+  }
+  return indexed;
+}
+
+function validateInstalledEntry(tracked, desired, origin) {
+  if (tracked.origin !== origin
+      || (tracked.installRole ?? CONSUMER_INSTALL_ROLE) !== CONSUMER_INSTALL_ROLE
+      || !HASH.test(tracked.installedSha256 ?? '')) {
+    throw new Error(`candidate invariant ownership: invalid ledger entry ${tracked.path}`);
+  }
+  for (const key of ['kind', 'ownerSkill', 'surface']) {
+    if ((tracked[key] ?? null) !== (desired[key] ?? null)) {
+      throw new Error(`candidate invariant ownership: ${key} mismatch ${tracked.path}`);
+    }
+  }
+  if (tracked.origin === KIT_ORIGIN && tracked.installedSha256 !== desired.sha256) {
+    throw new Error(`candidate invariant ownership: Kit hash identity mismatch ${tracked.path}`);
+  }
+}
+
+function verifyLedgerMetadata(ledger, context) {
+  const expected = emptyConsumerManifest(
+    context.pkg.kitVersion,
+    context.priorConsumerManifest,
+    context.nextReadinessManifest?.readiness ?? null,
+  );
+  const { installed: _actualInstalled, ...actualMetadata } = ledger;
+  const { installed: _expectedInstalled, ...expectedMetadata } = expected;
+  if (!isDeepStrictEqual(actualMetadata, expectedMetadata)) {
+    throw new Error(
+      'candidate invariant schema: Consumer ledger metadata differs from trusted prior state',
+    );
+  }
+}
+
+function expectedOrigin(path, priorInstalled, preview) {
+  const keptOwned = (preview.collisionResolutions ?? []).some(
+    (resolution) => resolution.path === path && resolution.outcome === 'keep-as-owned',
+  );
+  return keptOwned || (priorInstalled.get(path)?.origin ?? KIT_ORIGIN) === CONSUMER_ORIGIN
+    ? CONSUMER_ORIGIN
+    : KIT_ORIGIN;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}