release-skill 0.6.2 → 0.7.0

package/src/core/postpublish-bundle.mjs

@@ -0,0 +1,342 @@
+/**
+ * Post-publish private execution bundle (F-01 / T1).
+ *
+ * Release-domain orchestration ONLY. Path classification, containment,
+ * digesting, strict reads, exclusive publication, and temporary workspaces
+ * all come from `skill-family-harness-node` (0.6.0) by package import; this
+ * module never reimplements a hash, a containment check, an atomic writer,
+ * or a temporary-workspace algorithm. It supplies exactly the release
+ * semantics the Foundation mechanisms do not own:
+ *
+ * - WHERE the frozen bytes live: digest-addressed under the SAME
+ *   `.release-skill` that owns the plan authority — mechanically derived,
+ *   never a caller-supplied arbitrary root:
+ *
+ *       <plan authority .release-skill>/postpublish-bundles/<closure.digest>/<resource.path>
+ *
+ * - WHAT gets frozen: the closed-world `postPublish.executionFiles` manifest
+ *   (parent-workspace files that post-publish commands need but the frozen
+ *   tag tree does not contain; helpers must be declared explicitly). The
+ *   closure is the verbatim return of `computeResourceClosure()` — sorted,
+ *   deduplicated, containment-read, digested by Foundation. The frozen plan
+ *   (`postPublish.executionBundle`) is the ONLY source of truth for the
+ *   bundle; there is no parallel manifest and no second bundle digest —
+ *   `publicFiles` ride the plan digest with everything else.
+ *
+ * - HOW the bytes return at execution time: distribute/postVerify strictly
+ *   re-read every bundle file (frozen sha256 content guard + publication
+ *   mode guard), recompute the closure through Foundation in a disposable
+ *   workspace, compare it with the plan's frozen closure, and only then
+ *   install the verified bytes into the detached tag worktree — exclusively,
+ *   so a bundle entry can never shadow a frozen tag file. Any mismatch
+ *   fails closed BEFORE any hook or external write.
+ *
+ * Private files execute through the tag's interpreter and never depend on
+ * live executable modes; the bundle publishes and re-verifies one fixed
+ * regular-file mode.
+ *
+ * @module core/postpublish-bundle
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+
+import {
+  HARNESS_ERROR_KINDS,
+  classifyPathInput,
+  computeResourceClosure,
+  publishFileExclusive,
+  readFileStrict,
+  withTemporaryWorkspace,
+} from 'skill-family-harness-node';
+
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+
+/** Foundation mechanism identity frozen into every executionBundle. */
+export const EXECUTION_BUNDLE_MECHANISM = 'foundation.harness.resource-closure';
+
+/** Bundle store directory name under the plan authority `.release-skill`. */
+export const POSTPUBLISH_BUNDLES_DIRNAME = 'postpublish-bundles';
+
+/** Authority directory that owns plans, approvals, runs — and bundles. */
+export const RELEASE_SKILL_DIRNAME = '.release-skill';
+
+/**
+ * The single regular-file mode every bundle byte is published with and must
+ * still carry at execution time. A mode deviation is tamper evidence: the
+ * frozen closure binds content, and publication mode is this fixed policy
+ * constant — no per-file mode manifest exists.
+ */
+export const EXECUTION_BUNDLE_FILE_MODE = 0o644;
+
+function fail(message, details = {}) {
+  throw new ReleaseError(GATE_FAILED, `execution bundle: ${message}`, details);
+}
+
+/**
+ * Mechanically derive the bundle store root from the `.release-skill`
+ * authority directory that owns the plan. The caller never supplies an
+ * arbitrary root: the store is a fixed child of the plan's own authority
+ * directory.
+ *
+ * @param {string} releaseSkillDir - Absolute path of a `.release-skill` dir.
+ * @returns {string} Absolute bundle store root (may not exist yet).
+ */
+export function bundleRootForAuthorityDir(releaseSkillDir) {
+  const absolute = resolve(releaseSkillDir);
+  if (basename(absolute) !== RELEASE_SKILL_DIRNAME) {
+    fail('bundle root must be derived from a .release-skill authority directory', { releaseSkillDir: absolute });
+  }
+  return join(absolute, POSTPUBLISH_BUNDLES_DIRNAME);
+}
+
+/**
+ * Mechanically derive the bundle store root from a plan authority path:
+ * anchor on the nearest `.release-skill` ancestor of the plan file.
+ *
+ * @param {string} planPath - Absolute path of the frozen plan.
+ * @returns {string} Absolute bundle store root.
+ */
+export function deriveBundleRoot(planPath) {
+  const absolute = resolve(planPath);
+  const segments = absolute.split(sep).filter(Boolean);
+  const anchorIndex = segments.lastIndexOf(RELEASE_SKILL_DIRNAME);
+  if (anchorIndex < 0) {
+    fail('plan path has no .release-skill ancestor; cannot derive the bundle store root', { planPath: absolute });
+  }
+  const prefix = absolute.startsWith(sep) ? sep : '';
+  const releaseSkillDir = prefix + join(...segments.slice(0, anchorIndex + 1));
+  return bundleRootForAuthorityDir(releaseSkillDir);
+}
+
+/**
+ * Freeze the private execution bundle for one postPublish declaration.
+ *
+ * Order of operations (all before the plan is written):
+ * 1. Foundation path classification for every declared entry (no parallel
+ *    path regex; ambiguous inputs never reach the filesystem);
+ * 2. `computeResourceClosure()` — Foundation sorts, deduplicates,
+ *    containment-reads (every root-escape class rejected, root-internal
+ *    ancestor aliases are path aliases, not escapes), and digests; the
+ *    return value is frozen VERBATIM;
+ * 3. strict re-read of every entry bound to its frozen sha256 (any
+ *    concurrent drift fails closed; a symbolic-link entry is never readable
+ *    — Foundation no-follow), then exclusive publication of the exact bytes
+ *    under `<bundleRoot>/<closure.digest>/<resource.path>`. Re-preparing
+ *    identical bytes is idempotent; divergent bytes on an occupied
+ *    digest-addressed slot fail closed.
+ *
+ * Symbolic-link policy is fully delegated to Foundation (2026-08-21 handoff
+ * ruling C): anything escaping the workspace root is rejected by closure
+ * containment, a leaf symbolic link is rejected by `readFileStrict`
+ * (no-follow), and ordinary-file identity and digests stay bound.
+ *
+ * @param {object} params
+ * @param {string} params.workspaceRoot - Release workspace root.
+ * @param {string} params.releaseSkillDir - `.release-skill` authority dir
+ *   that will own the frozen plan (mechanical bundle-root anchor).
+ * @param {string[]} [params.executionFiles] - Closed-world manifest.
+ * @param {object[]} [params.publicFiles] - Release-unit public projection
+ *   frozen into the plan alongside the closure.
+ * @returns {Promise<{foundationMechanism: string, closure: object, publicFiles: object[]}>}
+ */
+export async function freezeExecutionBundle({ workspaceRoot, releaseSkillDir, executionFiles = [], publicFiles = [] } = {}) {
+  if (!workspaceRoot || typeof workspaceRoot !== 'string') {
+    throw new TypeError('freezeExecutionBundle: workspaceRoot must be a directory path string');
+  }
+  if (!Array.isArray(executionFiles)) {
+    throw new TypeError('freezeExecutionBundle: executionFiles must be an array');
+  }
+  for (const relPath of executionFiles) {
+    const classification = classifyPathInput(relPath);
+    if (!classification.ok) {
+      fail(`executionFiles entry is not a safe workspace-relative path (kind: ${classification.kind})`, {
+        path: typeof relPath === 'string' ? relPath : typeof relPath,
+        kind: classification.kind,
+      });
+    }
+  }
+
+  // Foundation closure: sort, dedupe, containment reads, sha256 — verbatim.
+  // Thin adapter mapping only: Foundation mechanism errors (lexical
+  // traversal, symlink/realpath escapes, missing inputs) surface as
+  // release-domain GATE_FAILED without reimplementing any mechanism.
+  let closure;
+  try {
+    closure = await computeResourceClosure({
+      root: workspaceRoot,
+      resources: executionFiles.map((path) => ({ path, role: 'input' })),
+    });
+  } catch (cause) {
+    if (cause instanceof ReleaseError) throw cause;
+    fail(`cannot compute the executionFiles closure: ${cause?.message ?? cause}`, {
+      kind: cause?.details?.kind,
+    });
+  }
+
+  const bundleRoot = bundleRootForAuthorityDir(releaseSkillDir);
+  await mkdir(bundleRoot, { recursive: true });
+
+  for (const resource of closure.resources) {
+    // Strict re-read bound to the frozen digest: any byte drift between the
+    // closure computation and the publication fails closed.
+    let receipt;
+    try {
+      receipt = await readFileStrict(workspaceRoot, resource.path, { expectedSha256: resource.sha256 });
+    } catch (cause) {
+      fail(`cannot strictly read executionFiles entry for publication: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+    const relTarget = join(closure.digest, resource.path);
+    try {
+      await publishFileExclusive(bundleRoot, relTarget, receipt.content, {
+        mode: EXECUTION_BUNDLE_FILE_MODE,
+        createParents: true,
+      });
+    } catch (cause) {
+      if (cause?.details?.kind === HARNESS_ERROR_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+        // Idempotent same-bytes re-prepare: the existing slot must carry the
+        // exact frozen bytes at the publication mode, verified strictly.
+        try {
+          const existing = await readFileStrict(bundleRoot, relTarget, { expectedSha256: resource.sha256 });
+          if (existing.mode !== EXECUTION_BUNDLE_FILE_MODE) {
+            fail('existing bundle file carries an unexpected mode', { path: resource.path, mode: existing.mode });
+          }
+          continue;
+        } catch (verifyCause) {
+          fail(`bundle slot already exists with divergent bytes: ${verifyCause?.message ?? verifyCause}`, {
+            path: resource.path,
+            kind: verifyCause?.details?.kind,
+          });
+        }
+      }
+      fail(`cannot publish bundle bytes: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+  }
+
+  return {
+    foundationMechanism: EXECUTION_BUNDLE_MECHANISM,
+    closure,
+    publicFiles: structuredClone(publicFiles),
+  };
+}
+
+/**
+ * Field-by-field closure comparison (the recomputed Foundation closure must
+ * equal the frozen plan closure; the digest alone is compared first).
+ */
+function sameClosureResources(actual, expected) {
+  if (!Array.isArray(actual) || !Array.isArray(expected) || actual.length !== expected.length) return false;
+  for (let index = 0; index < expected.length; index += 1) {
+    const left = actual[index] ?? {};
+    const right = expected[index] ?? {};
+    if (left.path !== right.path || left.role !== right.role
+      || left.exists !== right.exists || left.sha256 !== right.sha256) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Re-verify the frozen execution bundle and install ONLY the verified bytes
+ * into the detached tag worktree. Runs BEFORE any hook or external write.
+ *
+ * Steps:
+ * 1. Strictly read every frozen resource from the digest-addressed store
+ *    (`readFileStrict` with the frozen sha256 content guard); the file mode
+ *    must still equal the publication mode — any deviation is tamper;
+ * 2. recompute the closure through Foundation in a disposable workspace and
+ *    compare it (digest + resources) with the plan's frozen closure;
+ * 3. exclusively publish the verified bytes into the worktree — an occupied
+ *    target means the bundle would shadow a frozen tag file and fails closed.
+ *
+ * @param {object} params
+ * @param {object} params.plan - Frozen plan (postPublish.executionBundle).
+ * @param {string} params.planPath - Absolute plan authority path (mechanical
+ *   bundle-root anchor).
+ * @param {string} params.worktreePath - Detached tag worktree root.
+ * @returns {Promise<{installed: string[]}>} Installed relative paths.
+ */
+export async function verifyAndInstallExecutionBundle({ plan, planPath, worktreePath } = {}) {
+  const bundle = plan?.postPublish?.executionBundle;
+  if (!bundle) return { installed: [] };
+  const closure = bundle.closure;
+  if (!closure || !Array.isArray(closure.resources) || typeof closure.digest !== 'string') {
+    fail('plan carries a malformed executionBundle closure');
+  }
+
+  const bundleRoot = deriveBundleRoot(planPath);
+  const bytesByPath = new Map();
+  for (const resource of closure.resources) {
+    if (!resource || resource.role !== 'input' || resource.exists !== true || typeof resource.sha256 !== 'string') {
+      fail('executionBundle closure resources must be existing input resources with frozen digests', {
+        path: resource?.path,
+      });
+    }
+    let receipt;
+    try {
+      receipt = await readFileStrict(bundleRoot, join(closure.digest, resource.path), {
+        expectedSha256: resource.sha256,
+      });
+    } catch (cause) {
+      fail(`bundle resource is missing or drifted from the frozen closure: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+    if (receipt.mode !== EXECUTION_BUNDLE_FILE_MODE) {
+      fail(`bundle resource mode was tampered (expected ${EXECUTION_BUNDLE_FILE_MODE.toString(8)}, got ${receipt.mode.toString(8)})`, {
+        path: resource.path,
+      });
+    }
+    bytesByPath.set(resource.path, receipt.content);
+  }
+
+  // Foundation recomputation in a disposable workspace: any inconsistency
+  // fails before a hook or an external write.
+  try {
+    await withTemporaryWorkspace(async (workspace) => {
+      for (const resource of closure.resources) {
+        await workspace.writeFile(resource.path, bytesByPath.get(resource.path));
+      }
+      const recomputed = await computeResourceClosure({
+        root: workspace.root,
+        resources: closure.resources.map((resource) => ({ path: resource.path, role: resource.role })),
+      });
+      if (recomputed.digest !== closure.digest || !sameClosureResources(recomputed.resources, closure.resources)) {
+        fail('recomputed bundle closure differs from the frozen plan closure');
+      }
+    }, { prefix: 'rs-execution-bundle-verify-' });
+  } catch (cause) {
+    if (cause instanceof ReleaseError) throw cause;
+    fail(`bundle closure recomputation failed: ${cause?.message ?? cause}`, { kind: cause?.details?.kind });
+  }
+
+  // Install verified bytes into the tag worktree — exclusively: the bundle
+  // must never overwrite (shadow) a file that already belongs to the tag.
+  const installed = [];
+  for (const resource of closure.resources) {
+    try {
+      await publishFileExclusive(worktreePath, resource.path, bytesByPath.get(resource.path), {
+        mode: EXECUTION_BUNDLE_FILE_MODE,
+        createParents: true,
+      });
+    } catch (cause) {
+      if (cause?.details?.kind === HARNESS_ERROR_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+        fail(`execution bundle would overwrite a frozen tag file: ${resource.path}`, { path: resource.path });
+      }
+      fail(`cannot install bundle bytes into the tag worktree: ${cause?.message ?? cause}`, {
+        path: resource.path,
+        kind: cause?.details?.kind,
+      });
+    }
+    installed.push(resource.path);
+  }
+  return { installed };
+}

package/src/core/postpublish-projection.mjs

@@ -0,0 +1,210 @@
+/**
+ * Public payload managed projection (F-06 / T6).
+ *
+ * Release-domain orchestration ONLY. Full preflight, path containment,
+ * lexical classification, transactional writes, rollback, and closure
+ * digests all come from the exact Foundation version pinned by
+ * `packages/release-skill/package.json` and `pnpm-lock.yaml`
+ * `compileProjectionPlan()` / `runProjection()` by package import; strict
+ * no-follow source reads come from `skill-family-harness-node`
+ * `readFileStrict()`. This module never reimplements a containment check, a
+ * preflight, a writer, or a rollback — it supplies exactly the release
+ * semantics the Foundation mechanisms do not own:
+ *
+ * - WHAT is projected: the frozen plan's `postPublish.executionBundle.
+ *   publicFiles` mapping (schema- and runtime-validated before the plan was
+ *   frozen). Live project configuration is never read here or downstream —
+ *   the frozen plan is the only authority, per the R1 timing contract.
+ * - WHERE the bytes come from: the detached tag worktree at the frozen
+ *   tagCommit (snapshot layout — public files live at their `to` paths),
+ *   read strictly (no-follow, regular-file identity, digest receipt).
+ * - WHERE the payload lands: a completely fresh `hub-payload` root inside
+ *   the execution worktree. The payload root must not pre-exist; a planted
+ *   symlink or stale directory at that path fails closed before any write.
+ * - HOW authority is bound: the frozen mapping bytes ride the projection
+ *   plan as a `caller-bytes` authority binding (FG-3) — the projection never
+ *   reads authority from the target root and never forges target-local
+ *   authority facts; the Kit re-verifies the digest-bound bytes before every
+ *   mutation.
+ *
+ * Ordering guarantee: mapping shape checks, strict source staging, and the
+ * pure compile step all happen BEFORE the payload root is created — lexical
+ * escapes, duplicates, and collisions refuse with zero writes and leave no
+ * partial `hub-payload` behind.
+ *
+ * @module core/postpublish-projection
+ */
+
+import { chmod, lstat, mkdir, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import {
+  buildProjectionClosure,
+  compileProjectionPlan,
+  runProjection,
+} from 'skill-family-engineering-kit';
+import { digestBytes, readFileStrict } from 'skill-family-harness-node';
+
+import { ReleaseError, POST_PUBLISH_VERIFY_FAILED } from './errors.mjs';
+
+/** Mechanism identity recorded in the materialize evidence. */
+export const PROJECTION_MECHANISM = 'foundation.engineering-kit.projection';
+
+/** The fresh payload root staged inside the execution worktree. */
+export const PUBLIC_PAYLOAD_DIRNAME = 'hub-payload';
+
+/** Authority identity of the frozen publicFiles mapping. */
+const AUTHORITY_ID = 'frozen-public-files';
+const AUTHORITY_PATH = 'postpublish-public-files.json';
+
+/** Ownership identity recorded for every projected payload file. */
+const OWNER_ID = 'release-skill-postpublish';
+
+function fail(message, details = {}) {
+  throw new ReleaseError(POST_PUBLISH_VERIFY_FAILED, `public payload projection: ${message}`, details);
+}
+
+/**
+ * Stage the frozen public payload into a fresh `hub-payload` root inside the
+ * execution worktree through the Foundation managed projection.
+ *
+ * @param {object} params
+ * @param {string} params.executionWorktreeRoot - Detached tag worktree root
+ *   (frozen tagCommit checkout; snapshot layout).
+ * @param {string} params.candidateRoot - Disposable staging directory for the
+ *   candidate closure (external to the payload root; caller owns cleanup).
+ * @param {object[]} params.publicFiles - Frozen plan publicFiles mapping.
+ * @returns {Promise<{payloadRoot: string, fileCount: number, mechanism: string}>}
+ * @throws {ReleaseError} POST_PUBLISH_VERIFY_FAILED on any refusal — after
+ *   Foundation preflight/rollback semantics, never with a partial payload.
+ */
+export async function projectPublicPayload({ executionWorktreeRoot, candidateRoot, publicFiles } = {}) {
+  if (!executionWorktreeRoot || typeof executionWorktreeRoot !== 'string') {
+    throw new TypeError('projectPublicPayload: executionWorktreeRoot must be a directory path string');
+  }
+  if (!candidateRoot || typeof candidateRoot !== 'string') {
+    throw new TypeError('projectPublicPayload: candidateRoot must be a directory path string');
+  }
+
+  // --- Domain mapping shape (schema-validated upstream; re-checked fail-
+  // closed). Lexical path rejection belongs to Foundation classification. ---
+  if (!Array.isArray(publicFiles) || publicFiles.length === 0) {
+    fail('the frozen plan carries no publicFiles mapping; the payload cannot be staged');
+  }
+  for (const [index, entry] of publicFiles.entries()) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)
+      || typeof entry.from !== 'string' || entry.from.length === 0
+      || typeof entry.to !== 'string' || entry.to.length === 0
+      || entry.mode !== 'preserve') {
+      fail(`frozen publicFiles entry ${index} is not a valid preserve-mode mapping`, { index });
+    }
+  }
+
+  const worktreeReal = await realpath(executionWorktreeRoot).catch(() => null);
+  if (!worktreeReal) {
+    fail('the execution worktree does not resolve to an existing directory', { executionWorktreeRoot });
+  }
+
+  // --- Payload target preflight: the root must not pre-exist. The tag
+  // worktree is disposable and freshly created; a planted symlink or stale
+  // directory at the payload path fails closed BEFORE any write. ---
+  const payloadPath = join(worktreeReal, PUBLIC_PAYLOAD_DIRNAME);
+  const preExisting = await lstat(payloadPath).catch(() => null);
+  if (preExisting) {
+    fail(`the payload root already exists in the tag worktree (${preExisting.isSymbolicLink() ? 'symbolic link' : 'pre-existing entry'})`, {
+      path: PUBLIC_PAYLOAD_DIRNAME,
+    });
+  }
+
+  // --- Candidate staging: strict no-follow reads of every frozen `to` source
+  // from the frozen worktree (never the live workspace). A symlinked source
+  // is refused here — the escape target is never opened. ---
+  const stagedResources = [];
+  for (const entry of publicFiles) {
+    let receipt;
+    try {
+      receipt = await readFileStrict(executionWorktreeRoot, entry.to);
+    } catch (cause) {
+      fail(`cannot strictly read the frozen public file "${entry.to}" from the tag worktree: ${cause?.message ?? cause}`, {
+        path: entry.to,
+        kind: cause?.details?.kind,
+      });
+    }
+    const stagePath = join(candidateRoot, entry.to);
+    await mkdir(dirname(stagePath), { recursive: true });
+    await writeFile(stagePath, receipt.content);
+    await chmod(stagePath, receipt.mode);
+    stagedResources.push({ path: entry.to, sha256: receipt.sha256, mode: receipt.mode });
+  }
+
+  // --- Authority binding: the frozen mapping bytes ride the plan as a
+  // caller-bytes binding — no authority filesystem access, nothing forged
+  // into the target root. ---
+  const authorityBytes = Buffer.from(JSON.stringify(publicFiles), 'utf8');
+
+  // --- Pure compile: containment, duplicates, portable collisions, closure
+  // digests — every refusal happens before the payload root exists. ---
+  let prepared;
+  try {
+    prepared = compileProjectionPlan({
+      rootBinding: payloadPath,
+      authoritySources: [{
+        id: AUTHORITY_ID,
+        path: AUTHORITY_PATH,
+        type: 'file',
+        sha256: digestBytes(authorityBytes),
+        mode: 0o644,
+      }],
+      ownership: publicFiles.map((entry) => ({
+        path: entry.to,
+        authoritySource: AUTHORITY_ID,
+        owner: { kind: 'managed', id: OWNER_ID },
+        expect: { state: 'absent' },
+      })),
+      handwrittenPolicy: { authoritySource: AUTHORITY_ID, patterns: [] },
+      previousOwnedClosure: buildProjectionClosure([]),
+      externalCandidateClosure: buildProjectionClosure(stagedResources),
+      authorityBinding: {
+        kind: 'caller-bytes',
+        bytes: { [AUTHORITY_ID]: authorityBytes.toString('base64') },
+        freshRoot: true,
+      },
+    });
+  } catch (cause) {
+    fail(`the frozen publicFiles mapping cannot be compiled into a projection plan: ${cause?.message ?? cause}`, {
+      kind: cause?.details?.kind,
+    });
+  }
+
+  // --- Create the payload root and re-verify its identity (TOCTOU guard:
+  // the realpath must equal the compiled rootBinding). ---
+  try {
+    await mkdir(payloadPath);
+  } catch (cause) {
+    fail(`cannot create the fresh payload root: ${cause?.message ?? cause}`, { path: PUBLIC_PAYLOAD_DIRNAME });
+  }
+  const payloadReal = await realpath(payloadPath).catch(() => null);
+  if (!payloadReal || payloadReal !== payloadPath) {
+    fail('the payload root identity changed during creation (symbolic-link ancestor refused)', {
+      path: PUBLIC_PAYLOAD_DIRNAME,
+    });
+  }
+
+  // --- Foundation managed projection: complete preflight already passed;
+  // runProjection re-verifies candidate, authority, and target expectations
+  // before every mutation and restores the complete closure on failure. ---
+  try {
+    await runProjection({
+      root: payloadPath,
+      manifest: prepared.manifest,
+      candidateRoot,
+      preparedProjection: prepared,
+    });
+  } catch (cause) {
+    fail(`projection execution refused: ${cause?.message ?? cause}`, {
+      kind: cause?.details?.kind,
+    });
+  }
+
+  return { payloadRoot: payloadReal, fileCount: publicFiles.length, mechanism: PROJECTION_MECHANISM };
+}