release-skill 0.6.2 → 0.6.3

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,110 @@
+/**
+ * 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.
+ *
+ * @module core/postpublish-approval
+ */
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+import { computePlanDigest } from './plan.mjs';
+import { 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;
+}

package/src/core/postpublish.mjs

@@ -23,7 +23,12 @@
  * @module core/postpublish
  */
 
-import { ReleaseError, GATE_FAILED } from './errors.mjs';
+import { ReleaseError, GATE_FAILED, POSTPUBLISH_HOOK_INVALID } from './errors.mjs';
+import {
+  postPublishPresetNames,
+  validatePresetHook,
+  resolvePresetRequiresApproval,
+} from './presets.mjs';
 
 /** Secret-ish environment variable denylist (R3 credential hygiene). */
 export const ENV_ALLOWLIST_DENYLIST = /TOKEN|SECRET|PASSWORD|PASSPHRASE|API_KEY|CREDENTIAL/i;
@@ -178,6 +183,168 @@ function validateTarget(target, index) {
   }
 }
 
+function failHook(message, details = {}) {
+  throw new ReleaseError(POSTPUBLISH_HOOK_INVALID, `postPublish hook invalid: ${message}`, details);
+}
+
+/**
+ * Re-check the command-execution safety fields shared by materialize/steps
+ * and postPublish command hooks. Throws POSTPUBLISH_HOOK_INVALID (hooks) or
+ * GATE_FAILED (materialize/steps, via `fail`) depending on `failFn`.
+ */
+function validateCommandFields(where, hook, failFn) {
+  if (!Array.isArray(hook.command) || hook.command.length === 0) {
+    failFn(`${where}.command must be a non-empty array (shell strings are never accepted)`);
+  }
+  for (const element of hook.command) {
+    if (typeof element !== 'string' || element.length === 0) {
+      failFn(`${where}.command must contain only non-empty strings`);
+    }
+    if (/[\x00-\x1f\x7f]/.test(element)) {
+      failFn(`${where}.command contains control characters`, { element });
+    }
+    if (element.startsWith('-') && element === hook.command[0]) {
+      failFn(`${where}.command executable must not start with "-"`, { executable: element });
+    }
+  }
+  if (hook.cwd !== undefined) {
+    if (typeof hook.cwd !== 'string' || hook.cwd.length === 0) {
+      failFn(`${where}.cwd must be a non-empty string when provided`);
+    }
+    if (hook.cwd.startsWith('/') || hook.cwd.startsWith('./') || hook.cwd.includes('..')) {
+      failFn(`${where}.cwd must be a relative path inside the execution root`, { cwd: hook.cwd });
+    }
+  }
+  if (hook.timeoutMs !== undefined) {
+    if (!Number.isInteger(hook.timeoutMs) || hook.timeoutMs < 1000 || hook.timeoutMs > 7200000) {
+      failFn(`${where}.timeoutMs must be an integer in [1000, 7200000]`, { timeoutMs: hook.timeoutMs });
+    }
+  }
+  if (hook.envAllowlist !== undefined) {
+    if (!Array.isArray(hook.envAllowlist)) {
+      failFn(`${where}.envAllowlist must be an array`);
+    }
+    const seen = new Set();
+    for (const key of hook.envAllowlist) {
+      if (typeof key !== 'string' || !ENV_KEY_PATTERN.test(key)) {
+        failFn(`${where}.envAllowlist key ${JSON.stringify(key)} must be an uppercase [A-Z_][A-Z0-9_]* identifier`);
+      }
+      if (ENV_ALLOWLIST_DENYLIST.test(key)) {
+        failFn(
+          `${where}.envAllowlist key "${key}" matches the secret-ish denylist (TOKEN/SECRET/PASSWORD/PASSPHRASE/API_KEY/CREDENTIAL); distribute never reads or forwards credentials`,
+          { key },
+        );
+      }
+      if (seen.has(key)) {
+        failFn(`${where}.envAllowlist contains duplicate key "${key}"`);
+      }
+      seen.add(key);
+    }
+  }
+}
+
+/**
+ * Validate one postPublish hooks[] entry (v0.6.3 R1). Every violation throws
+ * POSTPUBLISH_HOOK_INVALID: the hooks layer is fail-closed and never repairs.
+ *
+ * Rules:
+ * - id mandatory, /^[a-z0-9][a-z0-9._-]*$/;
+ * - preset XOR command: exactly one must be declared;
+ * - preset references must exist in `knownPresets` (R2: defaults to the
+ *   built-in preset registry; an explicit empty list keeps the R1
+ *   fail-closed stance);
+ * - preset configs are validated by the registry (dual addressing,
+ *   marketplace/staticFiles shapes, secret scan) — POSTPUBLISH_HOOK_INVALID;
+ * - requiresApproval may tighten but never relax below the preset default;
+ * - command entries: executable+argument array safety (no shell strings);
+ * - phase: "distribute" (default) or "postVerify";
+ * - requiresApproval/blocksVerified booleans; blocksVerified: false is a
+ *   preset-only permission — custom command hooks can never weaken the
+ *   VERIFIED gate;
+ * - preset hooks must not declare command-hook execution fields
+ *   (cwd/timeoutMs/envAllowlist); command hooks must not declare config.
+ *
+ * @param {object} hook
+ * @param {number} index
+ * @param {object} options - { knownPresets: string[] }
+ */
+function validatePostPublishHookEntry(hook, index, options) {
+  const where = `hooks[${index}]`;
+  if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
+    failHook(`${where} must be a non-null object`);
+  }
+  if (typeof hook.id !== 'string' || !SAFE_ID_RE.test(hook.id)) {
+    failHook(`${where}.id must match /^[a-z0-9][a-z0-9._-]*$/`, { id: hook.id });
+  }
+
+  const hasPreset = hook.preset !== undefined;
+  const hasCommand = hook.command !== undefined;
+  if (hasPreset && hasCommand) {
+    failHook(`${where}: preset and command are mutually exclusive — declare exactly one`, { id: hook.id });
+  }
+  if (!hasPreset && !hasCommand) {
+    failHook(`${where}: declare exactly one of preset or command`, { id: hook.id });
+  }
+
+  if (hook.phase !== undefined && hook.phase !== 'distribute' && hook.phase !== 'postVerify') {
+    failHook(`${where}.phase must be "distribute" or "postVerify"`, { phase: hook.phase });
+  }
+  if (hook.requiresApproval !== undefined && typeof hook.requiresApproval !== 'boolean') {
+    failHook(`${where}.requiresApproval must be a boolean`, { requiresApproval: hook.requiresApproval });
+  }
+  if (hook.blocksVerified !== undefined && typeof hook.blocksVerified !== 'boolean') {
+    failHook(`${where}.blocksVerified must be a boolean`, { blocksVerified: hook.blocksVerified });
+  }
+
+  if (hasPreset) {
+    if (typeof hook.preset !== 'string' || !SAFE_ID_RE.test(hook.preset)) {
+      failHook(`${where}.preset must match /^[a-z0-9][a-z0-9._-]*$/`, { preset: hook.preset });
+    }
+    // R2: the built-in preset registry is the default authority; callers may
+    // still override with an explicit list (an empty list keeps the R1
+    // fail-closed stance where every preset reference is rejected).
+    const knownPresets = options.knownPresets ?? postPublishPresetNames();
+    if (!knownPresets.includes(hook.preset)) {
+      failHook(
+        `${where}: unknown preset "${hook.preset}" — the preset registry does not contain it (fail-closed)`,
+        { preset: hook.preset, knownPresets },
+      );
+    }
+    if (hook.config !== undefined && (typeof hook.config !== 'object' || Array.isArray(hook.config) || hook.config === null)) {
+      failHook(`${where}.config must be a plain object when provided`, { id: hook.id });
+    }
+    for (const field of ['cwd', 'timeoutMs', 'envAllowlist']) {
+      if (hook[field] !== undefined) {
+        failHook(`${where}: preset hooks must not declare command-hook execution field "${field}"`, { field });
+      }
+    }
+    // Registry-driven config validation (dual addressing, marketplace block,
+    // staticFiles, secret scan) — fail-closed per preset (R2, §2.5/§2.6).
+    validatePresetHook(hook, where);
+    // requiresApproval grading (§2.6): projects may tighten (explicit true)
+    // but never relax below the preset-declared default.
+    const presetDefault = resolvePresetRequiresApproval(hook.preset, hook.config);
+    if (hook.requiresApproval === false && presetDefault === true) {
+      failHook(
+        `${where}: requiresApproval cannot be relaxed below the preset default (preset "${hook.preset}" defaults to true; declare true to tighten, never false to relax)`,
+        { preset: hook.preset, presetDefault },
+      );
+    }
+  } else {
+    // Custom command hook.
+    validateCommandFields(where, hook, failHook);
+    if (hook.blocksVerified === false) {
+      failHook(
+        `${where}: custom command hooks must not declare blocksVerified: false — only presets may weaken the VERIFIED gate`,
+        { id: hook.id },
+      );
+    }
+    if (hook.config !== undefined) {
+      failHook(`${where}: config is a preset-only field`, { id: hook.id });
+    }
+  }
+}
+
 /**
  * Validate a per-unit postPublish declaration.
  *
@@ -185,8 +352,13 @@ function validateTarget(target, index) {
  *   the caller's config layer; this function is the runtime re-check).
  * @param {object} [options]
  * @param {string} [options.unitId] - Unit id for error context.
+ * @param {string[]} [options.knownPresets] - Preset names accepted as known.
+ *   Defaults to the built-in R2 preset registry (core/presets.mjs); an
+ *   explicit empty list restores the R1 fail-closed stance where every
+ *   preset reference is rejected.
  * @returns {object} The validated declaration (unmodified).
- * @throws {ReleaseError} GATE_FAILED on any violation (fail-closed).
+ * @throws {ReleaseError} GATE_FAILED on declaration violations;
+ *   POSTPUBLISH_HOOK_INVALID on hooks[] violations (fail-closed).
  */
 export function validatePostPublishDeclaration(postPublish, options = {}) {
   const unitLabel = options.unitId ? `unit "${options.unitId}" ` : '';
@@ -210,11 +382,16 @@ export function validatePostPublishDeclaration(postPublish, options = {}) {
     }
   }
 
