release-skill 0.6.2 → 0.7.0

package/src/core/hooks.mjs

@@ -197,6 +197,10 @@ function buildFilteredEnv(envAllowlist, contextEnv) {
  * @param {Object} context
  * @param {string} context.root           - Absolute project root.
  * @param {Record<string, string>} [context.env] - Extra env variables.
+ * @param {Record<string, string>} [context.injectEnv] - Always-injected
+ *   contract variables (merged AFTER allowlist filtering; used by the
+ *   postPublish hook context contract RELEASE_SKILL_POSTPUBLISH_CONTEXT).
+ *   Keys must match /^[A-Z_][A-Z0-9_]*$/, values must be strings.
  *
  * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
  *
@@ -233,6 +237,30 @@ export async function runHook(hook, context) {
   // --- Build safe environment ---
   const env = buildFilteredEnv(envAllowlist, context.env);
 
+  // --- Always-injected contract variables (postPublish context, v0.6.3 R1).
+  // Merged after allowlist filtering: declarations cannot be mutated to carry
+  // the context variable, and the runner must not depend on envAllowlist.
+  if (context.injectEnv !== undefined) {
+    if (!context.injectEnv || typeof context.injectEnv !== 'object' || Array.isArray(context.injectEnv)) {
+      throw new ReleaseError('INVALID_HOOK', 'context.injectEnv must be a plain object');
+    }
+    for (const [key, value] of Object.entries(context.injectEnv)) {
+      if (!ENV_KEY_PATTERN.test(key)) {
+        throw new ReleaseError(
+          'INVALID_HOOK',
+          `context.injectEnv key "${key}" must match /^[A-Z_][A-Z0-9_]*$/`,
+        );
+      }
+      if (typeof value !== 'string') {
+        throw new ReleaseError(
+          'INVALID_HOOK',
+          `context.injectEnv value for "${key}" must be a string`,
+        );
+      }
+      env[key] = value;
+    }
+  }
+
   // --- Set up timeout ---
   const executable = command[0];
   const args = command.slice(1);

package/src/core/marketplace-registry-entry.mjs

@@ -0,0 +1,175 @@
+/**
+ * marketplace-registry-entry preset: direct-edit downstream registry entry
+ * update (v0.6.3 R4, design §2.5).
+ *
+ * For downstream marketplaces WITHOUT their own governance/render pipeline:
+ * locate the registry entry by config.entryKey inside config.registryPath,
+ * update the declared fieldsFromPlan from the FROZEN plan values (§2.3
+ * context projection), run the declared downstream gates (argument arrays via
+ * the R1 hook runner), then push. Hubs with their own governance use
+ * proposal-inbox instead.
+ *
+ * Registry document shape (canonical, validated fail-closed):
+ * { "entries": [ { "key": "<entryKey>", ...fields } ] }
+ * - a missing registry file, a missing/malformed `entries` array, or a
+ *   missing entry key is REMOTE_CONFLICT: the downstream state disagrees
+ *   with the declaration and a human decides (nothing is ever invented);
+ * - the updated document is serialized deterministically (2-space indent +
+ *   trailing newline): byte-identical output -> NO_CHANGE (idempotent);
+ * - every other entry and field is preserved untouched.
+ *
+ * fieldsFromPlan maps entry field -> §2.3 context field; only frozen plan
+ * values are ever written (version/tag/commit/tree/manifestDigest/planDigest/
+ * publishedAt/unitId). A source value absent from the frozen plan fails
+ * closed before any write.
+ *
+ * @module core/marketplace-registry-entry
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { ReleaseError, GATE_FAILED, REMOTE_CONFLICT } from './errors.mjs';
+import { FIELDS_FROM_PLAN_SOURCES } from './presets.mjs';
+import { applyDownstreamGitChange } from './preset-gitwrite.mjs';
+
+export { FIELDS_FROM_PLAN_SOURCES };
+
+/**
+ * Apply the frozen-plan field update to one registry document. Pure and
+ * deterministic: returns the updated document, or throws when the document
+ * shape or the entry disagrees with the declaration.
+ *
+ * @param {object} registry - Parsed registry document.
+ * @param {object} params - { entryKey, fieldsFromPlan, contextProjection }.
+ * @returns {object} The updated registry document (new object).
+ * @throws {ReleaseError} REMOTE_CONFLICT when the entry cannot be located;
+ *   GATE_FAILED when a frozen source value is missing.
+ */
+export function updateRegistryEntry(registry, params) {
+  const { entryKey, fieldsFromPlan, contextProjection } = params ?? {};
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+    throw new ReleaseError(REMOTE_CONFLICT, 'marketplace registry file is not a JSON object; human decision required', {});
+  }
+  if (!Array.isArray(registry.entries)) {
+    throw new ReleaseError(
+      REMOTE_CONFLICT,
+      'marketplace registry file carries no "entries" array; the marketplace-registry-entry preset expects { "entries": [ { "key": ... } ] }',
+      {},
+    );
+  }
+  const entryIndex = registry.entries.findIndex(
+    (entry) => entry && typeof entry === 'object' && !Array.isArray(entry) && entry.key === entryKey,
+  );
+  if (entryIndex < 0) {
+    throw new ReleaseError(
+      REMOTE_CONFLICT,
+      `marketplace registry entry "${entryKey}" not found; registering a new entry requires a human decision`,
+      { entryKey },
+    );
+  }
+
+  const updated = JSON.parse(JSON.stringify(registry)); // deep, order-stable copy
+  const entry = updated.entries[entryIndex];
+  for (const [entryField, sourceField] of Object.entries(fieldsFromPlan)) {
+    const value = contextProjection?.[sourceField];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `fieldsFromPlan."${entryField}" maps to context field "${sourceField}" which the frozen plan does not provide`,
+        { entryField, sourceField },
+      );
+    }
+    entry[entryField] = value;
+  }
+  return updated;
+}
+
+/** Deterministic registry serialization (byte-stable NO_CHANGE detection). */
+export function serializeRegistry(registry) {
+  return `${JSON.stringify(registry, null, 2)}\n`;
+}
+
+/**
+ * Execute one marketplace-registry-entry preset hook end-to-end: read the
+ * downstream registry, apply the frozen-plan update, run the downstream
+ * gates, and push (never --force). Shared by distribute and postVerify.
+ *
+ * @param {object} params
+ * @param {object} params.hook - Declared hook entry (config bound).
+ * @param {object} params.contextProjection - The §2.3 context projection.
+ * @param {object} params.commitIdentity - Frozen commitIdentity.
+ * @param {string} params.releaseWorkspaceRoot - Release workspace root (the
+ *   real project root; workspace addressing resolution + write exclusion).
+ * @param {Function} [params.exec] - Injectable git exec (tests).
+ * @param {Function} [params.hookRunner] - Injectable gate runner (tests).
+ * @returns {Promise<{ status: string, observation: object, registryPath: string }>}
+ */
+export async function executeMarketplaceRegistryEntryHook(params) {
+  const { hook, contextProjection, commitIdentity, releaseWorkspaceRoot, exec, hookRunner } = params ?? {};
+  const config = hook?.config;
+  const target = config?.target;
+  if (!target || typeof target.branch !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'marketplace-registry-entry requires config.target with a branch');
+  }
+  const registryPath = config?.registryPath ?? 'registry.json';
+  const entryKey = config?.entryKey;
+  const fieldsFromPlan = config?.fieldsFromPlan;
+  if (typeof entryKey !== 'string' || entryKey.length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'marketplace-registry-entry requires config.entryKey');
+  }
+  if (!fieldsFromPlan || typeof fieldsFromPlan !== 'object' || Object.keys(fieldsFromPlan).length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'marketplace-registry-entry requires a non-empty config.fieldsFromPlan');
+  }
+
+  const unitId = contextProjection?.unitId ?? 'unknown';
+  const version = contextProjection?.version ?? 'unknown';
+
+  let currentText = null;
+  const mutate = async (worktree) => {
+    const absoluteRegistry = join(worktree, registryPath);
+    let raw;
+    try {
+      raw = await readFile(absoluteRegistry, 'utf8');
+    } catch {
+      throw new ReleaseError(
+        REMOTE_CONFLICT,
+        `marketplace registry file "${registryPath}" is missing in the downstream repository; creating it requires a human decision`,
+        { registryPath },
+      );
+    }
+    currentText = raw;
+    let registry;
+    try {
+      registry = JSON.parse(raw);
+    } catch {
+      throw new ReleaseError(
+        REMOTE_CONFLICT,
+        `marketplace registry file "${registryPath}" is not valid JSON; human decision required`,
+        { registryPath },
+      );
+    }
+    const updated = updateRegistryEntry(registry, { entryKey, fieldsFromPlan, contextProjection });
+    const serialized = serializeRegistry(updated);
+    if (serialized === currentText) {
+      // Leave the file untouched: the staged tree stays equal to the tip and
+      // the shared lifecycle reports NO_CHANGE.
+      return;
+    }
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(absoluteRegistry, serialized);
+  };
+
+  const result = await applyDownstreamGitChange({
+    target,
+    commitIdentity,
+    commitSubject: `release-skill marketplace-registry-entry ${unitId} ${version} (${entryKey})`,
+    mutate,
+    gates: config?.gates ?? [],
+    contextProjection,
+    releaseWorkspaceRoot,
+    ...(exec !== undefined ? { exec } : {}),
+    ...(hookRunner !== undefined ? { hookRunner } : {}),
+  });
+  return { ...result, registryPath };
+}

