release-skill 0.8.0 → 0.9.0

package/src/commands/verify.mjs

@@ -23,6 +23,7 @@ import { resolveContained } from 'skill-family-harness-node';
 const execFile = promisify(execFileCb);
 
 import { validatePlan, computePlanDigest, validatePlanActionCompleteness } from '../core/plan.mjs';
+import { normalizePostPublishView, postPublishActionId } from '../core/postpublish.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { readRunRecovery } from '../core/recovery.mjs';
 import {
@@ -62,6 +63,10 @@ import {
 import { loadProjectConfig } from '../core/config.mjs';
 import { assertTransition, PUBLISHED, VERIFIED } from '../core/state-machine.mjs';
 import { clearFrozenMarker } from '../core/frozen-marker.mjs';
+import {
+  isFoundationPluginVerificationEligible,
+  verifyFrozenPluginWithFoundation,
+} from '../core/foundation-plugin-verification.mjs';
 import { resolveUnitScopedPath } from '../snapshot/public-path.mjs';
 import {
   normalizeRegistry,
@@ -884,7 +889,7 @@ async function discoverDistributeRuns({ planPath, plan }) {
  *   governance rule that NEEDS_INPUT/BLOCKED cannot silently become VERIFIED.
  *
  * @param {Object} run - A distribute run record (checkpoints + status).
- * @param {Object} plan - The frozen release plan (postPublish.hooks source).
+ * @param {Object} plan - The frozen release plan (normalized postPublish declaration source).
  * @returns {{ pass: boolean, warned: boolean, exemptions: Object[] }}
  */
 export function evaluateDistributeGateRun(run, plan) {
@@ -892,12 +897,19 @@ export function evaluateDistributeGateRun(run, plan) {
   if (run.status === 'DISTRIBUTED') return { pass: true, warned: false, exemptions: [] };
   if (run.status !== 'PARTIAL') return { pass: false, warned: false, exemptions: [] };
 
-  const hooksById = new Map(((plan?.postPublish?.hooks ?? [])).map((hook) => [hook.id, hook]));
+  // §4.3 unified normalization: hooks resolve across all declarations and
+  // are keyed by the SAME action-id derivation the distribute run used, so
+  // v3 namespaced checkpoint ids (unitId/hookId) map back to their hook.
+  const hooksByActionId = new Map((plan ? normalizePostPublishView(plan) : [])
+    .flatMap((declaration) => (declaration.hooks ?? []).map((hook) => [
+      postPublishActionId({ planVersion: plan?.planVersion, unitId: declaration.unitId, localId: hook.id }),
+      hook,
+    ])));
   const exemptions = [];
   for (const checkpoint of run.checkpoints ?? []) {
     if (checkpoint.status === 'succeeded' || checkpoint.status === 'skipped') continue;
     const hook = checkpoint.actionType === 'postpublish-hook'
-      ? hooksById.get(checkpoint.actionId)
+      ? hooksByActionId.get(checkpoint.actionId)
       : undefined;
     if (hook && checkpoint.status === 'failed' && hook.blocksVerified === false) {
       exemptions.push({ actionId: checkpoint.actionId, status: checkpoint.status });
@@ -925,7 +937,7 @@ export function evaluateDistributeGateRun(run, plan) {
  * @param {() => string} [options.clock] - Clock function returning ISO-8601 strings.
  * @param {Object} [options.previousVerifyRun] - 上一次验证成功的 verify run 记录，用于安装契约摘要免验。
  *
- * @returns {Promise<{ planPath: string, status: string, adapterChecks: Object[], smokeTest: Object }>}
+ * @returns {Promise<{ planPath: string, runPath: string, status: string, adapterChecks: Object[], smokeTest: Object }>}
  *
  * @throws {ReleaseError} GATE_FAILED on safety gate failures.
  * @throws {ReleaseError} POST_PUBLISH_VERIFY_FAILED if any verification fails.
@@ -944,6 +956,7 @@ export async function verifyRelease(options) {
     previousVerifyRun,
     execFn,
     configPath: configPathOpt,
+    runPluginVerificationFn,
   } = options ?? {};
 
   const clockFn = typeof clockOpt === 'function' ? clockOpt : defaultClock;
@@ -1063,10 +1076,12 @@ export async function verifyRelease(options) {
     // PARTIAL distribute run passes only through the blocksVerified:false
     // exemption path (evaluateDistributeGateRun) — warned, never silent.
     // =======================================================================
-    const declaredPostPublishTargets = plan.postPublish?.targets ?? [];
-    const declaredPostPublishHooks = plan.postPublish?.hooks ?? [];
-    if (plan.postPublish
-      && (declaredPostPublishTargets.length > 0 || declaredPostPublishHooks.length > 0)) {
+    // §4.3 unified normalization: v3 empty arrays mean no distribution
+    // requirement; legacy absent postPublish resolves to the same empty view.
+    const postPublishDeclarations = normalizePostPublishView(plan);
+    const requiresDistribution = postPublishDeclarations.some((declaration) =>
+      (declaration.targets?.length ?? 0) > 0 || (declaration.hooks?.length ?? 0) > 0);
+    if (requiresDistribution) {
       await evidence.append({ phase: 'verify', step: 'distribute-run-discovery', status: 'started' });
 
       const distributeCandidates = await discoverDistributeRuns({ planPath, plan }) ?? [];
@@ -1351,10 +1366,15 @@ export async function verifyRelease(options) {
       }
     }
 
-    // When the plan declares humanConsumersStrategy: 'manualFollowUps',
-    // Kimi/CodeBuddy installations are non-blocking post-release manual tasks.
-    // Skip attestation collection and blocking for these platforms.
-    const isHumanConsumerFollowUp = plan.humanConsumersStrategy === 'manualFollowUps';
+    // Kimi/CodeBuddy remain non-blocking post-release manual tasks. New plans
+    // additionally require a Foundation observation of the complete frozen
+    // payload before the manual marketplace/invocation follow-up is emitted.
+    const isHumanConsumerFollowUp = [
+      'manualFollowUps',
+      'foundationPayloadThenManualFollowUps',
+    ].includes(plan.humanConsumersStrategy);
+    const requiresFoundationPayloadObservation = plan.humanConsumersStrategy
+      === 'foundationPayloadThenManualFollowUps';
 
     const missingManualAttestations = isHumanConsumerFollowUp
       ? []
@@ -1382,6 +1402,7 @@ export async function verifyRelease(options) {
 
     // Collect non-blocking manual follow-up tasks for human consumer platforms
     const manualFollowUps = [];
+    const foundationPluginVerificationReceipts = [];
 
     // Every action is identity-bound and adapters receive read-only or
     // per-action isolated consumer paths. Run independent checks concurrently;
@@ -1414,13 +1435,40 @@ export async function verifyRelease(options) {
       }
 
       if (isMarketplaceAction(action.type)) {
-        // When humanConsumersStrategy is 'manualFollowUps', Kimi/CodeBuddy
-        // installations are non-blocking manual follow-up tasks. Skip adapter
-        // processing and collect them as manualFollowUps.
+        // Both human-consumer strategies keep marketplace installation and
+        // invocation as non-blocking manual follow-ups. The new strategy first
+        // requires Foundation to observe the identity-bound frozen payload.
         const isHumanConsumerPlatform = action.type === 'kimi-marketplace-install'
           || action.type === 'codebuddy-marketplace-install';
         if (isHumanConsumerFollowUp && isHumanConsumerPlatform) {
           const platform = action.type === 'kimi-marketplace-install' ? 'kimi' : 'codebuddy';
+          const observesFoundationPayload = requiresFoundationPayloadObservation
+            && isFoundationPluginVerificationEligible({ action, units: plan.units });
+          if (observesFoundationPayload) {
+            const actionRunDir = join(runDir, 'foundation-plugin-verification', action.id);
+            await mkdir(join(actionRunDir, 'install'), { recursive: true, mode: 0o700 });
+            await mkdir(join(actionRunDir, 'temporary'), { recursive: true, mode: 0o700 });
+            await mkdir(join(actionRunDir, 'evidence'), { recursive: true, mode: 0o700 });
+            const receipt = await verifyFrozenPluginWithFoundation({
+              plan,
+              action,
+              root,
+              runDir: actionRunDir,
+              ...(runPluginVerificationFn ? { runPluginVerificationFn } : {}),
+              clock: clockFn,
+            });
+            foundationPluginVerificationReceipts.push(receipt);
+            await evidence.append({
+              phase: 'verify-marketplace',
+              actionId: action.id,
+              actionType: action.type,
+              status: 'FOUNDATION_PAYLOAD_OBSERVED',
+              requestDigest: receipt.requestDigest,
+              hostId: receipt.hostId,
+              payloadMatches: receipt.payloadMatches,
+              observationDigest: receipt.observationDigest,
+            });
+          }
           manualFollowUps.push({
             actionId: action.id,
             platform,
@@ -1428,20 +1476,26 @@ export async function verifyRelease(options) {
             version: action.parameters?.version,
             unitId: action.unitId,
             verifiedBySystem: false,
-            reason: 'human consumer platform — installation is a manual post-release task; not verified by system',
+            reason: observesFoundationPayload
+              ? 'complete frozen payload observed by Foundation; marketplace installation and host invocation remain manual'
+              : 'human consumer platform — installation is a manual post-release task; not verified by system',
           });
           adapterChecks.push({
             actionId: action.id,
             actionType: action.type,
             status: 'SKIPPED',
-            reason: 'manual-follow-up',
+            reason: observesFoundationPayload
+              ? 'foundation-payload-observed-manual-follow-up'
+              : 'manual-follow-up',
           });
           await evidence.append({
             phase: 'verify-marketplace',
             actionId: action.id,
             actionType: action.type,
             status: 'SKIPPED',
-            reason: 'manual-follow-up',
+            reason: observesFoundationPayload
+              ? 'foundation-payload-observed-manual-follow-up'
+              : 'manual-follow-up',
           });
           return;
         }
@@ -1727,6 +1781,8 @@ export async function verifyRelease(options) {
     }));
     adapterChecks.sort((a, b) => a.actionId.localeCompare(b.actionId));
     consumerVerificationReceipts.sort((a, b) => a.actionId.localeCompare(b.actionId));
+    foundationPluginVerificationReceipts.sort((a, b) => a.actionId.localeCompare(b.actionId));
+    manualFollowUps.sort((a, b) => a.actionId.localeCompare(b.actionId));
     consumerGateResults.sort((a, b) => a.id.localeCompare(b.id));
     const rejectedAction = actionResults.find((result) => result.status === 'rejected');
     if (rejectedAction) throw rejectedAction.reason;
@@ -2034,6 +2090,9 @@ export async function verifyRelease(options) {
       gateResults: consumerGateResults,
       consumerVerificationReceipts,
       skillResourceClosureReceipts,
+      ...(foundationPluginVerificationReceipts.length > 0
+        ? { foundationPluginVerificationReceipts }
+        : {}),
       ...(manualFollowUps.length > 0 ? { manualFollowUps } : {}),
       startedAt: clockFn(),
       finishedAt: clockFn(),
@@ -2127,11 +2186,15 @@ export async function verifyRelease(options) {
 
     return {
       planPath,
+      runPath: verifyRunPath,
       status: VERIFIED,
       adapterChecks,
       recoveryActionCode: null,
       smokeTest,
       gateResults: consumerGateResults,
+      ...(foundationPluginVerificationReceipts.length > 0
+        ? { foundationPluginVerificationReceipts }
+        : {}),
       ...(manualFollowUps.length > 0 ? { manualFollowUps } : {}),
       ...(baselineAdvance ? { baselineAdvance } : {}),
     };

package/src/core/adoption-assessment.mjs

@@ -40,9 +40,6 @@
 import { canonicalJson, sha256Hex } from './digest.mjs';
 import { resolveProducerVersion } from './evidence.mjs';
 
-// Keep the assessment entry point compatible without duplicating the rule.
-export { findPostPublishUnitConflict } from './hooks.mjs';
-
 /** Four adoption statuses; never reuses ASSESSED (design §3.2). */
 export const ASSESSMENT_STATUS = Object.freeze({
   NOT_CONFIGURED: 'NOT_CONFIGURED',

package/src/core/approval.mjs

@@ -12,7 +12,8 @@
  * - approvedAt is not in the future (beyond 5-minute clock skew tolerance)
  *
  * The planVersion fork (design: t1-2-digest-decoupling.md §4.3) is
- * centralized here: for planVersion 2 plans the baseline is record-layer
+ * centralized here: for planVersion 2/3 plans (v3 inherits the v2 approval
+ * boundary per 多发布单元 postPublish v3 §4.2) the baseline is record-layer
  * data -- gitTreeHash/workspaceDigest equality and the production workspace
  * digest algorithm double-check are NOT invalidation conditions (artifact
  * integrity is sealed by the frozen-artifact re-verification at publish).
@@ -186,11 +187,13 @@ export function validateApproval(plan, approval, options = {}) {
     );
   }
 
-  // planVersion fork (centralized here; see module header): v2 plans treat
-  // the baseline as optional record-layer data.
-  const planV2 = plan?.planVersion === 2;
+  // planVersion fork (centralized here; see module header): planVersion 2/3
+  // plans treat the baseline as optional record-layer data (v3 inherits the
+  // v2 approval boundary per 多发布单元 postPublish v3 §4.2). Versions beyond
+  // {2,3} stay on the legacy v1 path and are never silently admitted.
+  const recordLayerBaseline = plan?.planVersion === 2 || plan?.planVersion === 3;
 
-  if (planV2) {
+  if (recordLayerBaseline) {
     if (!approval.planDigest || !approval.expiresAt) {
       throw new ReleaseError(
         GATE_FAILED,
@@ -206,7 +209,7 @@ export function validateApproval(plan, approval, options = {}) {
     );
   }
 
-  if (!planV2) {
+  if (!recordLayerBaseline) {
     if (plan.production?.mode === 'github-npm-v1') {
       if (plan.baseline?.workspaceDigestAlgorithm !== WORKSPACE_DIGEST_ALGORITHM) {
         throw new ReleaseError(
@@ -249,9 +252,9 @@ export function validateApproval(plan, approval, options = {}) {
   }
 
   // --- baseline equality checks (v1 plans only) ---
-  // For planVersion 2 plans the baseline is record-layer data: it stays in
+  // For planVersion 2/3 plans the baseline is record-layer data: it stays in
   // the plan/approval files for audit but is not an invalidation condition.
-  if (!planV2) {
+  if (!recordLayerBaseline) {
     // --- baseline.gitTreeHash match ---
     if (approval.baseline.gitTreeHash !== plan.baseline?.gitTreeHash) {
       throw new ReleaseError(

package/src/core/foundation-plugin-verification.mjs

@@ -0,0 +1,247 @@
+/**
+ * Release-domain thin adapter for Foundation 0.13 complete-plugin observation.
+ *
+ * The frozen snapshot remains the only payload authority. This module derives
+ * transient Foundation inputs from that tree, calls the released Kit API, and
+ * returns only the fields needed to bind the mechanism observation to a
+ * release action. It does not prove a marketplace install or host invocation.
+ *
+ * @module core/foundation-plugin-verification
+ */
+
+import { join } from 'node:path';
+
+import { digestDocument } from 'skill-family-contracts';
+import {
+  bundledHostProfilesRoot,
+  describeHost,
+  runPluginVerification,
+} from 'skill-family-engineering-kit';
+import {
+  createFilesystemRootBinding,
+  readFileBound,
+} from 'skill-family-harness-node';
+
+import { getPlatform, normalizeHostId } from '../platforms/registry.mjs';
+import { verifyFrozenSnapshot } from '../snapshot/frozen.mjs';
+import { ReleaseError, POST_PUBLISH_VERIFY_FAILED } from './errors.mjs';
+
+// Foundation's public plugin-verification request freezes the built-in driver
+// contract at 1.0.0. The real API integration test intentionally exercises
+// this value so an upstream contract change fails closed during adoption.
+const FOUNDATION_PLUGIN_DRIVER_VERSION = '1.0.0';
+
+function fail(message, details = {}) {
+  return new ReleaseError(POST_PUBLISH_VERIFY_FAILED, message, details);
+}
+
+function projectSourceMembers(entries) {
+  const directories = new Set();
+  for (const entry of entries) {
+    const parts = entry.path.split('/');
+    for (let count = 1; count < parts.length; count += 1) {
+      directories.add(parts.slice(0, count).join('/'));
+    }
+  }
+  return [
+    ...[...directories].map((path) => ({ path, type: 'directory' })),
+    ...entries.map((entry) => ({
+      path: entry.path,
+      type: 'file',
+      sha256: entry.contentDigest,
+      bytes: entry.size,
+      executable: (entry.mode & 0o111) !== 0,
+    })),
+  ].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+}
+
+/**
+ * Return whether one human-consumer action has the complete frozen identity
+ * required by Foundation's local-staged plugin verification.
+ *
+ * This predicate is deliberately plan-derived. It does not persist a second
+ * action list, and the verifier repeats the same checks before every call.
+ */
+export function isFoundationPluginVerificationEligible({ action, units = [] } = {}) {
+  const platformId = action?.parameters?.consumer;
+  const expectedType = platformId === 'kimi'
+    ? 'kimi-marketplace-install'
+    : platformId === 'codebuddy'
+      ? 'codebuddy-marketplace-install'
+      : null;
+  if (!expectedType || action?.type !== expectedType) return false;
+
+  const unit = units.find((candidate) => candidate.id === action.unitId);
+  const snapshot = unit?.frozenSnapshot;
+  const sourceDescriptor = action.parameters?.sourceDescriptor;
+  if (
+    !snapshot?.path
+    || !snapshot.commit
+    || !snapshot.manifestDigest
+    || sourceDescriptor?.form !== 'bundled-family'
+    || sourceDescriptor.pluginSubpath !== '.'
+    || sourceDescriptor.commit !== snapshot.commit
+    || sourceDescriptor.payloadDigest !== snapshot.manifestDigest
+    || action.parameters?.sourceCommit !== snapshot.commit
+    || action.parameters?.snapshotPath !== snapshot.path
+    || action.parameters?.manifestDigest !== snapshot.manifestDigest
+  ) return false;
+
+  const platform = getPlatform(platformId);
+  return (unit.distributions ?? []).some((distribution) => (
+    distribution.type === platform.distributionType
+    && typeof distribution.installationContract?.manifestRelativePath === 'string'
+    && distribution.installationContract.manifestRelativePath.length > 0
+  ));
+}
+
+function assertResultMatchesRequest(result, request) {
+  if (
+    result?.status !== 'observed'
+    || result.requestDigest !== digestDocument(request)
+    || result.goal !== request.goal
+    || digestDocument(result.source) !== digestDocument(request.source)
+    || digestDocument(result.host) !== digestDocument(request.host)
+    || result.facts?.install?.payloadMatches !== true
+    || result.facts.install.sourceMode !== 'local-staged'
+    || result.facts.install.retained !== true
+    || result.facts.invocation !== null
+  ) {
+    throw fail('Foundation complete-plugin observation did not satisfy the frozen local payload contract', {
+      foundationStatus: result?.status ?? null,
+      foundationReason: result?.reason ?? null,
+      payloadMatches: result?.facts?.install?.payloadMatches ?? null,
+      requiredActions: result?.requiredActions ?? [],
+    });
+  }
+}
+
+/**
+ * Observe one frozen Kimi or CodeBuddy plugin payload through Foundation.
+ *
+ * @param {object} input
+ * @param {object} input.plan
+ * @param {object} input.action
+ * @param {string} input.root
+ * @param {string} input.runDir - Fresh per-action directory containing empty
+ *   install, temporary and evidence children.
+ * @param {Function} [input.runPluginVerificationFn]
+ * @param {Function} [input.clock]
+ * @returns {Promise<object>} local payload-observation receipt
+ */
+export async function verifyFrozenPluginWithFoundation({
+  plan,
+  action,
+  root,
+  runDir,
+  runPluginVerificationFn = runPluginVerification,
+  clock = () => new Date().toISOString(),
+} = {}) {
+  const unit = (plan?.units ?? []).find((candidate) => candidate.id === action?.unitId);
+  if (!unit?.frozenSnapshot?.path || !unit.frozenSnapshot.commit) {
+    throw fail('Foundation plugin observation requires a frozen unit snapshot', {
+      actionId: action?.id,
+      unitId: action?.unitId,
+    });
+  }
+
+  if (!isFoundationPluginVerificationEligible({ action, units: plan.units })) {
+    throw fail('Foundation local plugin observation requires one identity-bound bundled-family payload', {
+      actionId: action?.id,
+      sourceForm: action?.parameters?.sourceDescriptor?.form ?? null,
+      pluginSubpath: action?.parameters?.sourceDescriptor?.pluginSubpath ?? null,
+    });
+  }
+
+  const platformId = action?.parameters?.consumer;
+  const platform = getPlatform(platformId);
+  if (!['kimi', 'codebuddy'].includes(platform.id)) {
+    throw fail('Foundation local plugin observation is not configured for this release platform', {
+      actionId: action?.id,
+      platform: platform.id,
+    });
+  }
+  const sourceDescriptor = action.parameters.sourceDescriptor;
+  const distribution = (unit.distributions ?? []).find(
+    (candidate) => candidate.type === platform.distributionType,
+  );
+  const manifestRelativePath = distribution?.installationContract?.manifestRelativePath;
+  if (!manifestRelativePath) {
+    throw fail('Foundation plugin observation requires the frozen installation manifest path', {
+      actionId: action.id,
+      distributionType: platform.distributionType,
+    });
+  }
+
+  const frozen = await verifyFrozenSnapshot({
+    root,
+    snapshotPath: unit.frozenSnapshot.path,
+    expectedDigest: unit.frozenSnapshot.manifestDigest,
+  });
+  const sourceRoot = frozen.snapshotDir;
+  const sourceMembers = projectSourceMembers(frozen.entries);
+  const sourceManifest = frozen.entries.find((entry) => entry.path === manifestRelativePath);
+  if (!sourceManifest) {
+    throw fail('Foundation plugin observation manifest is not part of the frozen payload', {
+      actionId: action.id,
+      manifestRelativePath,
+    });
+  }
+
+  const hostsRoot = bundledHostProfilesRoot();
+  const hostId = await normalizeHostId(platform.buildAdapter.name);
+  const descriptor = await describeHost({ hostId, hostsRoot });
+  const hostsBinding = await createFilesystemRootBinding(hostsRoot);
+  const descriptorFile = await readFileBound(hostsRoot, `${hostId}/host-descriptor.json`, {
+    rootBinding: hostsBinding,
+  });
+  if (!descriptor.verification?.driverId) {
+    throw fail('Foundation host has no complete-plugin verification driver', { hostId });
+  }
+
+  const request = {
+    schemaVersion: 1,
+    kind: 'skill-family.plugin-verification-request',
+    operation: 'plugin-verification',
+    verificationSetId: `${plan.digest}:${action.id}`,
+    goal: 'install-only',
+    source: {
+      type: 'local-staged',
+      candidateRef: sourceDescriptor.commit,
+      sourceManifestSha256: sourceManifest.contentDigest,
+      membersDigest: digestDocument(sourceMembers),
+    },
+    host: {
+      hostId,
+      descriptorSha256: descriptorFile.sha256,
+      driverId: descriptor.verification.driverId,
+      driverVersion: FOUNDATION_PLUGIN_DRIVER_VERSION,
+    },
+    install: { mode: 'fresh-tree' },
+  };
+  const bindings = {
+    sourceRoot,
+    sourceManifestRelPath: manifestRelativePath,
+    sourceMembers,
+    installContainerRoot: join(runDir, 'install'),
+    temporaryRoot: join(runDir, 'temporary'),
+    privateEvidenceRoot: join(runDir, 'evidence'),
+  };
+
+  const result = await runPluginVerificationFn({ request, bindings, hostsRoot });
+  assertResultMatchesRequest(result, request);
+
+  return {
+    planDigest: plan.digest,
+    actionId: action.id,
+    unitId: unit.id,
+    requestDigest: result.requestDigest,
+    hostId,
+    goal: request.goal,
+    sourceType: request.source.type,
+    foundationStatus: result.status,
+    payloadMatches: result.facts.install.payloadMatches,
+    observationDigest: result.facts.install.observationDigest,
+    observedAt: clock(),
+  };
+}

package/src/core/hooks.mjs

@@ -43,22 +43,6 @@ const ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 // Validation
 // ---------------------------------------------------------------------------
 
-/**
- * A release plan binds at most one postPublish declaration. Both prepare
- * and adoption assessment consume this pure rule and retain their own
- * error codes and presentation. Declaration contents are validated by
- * the existing postPublish validator, not by this cross-unit check.
- *
- * @param {Array<Object>} units - config.releaseUnits.
- * @returns {null|{unitIds: string[]}} Sorted conflicting unit IDs, or null.
- */
-export function findPostPublishUnitConflict(units) {
-  const declaring = (units ?? [])
-    .filter((unit) => unit && typeof unit === 'object' && unit.postPublish !== undefined);
-  if (declaring.length <= 1) return null;
-  return { unitIds: declaring.map((unit) => unit.id).sort() };
-}
-
 /**
  * Validate the shape of a hook descriptor against the project contract.
  *

package/src/core/plan.mjs

@@ -202,7 +202,8 @@ export function validatePlan(plan) {
 }
 
 /**
- * planVersion 2 digest scope (design: t1-2-digest-decoupling.md §4.1).
+ * planVersion 2/3 digest scope (design: t1-2-digest-decoupling.md §4.1;
+ * v3 inherits the v2 scope per 多发布单元 postPublish v3 §4.2).
  *
  * The record layer -- top-level `digest`, lifecycle `status`, `createdAt`,
  * the whole `baseline` object, and each action's runtime `status` -- is
@@ -210,8 +211,10 @@ export function validatePlan(plan) {
  * but is excluded from the digest. Everything else (planVersion, units with
  * every frozenSnapshot artifact identity field, externalActions identity,
  * production, configDigest, verificationGates, snapshotDigest) binds.
+ * For v3 the frozen `postPublish` array and every item binding field stay in
+ * the binding layer: any order or binding change moves the digest.
  *
- * This is the ONLY place the v2 record layer is defined.
+ * This is the ONLY place the v2/v3 record layer is defined.
  *
  * @param {object} plan - A plan object.
  * @returns {object} The binding-layer projection of the plan.
@@ -242,9 +245,12 @@ function stripRecordLayerV2(plan) {
  *
  * Digest scope forks on `plan.planVersion` (centralized here, never spread
  * elsewhere):
- * - planVersion 2: record-layer fields (status/createdAt/baseline/action
+ * - planVersion 2/3: record-layer fields (status/createdAt/baseline/action
  *   status/digest) are stripped before hashing, so re-preparing over the
- *   same sources yields the same digest. See `stripRecordLayerV2`.
+ *   same sources yields the same digest. See `stripRecordLayerV2`. v3
+ *   inherits the v2 scope exactly (multi-release-unit postPublish v3 §4.2);
+ *   versions beyond {2,3} are NOT admitted and stay fail-closed on the
+ *   legacy v1 path rather than being silently bound to v2 semantics.
  * - planVersion 1 or absent (legacy): only the top-level `digest` field is
  *   stripped. Byte-for-byte legacy semantics -- this path must never change.
  *
@@ -258,7 +264,7 @@ export function computePlanDigest(plan) {
   // 而是经 digest.mjs 的宽松输入域包装（contracts 权威序列化 + 本地归一化）
   // 后由 Foundation digestBytes 摘要 —— 对纯 JSON 计划与 digestDocument 字节
   // 完全一致，对含 undefined 的计划保持迁移前字节语义。
-  if (plan.planVersion === 2) {
+  if (plan.planVersion === 2 || plan.planVersion === 3) {
     return sha256Hex(canonicalJson(stripRecordLayerV2(plan)));
   }
   // Strip the digest field if present so the hash is self-consistent.
@@ -341,14 +347,15 @@ export async function writePlanImmutable(planPath, plan) {
       // EEXIST 直接抛冲突，无幂等分支；wrapper 补齐，fail-closed 无双路径）。
       const existing = await readFile(planPath, 'utf8').catch(() => null);
       if (existing === json) return { planPath, planDigest };
-      // planVersion 2 (design: t1-2-digest-decoupling.md §4.1): record-layer
-      // fields (status/createdAt/baseline) are excluded from the digest, so
+      // planVersion 2/3 (design: t1-2-digest-decoupling.md §4.1; v3 inherits
+      // the scope per 多发布单元 postPublish v3 §4.2): record-layer fields
+      // (status/createdAt/baseline) are excluded from the digest, so
       // re-preparing over identical binding content yields the SAME digest
       // with legitimately different bytes. Reuse the existing authority IFF
       // it is genuinely self-consistent (its embedded digest and recomputed
       // digest both equal this digest) -- the authority is never replaced.
       // Any other divergence (tampering, malformed file) still fails closed.
-      if (plan.planVersion === 2 && existing !== null) {
+      if ((plan.planVersion === 2 || plan.planVersion === 3) && existing !== null) {
         let existingPlan = null;
         try {
           existingPlan = JSON.parse(existing);
@@ -386,7 +393,7 @@ export async function writePlanImmutable(planPath, plan) {
 /**
  * Canonical normalized freeze timestamp shape (`YYYY-MM-DDTHH:MM:SS+00:00`).
  * Mirrors the frozenSnapshot.commitTimestamp pattern in the release-plan
- * schema; used by the planVersion 2 completeness gate, which requires a
+ * schema; used by the planVersion 2/3 completeness gate, which requires a
  * canonical normalized timestamp without re-binding it to plan.createdAt.
  */
 const CANONICAL_COMMIT_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$/;
@@ -568,8 +575,9 @@ export function validatePlanActionCompleteness(plan, options = {}) {
       }
       if (!frozen.commitTimestamp || typeof frozen.commitTimestamp !== 'string') {
         failures.push(`unit "${unitId}" frozenSnapshot.commitTimestamp is missing; legacy production plans without a freeze timestamp are rejected, never silently backfilled`);
-      } else if (plan.planVersion === 2) {
-        // planVersion 2 (design: t1-2-digest-decoupling.md §4.2): the freeze
+      } else if (plan.planVersion === 2 || plan.planVersion === 3) {
+        // planVersion 2/3 (design: t1-2-digest-decoupling.md §4.2; v3 inherits
+        // the semantics per 多发布单元 postPublish v3 §4.2): the freeze
         // timestamp is derived from the headCommit committer date, so it no
         // longer equals plan.createdAt (record-layer real clock). It must
         // still be a canonical normalized timestamp -- the same pattern the

package/src/core/postpublish-approval.mjs

@@ -47,6 +47,7 @@ import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { computePlanDigest } from './plan.mjs';
 import { computeApprovalDigest, validateApprovalTimeWindow } from './approval.mjs';
 import { resolvePresetRequiresApproval } from './presets.mjs';
+import { normalizePostPublishView, validatePostPublishHookIdUniqueness } from './postpublish.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
 
 const postpublishApprovalSchema = JSON.parse((await readTrustedPackageResource(
@@ -79,7 +80,8 @@ export function validatePostPublishApprovalRecordSchema(approval) {
  * - 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;
+ * - hookId names a hook declared in the frozen plan's postPublish
+ *   declarations (unified normalized view, globally unique across units);
  * - that hook actually declares requiresApproval: true;
  * - the shared approval time window (24h max, 5-minute skew, unexpired).
  *
@@ -103,7 +105,15 @@ export function validatePostPublishApproval(plan, approval, options = {}) {
     );
   }
 
-  const hooks = plan.postPublish?.hooks ?? [];
+  // §4.3 unified normalization (rework R-02): the frozen plan's postPublish
+  // may be the legacy single declaration (planVersion 1/2) or the v3
+  // declaration array; every consumer resolves declared hooks through the
+  // SAME normalized view, and the SAME array-level uniqueness authority
+  // re-asserts that hookId is globally unique across declarations — one
+  // (planDigest, hookId) approval must never authorize two units.
+  const declarations = normalizePostPublishView(plan);
+  validatePostPublishHookIdUniqueness(declarations);
+  const hooks = declarations.flatMap((declaration) => declaration.hooks ?? []);
   const hook = hooks.find((entry) => entry.id === approval.hookId);
   if (!hook) {
     throw new ReleaseError(