@ikon85/agent-workflow-kit 0.34.4 → 0.34.5

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);
+}

package/src/lib/verifyUpdateCandidateArtifacts.mjs

@@ -0,0 +1,78 @@
+import { execFile } from 'node:child_process';
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import {
+  candidateInputPaths, declaredCandidateRunbookPaths, validateCandidateManifestPath,
+} from './updateCandidate.mjs';
+
+const run = promisify(execFile);
+
+export async function verifyCandidateMembership(candidateRoot, context) {
+  const manifests = [
+    context.priorReadinessManifest, context.nextReadinessManifest,
+  ];
+  const allowed = new Set(candidateInputPaths({ pkg: context.pkg, manifests }));
+  for (const path of await declaredCandidateRunbookPaths({ candidateRoot, manifests })) {
+    allowed.add(path);
+  }
+  for (const path of context.preview?.generated ?? []) allowed.add(path);
+  for (const { path } of context.preview?.migrations ?? []) allowed.add(path);
+  for (const path of await regularCandidateFiles(candidateRoot)) {
+    if (!allowed.has(path)) {
+      throw new Error(`candidate invariant artifact: extra ${path}`);
+    }
+  }
+}
+
+export async function verifyChangedSyntax(candidateRoot, preview) {
+  const changed = new Set([
+    ...(preview?.added ?? []),
+    ...(preview?.updated ?? []),
+    ...(preview?.generated ?? []),
+    ...(preview?.migrations ?? []).map(({ path }) => path),
+  ]);
+  for (const path of [...changed].sort()) {
+    const absolute = join(candidateRoot, path);
+    let command;
+    if (/\.(?:mjs|cjs|js)$/.test(path)) {
+      command = [process.execPath, ['--check', absolute], 'Node'];
+    } else if (path.endsWith('.py')) {
+      command = [
+        'python3',
+        [
+          '-c',
+          'import ast,pathlib,sys; ast.parse(pathlib.Path(sys.argv[1]).read_bytes())',
+          absolute,
+        ],
+        'Python',
+      ];
+    } else if (path.endsWith('.sh')) {
+      command = ['bash', ['-n', absolute], 'shell'];
+    } else {
+      continue;
+    }
+    try {
+      await run(command[0], command[1]);
+    } catch {
+      throw new Error(`candidate invariant syntax: ${command[2]} parse failed ${path}`);
+    }
+  }
+}
+
+async function regularCandidateFiles(root, relative = '') {
+  const files = [];
+  for (const entry of await readdir(join(root, relative), { withFileTypes: true })) {
+    const path = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...await regularCandidateFiles(root, path));
+      continue;
+    }
+    const state = await lstat(join(root, path));
+    if (!state.isFile()) {
+      throw new Error(`candidate invariant artifact: not a regular file ${path}`);
+    }
+    files.push(path);
+  }
+  return files;
+}

package/src/lib/verifyUpdateCandidateProtocol.mjs