package/src/core/notify-handoff.mjs

@@ -0,0 +1,76 @@
+/**
+ * notify-handoff preset: the zero-write floor (v0.6.3 R4, design §2.5).
+ *
+ * Every downstream scenario degrades to at least this behavior: NO writes of
+ * any kind — the §2.3 frozen context is rendered into a DETERMINISTIC
+ * downstream sync checklist (version/tag/sha/tree/evidence path/suggested
+ * actions), which the command layer writes into the run evidence and echoes.
+ * Zero configuration, usable by any project, requiresApproval defaults false.
+ *
+ * The renderer is pure: identical inputs produce byte-identical checklists
+ * (snapshot-locked by test/postpublish-notify-handoff.test.mjs). payloadDir
+ * and any other local-only artifact never enter the checklist.
+ *
+ * @module core/notify-handoff
+ */
+
+/** Context fields rendered into the checklist, in deterministic order. */
+const CHECKLIST_FACT_FIELDS = ['unitId', 'version', 'tag', 'commit', 'tree', 'manifestDigest', 'planDigest', 'runId', 'publishedAt'];
+
+/**
+ * Render the deterministic downstream sync checklist for the notify-handoff
+ * preset. Pure function — no I/O, no writes.
+ *
+ * @param {object} contextProjection - The §2.3 context projection.
+ * @param {object} [options]
+ * @param {string} [options.evidencePath] - This run's evidence path (rendered
+ *   as the `evidence:` line when provided).
+ * @returns {string[]} Checklist lines (deterministic order and wording).
+ */
+export function renderNotifyHandoffChecklist(contextProjection, options = {}) {
+  const context = contextProjection ?? {};
+  const lines = [
+    'notify-handoff downstream sync checklist (zero-write floor; no automated write was performed)',
+  ];
+  for (const field of CHECKLIST_FACT_FIELDS) {
+    const value = context[field];
+    if (typeof value === 'string' && value.length > 0) {
+      lines.push(`- ${field}: ${value}`);
+    }
+  }
+  const verifyEvidence = context.verifyEvidence;
+  if (verifyEvidence && typeof verifyEvidence === 'object') {
+    lines.push(`- verifyEvidence: runId=${verifyEvidence.runId ?? ''} status=${verifyEvidence.status ?? ''} finishedAt=${verifyEvidence.finishedAt ?? ''}`);
+  }
+  if (typeof options.evidencePath === 'string' && options.evidencePath.length > 0) {
+    lines.push(`- evidence: ${options.evidencePath}`);
+  }
+  lines.push('suggested actions:');
+  lines.push('- manually sync the frozen release facts above into every downstream consumer (marketplace entries, docs sites, hub registries)');
+  lines.push('- downstream updates require human action or the downstream governance workflow; this hook wrote nothing');
+  return lines;
+}
+
+/**
+ * Execute one notify-handoff preset hook: render the checklist. The command
+ * layer evidences/echoes it; this module performs zero writes.
+ *
+ * @param {object} params
+ * @param {object} params.contextProjection - The §2.3 context projection.
+ * @param {string} [params.evidencePath] - This run's evidence path.
+ * @returns {Promise<{ status: 'EXECUTED', mode: 'notify-handoff',
+ *   checklist: string[], manualSyncPrompt: string, observation: object }>}
+ */
+export async function executeNotifyHandoffHook(params) {
+  const { contextProjection, evidencePath } = params ?? {};
+  const checklist = renderNotifyHandoffChecklist(contextProjection, {
+    ...(evidencePath !== undefined ? { evidencePath } : {}),
+  });
+  return {
+    status: 'EXECUTED',
+    mode: 'notify-handoff',
+    checklist,
+    manualSyncPrompt: checklist.join('\n'),
+    observation: { mode: 'notify-handoff' },
+  };
+}