-  if (!Array.isArray(postPublish.targets) || postPublish.targets.length === 0) {
-    fail(`${unitLabel}targets must be a non-empty array`);
+  // targets: optional since v0.6.3 R1 (hooks-only declarations are legal).
+  // An explicitly empty array still fails closed (semantic lock: a present
+  // targets array must declare at least one target).
+  const targets = postPublish.targets ?? [];
+  if (postPublish.targets !== undefined
+    && (!Array.isArray(postPublish.targets) || postPublish.targets.length === 0)) {
+    fail(`${unitLabel}targets must be a non-empty array when present; omit it entirely for a hooks-only declaration`);
   }
   const ids = new Set();
-  postPublish.targets.forEach((target, index) => {
+  targets.forEach((target, index) => {
     validateTarget(target, index);
     if (ids.has(target.id)) {
       fail(`${unitLabel}duplicate target id "${target.id}"`);
@@ -223,8 +400,8 @@ export function validatePostPublishDeclaration(postPublish, options = {}) {
   });
 
   // dependsOn references must exist and point at payload-mirror targets.
-  const byId = new Map(postPublish.targets.map((target) => [target.id, target]));
-  for (const target of postPublish.targets) {
+  const byId = new Map(targets.map((target) => [target.id, target]));
+  for (const target of targets) {
     if (target.dependsOn === undefined) continue;
     const dependency = byId.get(target.dependsOn);
     if (!dependency) {
@@ -235,6 +412,27 @@ export function validatePostPublishDeclaration(postPublish, options = {}) {
     }
   }
 
+  // hooks (v0.6.3 R1): per-entry fail-closed validation + unique ids across
+  // the normalized target/hook table.
+  if (postPublish.hooks !== undefined) {
+    if (!Array.isArray(postPublish.hooks)) {
+      failHook(`${unitLabel}hooks must be an array`);
+    }
+    postPublish.hooks.forEach((hook, index) => {
+      validatePostPublishHookEntry(hook, index, options);
+    });
+    const hookIds = new Set();
+    for (const hook of postPublish.hooks) {
+      if (hookIds.has(hook.id)) {
+        failHook(`${unitLabel}duplicate hook id "${hook.id}"`);
+      }
+      hookIds.add(hook.id);
+      if (ids.has(hook.id)) {
+        failHook(`${unitLabel}hook id "${hook.id}" conflicts with target id "${hook.id}"; normalized table ids must be unique`);
+      }
+    }
+  }
+
   // commitIdentity is mandatory whenever targets exist (always, here).
   const identity = postPublish.commitIdentity;
   if (!identity || typeof identity !== 'object' || Array.isArray(identity)) {
@@ -313,3 +511,222 @@ export function orderTargetsByDependency(targets) {
   }
   return ordered;
 }
+
+// ---------------------------------------------------------------------------
+// Hook normalization + context contract (v0.6.3 R1, design §2.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Environment variable carrying the read-only postPublish hook context.
+ * The JSON projection is injected into the hook process environment AFTER
+ * envAllowlist filtering (core/hooks.mjs injectEnv), so declarations can
+ * neither opt out of it nor smuggle it through their allowlist.
+ */
+export const POSTPUBLISH_CONTEXT_ENV = 'RELEASE_SKILL_POSTPUBLISH_CONTEXT';
+
+/**
+ * Normalize one declared postPublish hook entry: apply the governance
+ * defaults (phase distribute, blocksVerified true, requiresApproval false)
+ * and tag the entry kind. Pure function; the declaration is not mutated.
+ * This normalized shape is the digest-bound display surface shown at
+ * checkpoint approval time (review N-6).
+ *
+ * @param {object} hook - Declared hook entry (validate first for safety).
+ * @returns {object} Normalized entry: { id, kind, phase, blocksVerified,
+ *   requiresApproval, + kind-specific fields (command/cwd/timeoutMs/
+ *   envAllowlist or preset/config) }.
+ */
+export function normalizePostPublishHook(hook) {
+  const kind = hook.preset !== undefined ? 'preset' : 'command';
+  // requiresApproval grading (§2.6): command hooks default false; preset
+  // hooks inherit the preset-declared default (public-write presets true,
+  // notify-handoff / proposal-inbox local-file false; validation forbids
+  // relaxing below the default, so this resolution can only ever confirm or
+  // tighten).
+  const defaultRequiresApproval = kind === 'preset'
+    ? resolvePresetRequiresApproval(hook.preset, hook.config)
+    : false;
+  const normalized = {
+    id: hook.id,
+    kind,
+    ...(kind === 'preset' ? { preset: hook.preset } : { command: [...hook.command] }),
+    phase: hook.phase ?? 'distribute',
+    ...(hook.config !== undefined ? { config: hook.config } : {}),
+    ...(kind === 'command' && hook.cwd !== undefined ? { cwd: hook.cwd } : {}),
+    ...(hook.timeoutMs !== undefined ? { timeoutMs: hook.timeoutMs } : {}),
+    ...(hook.envAllowlist !== undefined ? { envAllowlist: [...hook.envAllowlist] } : {}),
+    requiresApproval: hook.requiresApproval ?? defaultRequiresApproval,
+    blocksVerified: hook.blocksVerified ?? true,
+  };
+  return normalized;
+}
+
+/**
+ * Effective requiresApproval (§2.6 grading) for one declared hook: command
+ * hooks carry their declared value; preset hooks inherit the preset-declared
+ * default (public-write presets true; proposal-inbox graded by transport;
+ * notify-handoff / local-file false) unless explicitly tightened. Single
+ * authority shared by distribute, postverify, and the ship re-entry gate.
+ *
+ * @param {object} hook - Declared hook entry.
+ * @returns {boolean}
+ */
+export function effectiveHookRequiresApproval(hook) {
+  if (hook.requiresApproval !== undefined) return hook.requiresApproval === true;
+  if (hook.preset !== undefined) return resolvePresetRequiresApproval(hook.preset, hook.config) === true;
+  return false;
+}
+
+/**
+ * Build the read-only context projection injected into postPublish hooks
+ * (design §2.3). Every field comes from the frozen plan or the sealed source
+ * run — never from the live workspace.
+ *
+ * Phase distinction: `verifyEvidence` is carried ONLY for postVerify-phase
+ * hooks; for the distribute phase the key is ABSENT (not null), so hooks can
+ * distinguish the phases without trusting a mutable value.
+ *
+ * @param {object} args
+ * @param {object} args.plan - Frozen plan (digest + units + postPublish).
+ * @param {string} args.runId - Current distribute run id.
+ * @param {object} args.sourceRun - Sealed source run (finishedAt = publishedAt).
+ * @param {string} args.payloadDir - Materialized payload directory.
+ * @param {'distribute'|'postVerify'} args.phase
+ * @param {object} [args.verifyEvidence] - Verify evidence (postVerify phase).
+ * @returns {object} The context projection.
+ */
+export function buildPostPublishContext({ plan, runId, sourceRun, payloadDir, phase, verifyEvidence }) {
+  const postPublish = plan.postPublish ?? {};
+  const unit = (plan.units ?? []).find((entry) => entry.id === postPublish.unitId);
+  const frozenSnapshot = unit?.frozenSnapshot ?? {};
+  return {
+    planDigest: plan.digest,
+    runId,
+    unitId: postPublish.unitId,
+    version: unit?.targetVersion,
+    tag: postPublish.tag,
+    commit: postPublish.tagCommit,
+    ...(frozenSnapshot.tree !== undefined ? { tree: frozenSnapshot.tree } : {}),
+    ...(frozenSnapshot.manifestDigest !== undefined ? { manifestDigest: frozenSnapshot.manifestDigest } : {}),
+    publishedAt: sourceRun?.finishedAt,
+    payloadDir,
+    ...(phase === 'postVerify' && verifyEvidence !== undefined ? { verifyEvidence } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Targets normalization (v0.6.3 R2, design §2.2)
+// ---------------------------------------------------------------------------
+
+/** Legacy target kind -> absorbing preset (design §2.5). */
+const TARGET_KIND_PRESET = {
+  'payload-mirror': 'git-mirror',
+  'marketplace-index': 'marketplace-index-render',
+};
+
+/**
+ * Normalize one legacy targets[] entry into a preset hook entry. Field-level
+ * mapping (review N-B2): remoteUrl/branch -> config.target; visibility ->
+ * config.visibility (public-write/internal-write semantics preserved);
+ * staticFiles -> config.staticFiles; marketplace -> config.marketplace;
+ * dependsOn -> hook-level dependency (runtime validates existence + acyclicity,
+ * semantics unchanged).
+ *
+ * @param {object} target - Validated postPublish target entry.
+ * @returns {object} Normalized preset hook entry.
+ */
+function normalizeTargetToPresetHook(target) {
+  const preset = TARGET_KIND_PRESET[target.kind];
+  return {
+    id: target.id,
+    kind: 'preset',
+    preset,
+    origin: 'target',
+    originKind: target.kind,
+    phase: 'distribute',
+    config: {
+      target: { remoteUrl: target.remoteUrl, branch: target.branch },
+      visibility: target.visibility,
+      ...(target.staticFiles !== undefined
+        ? { staticFiles: target.staticFiles.map((file) => ({ from: file.from, to: file.to })) }
+        : {}),
+      ...(target.marketplace !== undefined
+        ? { marketplace: structuredClone(target.marketplace) }
+        : {}),
+    },
+    ...(target.dependsOn !== undefined ? { dependsOn: target.dependsOn } : {}),
+    requiresApproval: resolvePresetRequiresApproval(preset, {}),
+    blocksVerified: true,
+  };
+}
+
+/**
+ * Normalize a validated postPublish declaration into the unified hook table
+ * (design §2.2). Pure and deterministic: the table is a projection of the
+ * digest-bound declaration, so any targets/hooks list change changes the plan
+ * digest and invalidates existing approvals.
+ *
+ * Shape:
+ * - `preGates`: section-level gates injected ahead of all git-write hooks —
+ *   assertMainVersionAhead:true becomes `assert-main-version-ahead` (current
+ *   distribute semantics preserved);
+ * - `defaults`: section-level defaults injected into the relevant presets —
+ *   materialize / steps / commitIdentity;
+ * - `hooks`: target-derived preset hooks first (declaration order), then the
+ *   declared hooks[] entries normalized via normalizePostPublishHook.
+ *
+ * Validate the declaration BEFORE calling this (id conflicts, dependency
+ * references, and preset semantics are fail-closed there, not here).
+ *
+ * @param {object} postPublish - Validated postPublish declaration.
+ * @returns {{ preGates: object[], defaults: object, hooks: object[] }}
+ */
+export function normalizePostPublishDeclaration(postPublish) {
+  const preGates = postPublish.assertMainVersionAhead === true
+    ? [{ gate: 'assert-main-version-ahead', before: 'git-write-hooks' }]
+    : [];
+  const defaults = {
+    materialize: structuredClone(postPublish.materialize),
+    steps: structuredClone(postPublish.steps ?? []),
+    commitIdentity: structuredClone(postPublish.commitIdentity),
+  };
+  const targetHooks = (postPublish.targets ?? []).map((target) => normalizeTargetToPresetHook(target));
+  const declaredHooks = (postPublish.hooks ?? []).map((hook) => normalizePostPublishHook(hook));
+  return { preGates, defaults, hooks: [...targetHooks, ...declaredHooks] };
+}
+
+/**
+ * Order the normalized hook table so every hook runs after its dependsOn
+ * hook, preserving declaration order among ready entries (dependency
+ * topology + declaration order). Dangling references and cycles fail closed
+ * with GATE_FAILED — references are also validated at declaration time; this
+ * guard keeps ordering independently safe.
+ *
+ * @param {object[]} hooks - Normalized hook table.
+ * @returns {object[]} Hooks in execution order.
+ */
+export function orderNormalizedHooks(hooks) {
+  const byId = new Map(hooks.map((hook) => [hook.id, hook]));
+  const ordered = [];
+  const placed = new Set();
+  while (ordered.length < hooks.length) {
+    let progress = false;
+    for (const hook of hooks) {
+      if (placed.has(hook.id)) continue;
+      if (hook.dependsOn !== undefined) {
+        if (!byId.has(hook.dependsOn)) {
+          fail(`hook "${hook.id}" dependsOn unknown hook "${hook.dependsOn}"`);
+        }
+        if (!placed.has(hook.dependsOn)) continue;
+      }
+      ordered.push(hook);
+      placed.add(hook.id);
+      progress = true;
+    }
+    if (!progress) {
+      const pending = hooks.filter((hook) => !placed.has(hook.id)).map((hook) => hook.id);
+      fail(`postPublish hook dependency cycle detected among: ${pending.join(', ')}`);
+    }
+  }
+  return ordered;
+}