@@ -0,0 +1,221 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, filesForInstallRole } from './manifest.mjs';
+import { validateCandidateManifestPath } from './updateCandidate.mjs';
+
+const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
+const SURFACE_ROOT = {
+  claude: '.claude/skills/',
+  codex: '.agents/skills/',
+};
+
+export async function verifyCandidateProtocol(candidateRoot, pkg, installed) {
+  if (!filesForInstallRole(pkg).some(({ path }) => path === READINESS_MANIFEST_PATH)) return;
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(join(candidateRoot, READINESS_MANIFEST_PATH), 'utf8'));
+  } catch {
+    throw new Error('candidate invariant schema: readiness manifest is invalid JSON');
+  }
+  validateReadinessManifest(manifest);
+  validateSkillArtifactReferences(manifest, pkg);
+  for (const [name, declaration] of Object.entries(manifest.skills)) {
+    if (!declaration.publish
+        || (declaration.installRole ?? CONSUMER_INSTALL_ROLE) !== CONSUMER_INSTALL_ROLE
+        || !declaration.surfaces.includes('claude')
+        || !declaration.surfaces.includes('codex')) continue;
+    await verifyMirrorGroup(candidateRoot, pkg, installed, name, declaration.class);
+  }
+}
+
+function validateReadinessManifest(manifest) {
+  if (!manifest || manifest.schema_version !== 1
+      || !isRecord(manifest.skills)
+      || !isRecord(manifest.readiness)
+      || !Number.isInteger(manifest.readiness.contractVersion)
+      || !isRecord(manifest.readiness.capabilities)) {
+    throw new Error('candidate invariant schema: readiness manifest identity is invalid');
+  }
+  const capabilities = manifest.readiness.capabilities;
+  for (const [name, capability] of Object.entries(capabilities)) {
+    const evidence = capability?.evidence;
+    if (!isRecord(evidence) || typeof evidence.type !== 'string'
+        || !Array.isArray(evidence.paths) || !evidence.paths.length) {
+      throw new Error(`candidate invariant schema: invalid capability evidence ${name}`);
+    }
+    for (const path of evidence.paths) {
+      try {
+        validateCandidateManifestPath(path);
+      } catch {
+        throw new Error(`candidate invariant schema: unsafe capability path ${name}`);
+      }
+    }
+  }
+  for (const [name, skill] of Object.entries(manifest.skills)) {
+    const readiness = skill?.readiness ?? {};
+    if (!isRecord(skill) || typeof skill.publish !== 'boolean'
+        || !['generic', 'vendored', 'adapter'].includes(skill.class)
+        || ![CONSUMER_INSTALL_ROLE, 'maintainer'].includes(
+          skill.installRole ?? CONSUMER_INSTALL_ROLE,
+        )
+        || !Array.isArray(skill.surfaces)
+        || (skill.publish && !skill.surfaces.length)
+        || skill.surfaces.some((surface) => !SURFACE_ROOT[surface])
+        || new Set(skill.surfaces).size !== skill.surfaces.length
+        || !isRecord(readiness)
+        || !Array.isArray(readiness.required ?? [])
+        || !isRecord(readiness.optionalBlocks ?? {})
+        || [...(readiness.required ?? []), ...Object.values(readiness.optionalBlocks ?? {})]
+          .some((capability) => typeof capability !== 'string' || !capability)) {
+      throw new Error(`candidate invariant schema: invalid skill declaration ${name}`);
+    }
+    for (const capability of [
+      ...(readiness.required ?? []),
+      ...Object.values(readiness.optionalBlocks ?? {}),
+    ]) {
+      if (!capabilities[capability]) {
+        throw new Error(`candidate invariant schema: unknown readiness reference ${name}.${capability}`);
+      }
+    }
+  }
+}
+
+function validateSkillArtifactReferences(manifest, pkg) {
+  const installable = filesForInstallRole(pkg);
+  for (const entry of installable.filter(({ kind }) => kind === 'skill')) {
+    const name = entry.ownerSkill ?? skillNameFromPath(entry.path);
+    const surface = entry.surface ?? skillSurfaceFromPath(entry.path);
+    const declaration = manifest.skills[name];
+    if (!declaration?.publish || !declaration.surfaces.includes(surface)) {
+      throw new Error(`candidate invariant schema: undeclared skill artifact ${entry.path}`);
+    }
+  }
+  for (const [name, declaration] of Object.entries(manifest.skills)) {
+    if (!declaration.publish
+        || (declaration.installRole ?? CONSUMER_INSTALL_ROLE) !== CONSUMER_INSTALL_ROLE) continue;
+    for (const surface of declaration.surfaces) {
+      const path = `${SURFACE_ROOT[surface]}${name}/SKILL.md`;
+      if (!installable.some((entry) => entry.path === path)) {
+        throw new Error(`candidate invariant schema: missing skill entrypoint ${path}`);
+      }
+    }
+  }
+}
+
+async function verifyMirrorGroup(candidateRoot, pkg, installed, name, skillClass) {
+  const relativeBySurface = {};
+  for (const [surface, root] of Object.entries(SURFACE_ROOT)) {
+    const prefix = `${root}${name}/`;
+    relativeBySurface[surface] = new Map(filesForInstallRole(pkg)
+      .filter(({ path }) => path.startsWith(prefix))
+      .map((entry) => [entry.path.slice(prefix.length), entry.path]));
+  }
+  const claude = relativeBySurface.claude;
+  const codex = relativeBySurface.codex;
+  const union = new Set([...claude.keys(), ...codex.keys()]);
+  for (const relative of union) {
+    const sourcePath = claude.get(relative);
+    const mirrorPath = codex.get(relative);
+    if (!sourcePath || !mirrorPath) {
+      throw new Error(`candidate invariant protocol: mirror file-set mismatch ${name}/${relative}`);
+    }
+    if (installed.get(sourcePath)?.origin === CONSUMER_ORIGIN
+        || installed.get(mirrorPath)?.origin === CONSUMER_ORIGIN) continue;
+    const source = await readFile(join(candidateRoot, sourcePath));
+    const mirror = await readFile(join(candidateRoot, mirrorPath));
+    if (relative.endsWith('.md') && ['generic', 'vendored'].includes(skillClass)) {
+      const left = normalizedMirrorMarkdown(source.toString('utf8'));
+      const right = normalizedMirrorMarkdown(mirror.toString('utf8'));
+      if (left.sequence.join('\0') !== right.sequence.join('\0')
+          || left.body !== right.body) {
+        throw new Error(`candidate invariant protocol: mirror content mismatch ${name}/${relative}`);
+      }
+    } else if (!source.equals(mirror)) {
+      throw new Error(`candidate invariant protocol: mirror content mismatch ${name}/${relative}`);
+    }
+  }
+}
+
+function normalizedMirrorMarkdown(text) {
+  const lines = text.split(/\r?\n/);
+  let body = lines;
+  let frontmatter = [];
+  if (lines[0] === '---') {
+    const end = lines.indexOf('---', 1);
+    if (end < 0) throw new Error('candidate invariant schema: unterminated skill frontmatter');
+    frontmatter = normalizedFrontmatter(lines.slice(1, end));
+    body = lines.slice(end + 1);
+  }
+  const kept = [];
+  const sequence = [];
+  let inTransform = false;
+  for (const line of body) {
+    const start = /^\s*<!--\s*mirror-xform:start(?:\s+([^>]*?))?\s*-->\s*$/.exec(line);
+    if (start) {
+      if (inTransform) throw new Error('candidate invariant protocol: nested mirror transform');
+      inTransform = true;
+      sequence.push((start[1] ?? '').trim());
+      continue;
+    }
+    if (/^\s*<!--\s*mirror-xform:end\s*-->\s*$/.test(line)) {
+      if (!inTransform) throw new Error('candidate invariant protocol: unmatched mirror transform');
+      inTransform = false;
+      continue;
+    }
+    if (!inTransform) kept.push(line.trimEnd());
+  }
+  if (inTransform) throw new Error('candidate invariant protocol: unterminated mirror transform');
+  return { body: [...frontmatter, ...kept].join('\n').trim(), sequence };
+}
+
+function normalizedFrontmatter(lines) {
+  const fields = new Map();
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = /^(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+)):\s*(.*)$/.exec(
+      lines[index].trimEnd(),
+    );
+    if (!match) throw new Error('candidate invariant schema: invalid skill frontmatter');
+    const key = match[1] ?? match[2] ?? match[3];
+    if (fields.has(key)) throw new Error(`candidate invariant schema: duplicate frontmatter key ${key}`);
+    let value = match[4];
+    if (/^[>|]-?$/.test(value)) {
+      const folded = value.startsWith('>');
+      const continuation = [];
+      while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+        index += 1;
+        continuation.push(lines[index].trim());
+      }
+      value = continuation.join(folded ? ' ' : '\n');
+    } else if (value.startsWith('"') && value.endsWith('"')) {
+      try { value = JSON.parse(value); } catch {
+        throw new Error(`candidate invariant schema: invalid frontmatter value ${key}`);
+      }
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1).replaceAll("''", "'");
+    } else if (/^(?:true|false|null|-?\d+(?:\.\d+)?)$/.test(value)) {
+      value = JSON.parse(value);
+    }
+    fields.set(key, value);
+  }
+  return [
+    '---',
+    ...[...fields].filter(([key]) => key !== 'description')
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, value]) => `${key}: ${JSON.stringify(value)}`),
+    '---',
+  ];
+}
+
+function skillNameFromPath(path) {
+  return path.split('/')[2];
+}
+
+function skillSurfaceFromPath(path) {
+  if (path.startsWith(SURFACE_ROOT.claude)) return 'claude';
+  if (path.startsWith(SURFACE_ROOT.codex)) return 'codex';
+  return null;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/src/lib/verifyUpdateCandidateTransaction.mjs

@@ -0,0 +1,152 @@
+import { join } from 'node:path';
+import { sha256File } from './hash.mjs';
+import { CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, KIT_ORIGIN } from './manifest.mjs';
+import { validateCandidateManifestPath } from './updateCandidate.mjs';
+
+const HASH = /^[a-f0-9]{64}$/;
+
+export function verifyDeletionState(installed, pkg, installable, preview) {
+  const installablePaths = new Set(installable.map(({ path }) => path));
+  const packageEntries = new Map(pkg.files.map((entry) => [entry.path, entry]));
+  const deleted = new Set(preview?.deleted ?? []);
+  const preserved = new Set(preview?.keptDeleted ?? []);
+  for (const [path, tracked] of installed) {
+    if (installablePaths.has(path)) continue;
+    if (deleted.has(path) && tracked.origin === KIT_ORIGIN) {
+      throw new Error(`candidate invariant deletion: stale Kit ledger path ${path}`);
+    }
+    if (tracked.origin === CONSUMER_ORIGIN) continue;
+    if (!preserved.has(path)) {
+      throw new Error(`candidate invariant deletion: undeclared legacy Kit path ${path}`);
+    }
+    const packaged = packageEntries.get(path);
+    const expectedRole = packaged?.installRole ?? tracked.installRole ?? CONSUMER_INSTALL_ROLE;
+    if ((tracked.installRole ?? CONSUMER_INSTALL_ROLE) !== expectedRole) {
+      throw new Error(`candidate invariant deletion: role mismatch ${path}`);
+    }
+  }
+  for (const path of deleted) {
+    if (installed.has(path)) {
+      throw new Error(`candidate invariant deletion: stale Kit ledger path ${path}`);
+    }
+  }
+  for (const path of preserved) {
+    if (!installed.has(path)) {
+      throw new Error(`candidate invariant deletion: missing preserved ledger path ${path}`);
+    }
+  }
+}
+
+export function verifyTransactionPreview(preview, installable, installed) {
+  if (!preview || typeof preview !== 'object') {
+    throw new Error('candidate invariant transaction: preview is required');
+  }
+  const installablePaths = new Set(installable.map(({ path }) => path));
+  const owners = new Map();
+  const actionSets = new Map();
+  for (const key of ['added', 'updated', 'deleted', 'generated', 'keptDeleted']) {
+    if (!Array.isArray(preview[key] ?? [])) {
+      throw new Error(`candidate invariant transaction: ${key} must be an array`);
+    }
+    const local = new Set();
+    for (const path of preview[key] ?? []) {
+      claimTransactionPath(path, key, local, owners);
+      if (['added', 'updated'].includes(key) && !installablePaths.has(path)) {
+        throw new Error(`candidate invariant transaction: unmanaged ${key} path ${path}`);
+      }
+      if (key === 'deleted' && installablePaths.has(path)) {
+        throw new Error(`candidate invariant transaction: deletes current package path ${path}`);
+      }
+    }
+    actionSets.set(key, local);
+  }
+  if (!Array.isArray(preview.migrations ?? [])) {
+    throw new Error('candidate invariant transaction: migrations must be an array');
+  }
+  const migrationPaths = new Set();
+  for (const migration of preview.migrations ?? []) {
+    claimTransactionPath(migration?.path, 'migrations', migrationPaths, owners);
+  }
+  verifyCollisionRecords(preview, installablePaths, installed, actionSets, owners);
+}
+
+export async function verifyDerivedArtifacts(candidateRoot, installed, preview) {
+  for (const path of preview.generated ?? []) {
+    const tracked = installed.get(path);
+    if (!tracked || tracked.origin !== CONSUMER_ORIGIN
+        || !HASH.test(tracked.installedSha256 ?? '')) {
+      throw new Error(`candidate invariant transaction: invalid generated ledger ${path}`);
+    }
+    if (await transactionHash(candidateRoot, path) !== tracked.installedSha256) {
+      throw new Error(`candidate invariant transaction: generated hash mismatch ${path}`);
+    }
+  }
+  const migrations = new Set();
+  for (const migration of preview.migrations ?? []) {
+    const path = migration?.path;
+    claimTransactionPath(path, 'migration', migrations);
+    if (!(migration.beforeSha256 === null || HASH.test(migration.beforeSha256 ?? ''))
+        || !HASH.test(migration.afterSha256 ?? '')
+        || await transactionHash(candidateRoot, path) !== migration.afterSha256) {
+      throw new Error(`candidate invariant transaction: migration hash mismatch ${path}`);
+    }
+  }
+}
+
+function verifyCollisionRecords(preview, installablePaths, installed, actionSets, owners) {
+  if (!Array.isArray(preview.collisions ?? [])
+      || !Array.isArray(preview.collisionResolutions ?? [])) {
+    throw new Error('candidate invariant transaction: collision records must be arrays');
+  }
+  const unresolved = new Set();
+  for (const path of preview.collisions ?? []) {
+    claimTransactionPath(path, 'collisions', unresolved);
+  }
+  if (unresolved.size) {
+    throw new Error('candidate invariant transaction: unresolved collision');
+  }
+  const resolutions = new Set();
+  for (const resolution of preview.collisionResolutions ?? []) {
+    const path = resolution?.path;
+    claimTransactionPath(path, 'collision resolution', resolutions);
+    if (!installablePaths.has(path)
+        || !['keep-as-owned', 'replace'].includes(resolution?.outcome)
+        || !HASH.test(resolution?.destinationSha256 ?? '')) {
+      throw new Error(`candidate invariant transaction: invalid collision resolution ${path}`);
+    }
+    const expectedOrigin = resolution.outcome === 'keep-as-owned' ? CONSUMER_ORIGIN : KIT_ORIGIN;
+    if (installed.get(path)?.origin !== expectedOrigin
+        || (resolution.outcome === 'replace' && !actionSets.get('added').has(path))
+        || (resolution.outcome === 'keep-as-owned' && owners.has(path))) {
+      throw new Error(`candidate invariant transaction: incoherent collision resolution ${path}`);
+    }
+  }
+}
+
+function claimTransactionPath(path, key, local, owners = null) {
+  try {
+    validateCandidateManifestPath(path);
+  } catch {
+    throw new Error(`candidate invariant transaction: unsafe ${key} path ${path}`);
+  }
+  if (local.has(path)) {
+    throw new Error(`candidate invariant transaction: duplicate ${key} path ${path}`);
+  }
+  local.add(path);
+  const owner = owners?.get(path);
+  if (owner && owner !== key) {
+    throw new Error(`candidate invariant transaction: overlapping action ${path}`);
+  }
+  owners?.set(path, key);
+}
+
+async function transactionHash(candidateRoot, path) {
+  try {
+    return await sha256File(join(candidateRoot, path));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`candidate invariant transaction: missing derived artifact ${path}`);
+    }
+    throw error;
+  }
+}