package/src/core/postpublish-approval.mjs

@@ -0,0 +1,241 @@
+/**
+ * Checkpoint-level approval for requiresApproval postPublish hooks
+ * (v0.6.3 R1, design §2.7 ruling 2).
+ *
+ * A `requiresApproval: true` hook needs its own approval record binding
+ * (planDigest, hookId). The plan-level approval-record schema is NOT
+ * extended (its top level is additionalProperties: false); this module owns
+ * the separate postpublish-approval-record schema and its validation.
+ *
+ * Time semantics (24h max window, 5-minute clock-skew tolerance, expiry) are
+ * delegated wholesale to core/approval.mjs `validateApprovalTimeWindow` so
+ * both approval kinds can never drift apart. Hook config changes change the
+ * plan digest, so approvals invalidate naturally with the plan; `runId` is
+ * audit-only and never participates in binding.
+ *
+ * F-02 (architecture gap remediation T2): consumption is bound to the
+ * immutable authority minted by commands/approve.mjs
+ * `approvePostPublishHook`:
+ *
+ *     <plan owning .release-skill>/approvals/postpublish/<planDigest>/<approvalDigest>.json
+ *
+ * `assertPostPublishApprovalAuthority` recomputes planDigest from the
+ * current plan and approvalDigest from the consumed raw bytes, requires the
+ * consumption path to EQUAL that authority path byte-for-byte (identical
+ * content anywhere else is not an approval), and strictly re-reads the file
+ * through Foundation `readFileStrict` (existence, containment against every
+ * root-escape class, no-follow regular-file identity, digest receipt bound
+ * to the recomputed approvalDigest). Symbolic-link semantics are fully
+ * delegated to Foundation: anything escaping the root is rejected, a leaf
+ * symbolic link is never an authority, and a root-internal ancestor alias
+ * is not an independent security failure (2026-08-21 handoff ruling C). The
+ * check is strictly read-only: it never creates a directory. After the
+ * authority passes, the existing schema/hook/grading/time-window validation
+ * continues unchanged.
+ *
+ * @module core/postpublish-approval
+ */
+
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+import { readFileStrict } from 'skill-family-harness-node';
+
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+import { computePlanDigest } from './plan.mjs';
+import { computeApprovalDigest, validateApprovalTimeWindow } from './approval.mjs';
+import { resolvePresetRequiresApproval } from './presets.mjs';
+import { readTrustedPackageResource } from './trusted-resource.mjs';
+
+const postpublishApprovalSchema = JSON.parse((await readTrustedPackageResource(
+  'schemas/postpublish-approval-record.schema.json',
+)).toString('utf8'));
+const postpublishApprovalAjv = new Ajv({ allErrors: true, strict: false });
+addFormats(postpublishApprovalAjv);
+const validatePostPublishApprovalSchema = postpublishApprovalAjv.compile(postpublishApprovalSchema);
+
+/**
+ * Schema-validate a postpublish checkpoint approval record.
+ *
+ * @param {object} approval
+ * @throws {ReleaseError} GATE_FAILED when the record violates the schema.
+ */
+export function validatePostPublishApprovalRecordSchema(approval) {
+  if (validatePostPublishApprovalSchema(approval)) return;
+  const errors = validatePostPublishApprovalSchema.errors ?? [];
+  throw new ReleaseError(
+    GATE_FAILED,
+    `postpublish approval record schema validation failed: ${errors.map((error) => `${error.instancePath || '/'}: ${error.message}`).join('; ')}`,
+    { validationErrors: errors },
+  );
+}
+
+/**
+ * Validate a checkpoint approval against the frozen plan.
+ *
+ * Bindings enforced (all fail-closed with GATE_FAILED):
+ * - record shape (postpublish-approval-record schema; additionalProperties
+ *   is false, so plan-level fields like approvedActions are rejected);
+ * - planDigest equals the computed plan digest;
+ * - hookId names a hook declared in the frozen plan's postPublish.hooks;
+ * - that hook actually declares requiresApproval: true;
+ * - the shared approval time window (24h max, 5-minute skew, unexpired).
+ *
+ * @param {object} plan - Frozen plan (schema-valid, digest verified by caller).
+ * @param {object} approval - Parsed postpublish approval record.
+ * @param {object} [options]
+ * @param {() => string} [options.clock] - Clock function returning ISO-8601.
+ * @param {boolean} [options.requireUnexpired] - Default true.
+ * @returns {object} The approved hook declaration.
+ * @throws {ReleaseError} GATE_FAILED on any violation.
+ */
+export function validatePostPublishApproval(plan, approval, options = {}) {
+  validatePostPublishApprovalRecordSchema(approval);
+
+  const actualDigest = computePlanDigest(plan);
+  if (approval.planDigest !== actualDigest) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postpublish approval planDigest mismatch: approval says ${String(approval.planDigest).slice(0, 16)}..., plan is ${actualDigest.slice(0, 16)}...`,
+      { approvalPlanDigest: approval.planDigest, planDigest: actualDigest },
+    );
+  }
+
+  const hooks = plan.postPublish?.hooks ?? [];
+  const hook = hooks.find((entry) => entry.id === approval.hookId);
+  if (!hook) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postpublish approval names hook "${approval.hookId}" which is not declared in the frozen plan`,
+      { hookId: approval.hookId, declaredHookIds: hooks.map((entry) => entry.id) },
+    );
+  }
+  // Effective requiresApproval (§2.6 grading): preset hooks may inherit the
+  // preset-declared default (proposal-inbox git-push -> true) without an
+  // explicit declaration; command hooks carry their declared value.
+  const effectiveRequiresApproval = hook.requiresApproval
+    ?? (hook.preset !== undefined ? resolvePresetRequiresApproval(hook.preset, hook.config) : false);
+  if (effectiveRequiresApproval !== true) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postpublish approval names hook "${approval.hookId}" which does not require approval (requiresApproval is not true)`,
+      { hookId: approval.hookId, requiresApproval: effectiveRequiresApproval ?? false },
+    );
+  }
+
+  validateApprovalTimeWindow(approval, {
+    clock: options.clock,
+    requireUnexpired: options.requireUnexpired,
+  });
+
+  return hook;
+}
+
+/**
+ * Derive the immutable checkpoint-approval authority location for a plan.
+ *
+ * This is the SINGLE source of truth for the authority layout, shared by the
+ * minter (commands/approve.mjs `approvePostPublishHook`) and the consumers
+ * (`assertPostPublishApprovalAuthority` below): the record lives at
+ *
+ *     <releaseDir>/approvals/postpublish/<planDigest>/<approvalDigest>.json
+ *
+ * where `releaseDir` is the directory owning the frozen plan — the
+ * `.release-skill` authority root when the plan uses the canonical
+ * `plans/<planDigest>.json` naming, otherwise the plan's own directory
+ * (non-production aliases), mirroring the minter exactly.
+ *
+ * @param {string} planPath - Absolute path of the frozen plan.
+ * @param {string} planDigest - Plan digest recomputed from the current plan.
+ * @param {string} approvalDigest - Digest recomputed from the approval bytes.
+ * @returns {{releaseDir: string, authorityPath: string}}
+ */
+export function derivePostPublishApprovalAuthorityPath(planPath, planDigest, approvalDigest) {
+  const absolutePlanPath = resolve(planPath);
+  const planDir = dirname(absolutePlanPath);
+  const releaseDir = basename(planDir) === 'plans' && basename(absolutePlanPath) === `${planDigest}.json`
+    ? dirname(planDir)
+    : planDir;
+  return {
+    releaseDir,
+    authorityPath: resolve(releaseDir, 'approvals', 'postpublish', planDigest, `${approvalDigest}.json`),
+  };
+}
+
+/**
+ * Assert that a checkpoint approval is consumed from its immutable authority.
+ *
+ * Fail-closed checks, in order (all GATE_FAILED):
+ * 1. `planDigest` is recomputed from the CURRENT plan;
+ * 2. `approvalDigest` is recomputed from the consumed raw approval bytes;
+ * 3. the consumption path must EQUAL the expected absolute authority path —
+ *    the same bytes copied anywhere else are never an approval;
+ * 4. Foundation `readFileStrict` re-reads the record through the authority
+ *    root: containment rejects every escape class (lexical traversal, a
+ *    final-component symlink pointing out, and any ancestor chain whose
+ *    canonical target leaves the root), the record must be one ordinary
+ *    file, never a symbolic link (no-follow, O_NOFOLLOW open, dev/ino
+ *    identity re-stat), and its bytes must digest to the recomputed
+ *    approvalDigest (binding the consumed bytes to the authoritative bytes).
+ *    A root-internal ancestor alias is a path alias, not an escape, and is
+ *    not an independent security failure (2026-08-21 handoff ruling C).
+ *
+ * The check is strictly read-only: it never creates a directory or file.
+ * Callers continue with `validatePostPublishApproval` (schema, hook,
+ * grading, time window) only after this assertion passes.
+ *
+ * @param {string} planPath - Absolute path of the frozen plan.
+ * @param {string} approvalPath - Path the consumer read the approval from.
+ * @param {object} plan - Parsed frozen plan (schema-valid).
+ * @param {string|Buffer} approvalRaw - Raw approval bytes the consumer read.
+ * @returns {Promise<{planDigest: string, approvalDigest: string, authorityPath: string}>}
+ * @throws {ReleaseError} GATE_FAILED on any violation.
+ */
+export async function assertPostPublishApprovalAuthority(planPath, approvalPath, plan, approvalRaw) {
+  if (!plan || typeof plan !== 'object') {
+    throw new ReleaseError(GATE_FAILED, 'postpublish approval authority check requires the parsed plan');
+  }
+  if (typeof approvalPath !== 'string' || approvalPath.length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'postpublish approval authority check requires a consumption path');
+  }
+
+  const planDigest = computePlanDigest(plan);
+  const approvalDigest = computeApprovalDigest(approvalRaw);
+  const { releaseDir, authorityPath } = derivePostPublishApprovalAuthorityPath(
+    planPath,
+    planDigest,
+    approvalDigest,
+  );
+
+  // Exact consumption-path equality: copying the bytes elsewhere never mints
+  // an approval. The comparison is lexical on resolve()d paths (no realpath
+  // normalization), so aliased spellings fail closed too.
+  const consumedPath = resolve(approvalPath);
+  if (consumedPath !== authorityPath) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postpublish checkpoint approval must be consumed from its immutable authority path; expected ${authorityPath}, got ${consumedPath}`,
+      { planDigest, approvalDigest, expectedAuthorityPath: authorityPath, consumedPath },
+    );
+  }
+
+  // Strict authority read through Foundation (FG-1 semantics, never local):
+  // containment (every root-escape class), no-follow leaf, regular-file
+  // identity, digest receipt. The expected digest binds the authoritative
+  // bytes to the consumed bytes.
+  const relPath = relative(releaseDir, authorityPath).split(sep).join('/');
+  try {
+    await readFileStrict(releaseDir, relPath, { expectedSha256: approvalDigest });
+  } catch (cause) {
+    if (cause instanceof ReleaseError) throw cause;
+    throw new ReleaseError(
+      GATE_FAILED,
+      `postpublish checkpoint approval authority read failed: ${cause?.message ?? cause}`,
+      { authorityPath, kind: cause?.details?.kind },
+    );
+  }
+
+  return Object.freeze({ planDigest, approvalDigest, authorityPath });
+}