release-skill 0.9.0 → 0.9.3

package/src/commands/setup.mjs

@@ -46,6 +46,7 @@ import {
   deriveGateSuggestions,
   deriveHookDurations,
   deriveLongHookSuggestions,
+  derivePreHookPublicSurfaceFinding,
   scanGateDeclarationFindings,
   FINDING_CATEGORY,
   ASSESSMENT_STATUS,
@@ -3209,6 +3210,7 @@ export async function assessAdoption({ root } = {}) {
     currentProducerVersion: resolveProducerVersion(),
   });
   findings.push(...deriveLongHookSuggestions(hookDurations));
+  findings.push(derivePreHookPublicSurfaceFinding({ config, hookDurations }));
   findings.push(...deriveCheckOnlySuggestions(config.hooks));
 
   // --- Gate suggestions (scenarios 5 & 6) ---

package/src/commands/ship.mjs

@@ -2,6 +2,7 @@ import { readFile, lstat, mkdir } from 'node:fs/promises';
 import { basename, dirname, resolve } from 'node:path';
 import { publishFileOrReplace } from 'skill-family-harness-node';
 
+import { MAX_APPROVAL_MS } from '../core/approval.mjs';
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
 import {
   effectiveHookRequiresApproval,
@@ -88,6 +89,7 @@ async function defaultDependencies() {
     postVerifyRelease: postverifyModule.postVerifyRelease,
     preflightGitTransports: transportModule.preflightGitTransports,
     updatePreviousPublicBaselines: metadataModule.updatePreviousPublicBaselines,
+    readMaxApprovalMs: () => MAX_APPROVAL_MS,
   };
 }
 
@@ -116,34 +118,135 @@ function publicState(state) {
     ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
     ...(state.postRelease ? { postRelease: state.postRelease } : {}),
-    verificationGateAuthorizationIncludedInPlanApproval: true,
-    postVerifyMetadataUpdateIncludedInPlanApproval: true,
+    externalActionsIncludedInPlanApproval: true,
+    verificationGatesIncludedInPlanApproval: true,
+    postPublishCheckpointApprovalsIncludedInPlanApproval: false,
   };
 }
 
+const HOUR_MS = 60 * 60 * 1000;
+
+const ACTION_TARGET_FIELDS = Object.freeze({
+  'push-commit': Object.freeze(['remote', 'branch']),
+  'push-snapshot': Object.freeze(['repo', 'branch', 'branchStrategy', 'commit']),
+  'create-tag': Object.freeze(['repo', 'tag', 'commit']),
+  'npm-publish': Object.freeze(['package', 'version', 'registry', 'tag', 'access', 'provenance']),
+  'github-release': Object.freeze(['repo', 'tag', 'name', 'commit']),
+  'claude-marketplace-install': Object.freeze(['consumer', 'plugin', 'marketplace', 'repo', 'ref', 'version', 'entrySkill']),
+  'codex-marketplace-install': Object.freeze(['consumer', 'plugin', 'marketplace', 'repo', 'ref', 'version', 'entrySkill']),
+  'kimi-marketplace-install': Object.freeze(['consumer', 'plugin', 'repo', 'ref', 'version', 'entrySkill']),
+  'codebuddy-marketplace-install': Object.freeze(['consumer', 'plugin', 'repo', 'ref', 'version', 'entrySkill']),
+  'set-default-branch': Object.freeze(['repo', 'oldBranch', 'newBranch', 'expectedNewBranchCommit']),
+});
+
+function deriveApprovalWindowHours(maxApprovalMs) {
+  if (
+    !Number.isSafeInteger(maxApprovalMs)
+    || maxApprovalMs <= 0
+    || maxApprovalMs % HOUR_MS !== 0
+  ) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'core approval window must be a positive whole number of hours',
+      { maxApprovalMs },
+    );
+  }
+  return maxApprovalMs / HOUR_MS;
+}
+
+function projectActionTarget(action) {
+  const parameters = action?.parameters ?? {};
+  return Object.fromEntries(
+    (ACTION_TARGET_FIELDS[action?.type] ?? [])
+      .filter((field) => parameters[field] !== undefined)
+      .map((field) => [field, parameters[field]]),
+  );
+}
+
 /**
  * Build a human-readable approval summary from the frozen plan.
- * Lists each unit's version and every external action's id/type/unitId.
- * Returns an empty summary when the plan file is not yet available (e.g., in tests).
+ * Lists every publish target and every checkpoint approval separately. All
+ * fields are mechanically projected from the frozen plan; unreadable plans
+ * fail closed instead of producing an empty or partial summary.
  *
  * @param {string} planPath - Path to the frozen release plan.
  * @returns {Promise<object>} The approval summary.
  */
-async function buildApprovalSummary(planPath) {
+async function buildApprovalSummary(planPath, maxApprovalMs = MAX_APPROVAL_MS) {
   try {
     const plan = JSON.parse(await readFile(planPath, 'utf8'));
-    const units = (plan.units ?? []).map((unit) => ({
-      id: unit.id,
-      targetVersion: unit.targetVersion ?? unit.version,
-    }));
+    const approvalWindowHours = deriveApprovalWindowHours(maxApprovalMs);
     const actions = (plan.externalActions ?? []).map((action) => ({
       id: action.id,
       type: action.type,
       unitId: action.unitId,
+      target: projectActionTarget(action),
     }));
-    return { units, actions };
-  } catch {
-    return { units: [], actions: [] };
+    const units = (plan.units ?? []).map((unit) => {
+      const targetVersion = unit.targetVersion ?? unit.version;
+      const githubRelease = (plan.externalActions ?? [])
+        .find((action) => action.unitId === unit.id && action.type === 'github-release');
+      return {
+        id: unit.id,
+        targetVersion,
+        publicRepo: unit.publicRepo,
+        branch: unit.frozenSnapshot?.branch
+          ?? unit.productionConfig?.branchTemplate
+            ?.replaceAll('{tag}', unit.tagTemplate?.replace('{version}', targetVersion) ?? '')
+            .replaceAll('{version}', targetVersion)
+            .replaceAll('{unit}', unit.id),
+        branchStrategy: unit.frozenSnapshot?.branchStrategy ?? unit.productionConfig?.branchStrategy,
+        tag: unit.tagTemplate?.replace('{version}', targetVersion),
+        npm: (unit.distributions ?? [])
+          .filter((distribution) => distribution.type === 'npm')
+          .map((distribution) => ({
+            package: distribution.package,
+            version: targetVersion,
+            registry: distribution.registry,
+            distTag: distribution.tag,
+            access: distribution.access,
+            provenance: distribution.provenance,
+          })),
+        ...(githubRelease ? {
+          githubRelease: {
+            repo: githubRelease.parameters?.repo ?? githubRelease.parameters?.publicRepo,
+            tag: githubRelease.parameters?.tag,
+            name: githubRelease.parameters?.name,
+          },
+        } : {}),
+      };
+    });
+    const postPublishCheckpointApprovals = normalizePostPublishView(plan)
+      .flatMap((declaration) => (declaration.hooks ?? [])
+        .filter((hook) => effectiveHookRequiresApproval(hook))
+        .map((hook) => ({
+          unitId: declaration.unitId,
+          hookId: hook.id,
+          actionId: postPublishActionId({
+            planVersion: plan.planVersion,
+            unitId: declaration.unitId,
+            localId: hook.id,
+          }),
+          phase: hook.phase ?? 'distribute',
+          ...(hook.preset !== undefined ? { preset: hook.preset } : {}),
+          ...(hook.config?.delivery !== undefined ? { delivery: hook.config.delivery } : {}),
+          requiresApproval: true,
+          includedInPlanApproval: false,
+          approvalWindowHours,
+          binding: { planDigest: plan.digest, hookId: hook.id },
+        })));
+    return {
+      units,
+      actions,
+      waivers: Array.isArray(plan.waivers) ? plan.waivers : [],
+      postPublishCheckpointApprovals,
+    };
+  } catch (error) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot build ship approval summary from frozen plan: ${error.message}`,
+      { planPath },
+    );
   }
 }
 
@@ -197,9 +300,11 @@ async function allUnclosedPostVerifyHooksUngated(state, postVerifyHooks, planVer
  * resumes instead of reconstructing authority from terminal/chat output.
  *
  * New flow (v0.4+): ship directly runs configured hooks and verification gates
- * without a separate hook authorization step. The only human gate is plan
- * approval. Kimi/CodeBuddy installations are non-blocking manual follow-up
- * tasks when the plan declares humanConsumersStrategy: 'manualFollowUps'.
+ * without a separate hook authorization step. Plan approval is the only
+ * normal release-level gate. A postPublish hook whose effective
+ * requiresApproval is true still needs its independent checkpoint approval.
+ * Kimi/CodeBuddy installations are non-blocking manual follow-up tasks when
+ * the plan declares humanConsumersStrategy: 'manualFollowUps'.
  */
 export async function advanceShip(options = {}, injected = {}) {
   const root = resolve(options.root ?? process.cwd());
@@ -210,6 +315,25 @@ export async function advanceShip(options = {}, injected = {}) {
     ? injected
     : await defaultDependencies();
   let state = await readState(statePath);
+  const requestedTargetVersion = options.targetVersion ?? null;
+  if (state && requestedTargetVersion !== null) {
+    const stateTargetVersion = state.targetVersion ?? null;
+    if (stateTargetVersion === null || stateTargetVersion !== requestedTargetVersion) {
+      const suffix = stateTargetVersion === null
+        ? 'state targetVersion is missing; provide a new --state path to start the requested version'
+        : `state targetVersion ${stateTargetVersion} does not match requested targetVersion ${requestedTargetVersion}`;
+      throw new ReleaseError(
+        GATE_FAILED,
+        `ship state target version mismatch: ${suffix}`,
+        {
+          reason: 'SHIP_STATE_TARGET_VERSION_MISMATCH',
+          statePath,
+          stateTargetVersion,
+          requestedTargetVersion,
+        },
+      );
+    }
+  }
   if (state?.gitTransport) {
     process.env.RELEASE_SKILL_GIT_TRANSPORT = state.gitTransport;
   }
@@ -268,7 +392,10 @@ export async function advanceShip(options = {}, injected = {}) {
       transportPreflight = await deps.preflightGitTransports(frozenPlan);
       process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
     }
-    const approvalSummary = await buildApprovalSummary(prepared.planPath);
+    const maxApprovalMs = typeof deps.readMaxApprovalMs === 'function'
+      ? await deps.readMaxApprovalMs()
+      : MAX_APPROVAL_MS;
+    const approvalSummary = await buildApprovalSummary(prepared.planPath, maxApprovalMs);
     state = {
       ...state,
       status: 'NEEDS_PLAN_APPROVAL',

package/src/commands/verify.mjs

@@ -1045,6 +1045,27 @@ export async function verifyRelease(options) {
       requireDigest: Boolean(plan.production),
       ...(plan.production ? { authorityPlanPath: planPath } : {}),
     });
+
+    // `distribute` runs are deliberately not valid verify sources. Report the
+    // actionable lineage correction before the generic lineage validator's
+    // unsupported-command error, while keeping the existing source authority
+    // and automatic distribute discovery semantics unchanged.
+    if (sourceRun.command === 'distribute') {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'verify --run must point to a PUBLISHED publish or reconcile run from the same plan; distribute runs are automatically discovered by verify and do not become the verify authority',
+        {
+          sourceRunCommand: sourceRun.command,
+          sourceRunId: sourceRun.runId,
+          sourceRunStatus: sourceRun.status,
+          expectedSourceCommands: ['publish', 'reconcile'],
+          requiredSourceStatus: 'PUBLISHED',
+          distributeRunsAutoDiscovered: true,
+          verifyAuthority: 'publish-or-reconcile-source-run',
+        },
+      );
+    }
+
     await validateRunLineage(sourceRun, {
       plan,
       planPath,

package/src/core/adoption-assessment.mjs

@@ -506,6 +506,65 @@ export function deriveLongHookSuggestions(hookDurations) {
   return findings;
 }
 
+/**
+ * Report the opt-in R93-01 pre-hook public-surface check without changing the
+ * base adoption conclusion. A candidate is based only on hookDurations that
+ * already passed the current-producer, command/cwd-matching and real
+ * started/completed-pair checks above; timeout, cache hits and labels are not
+ * consulted here.
+ *
+ * @param {object} options
+ * @param {object} options.config - Loaded project configuration.
+ * @param {Array<object>} options.hookDurations - Trusted duration facts.
+ * @returns {object} One adoption finding for the policy field.
+ */
+export function derivePreHookPublicSurfaceFinding({ config, hookDurations }) {
+  const fieldPath = 'policy.preHookPublicSurfaceCheck';
+  if (config?.policy?.preHookPublicSurfaceCheck === true) {
+    return createFinding({
+      category: FINDING_CATEGORY.SATISFIED,
+      code: 'PRE_HOOK_PUBLIC_SURFACE_CHECK_ADOPTED',
+      fieldPath,
+      message: '已启用 Hook 前公开表面检查；prepare 会在首个 Hook 前验证候选公开表面，并在 Hook 后重新执行正式检查。',
+      evidence: { enabled: true },
+    });
+  }
+
+  const candidate = (hookDurations ?? [])
+    .filter((duration) => (
+      duration?.basis === 'evidence'
+      && Number.isFinite(duration.durationMs)
+      && duration.durationMs >= LONG_HOOK_THRESHOLD_MS
+      && duration.realRuns >= 1
+    ))
+    .sort((a, b) => (
+      (b.durationMs - a.durationMs) || a.hookName.localeCompare(b.hookName)
+    ))[0];
+  if (candidate) {
+    return createFinding({
+      category: FINDING_CATEGORY.OPTIONAL_SUGGESTION,
+      code: 'PRE_HOOK_PUBLIC_SURFACE_CHECK_CANDIDATE',
+      fieldPath,
+      message: `当前 hook "${candidate.hookName}" 有可信的实际运行证据（至少 30 分钟）；可人工评估是否启用 Hook 前公开表面检查。`,
+      evidence: {
+        hookName: candidate.hookName,
+        durationMs: candidate.durationMs,
+        realRuns: candidate.realRuns,
+        lastObservedAt: candidate.lastObservedAt,
+      },
+      action: '确认公开文件不会由 Hook 生成或修复后，再在配置中将 policy.preHookPublicSurfaceCheck 设为 true；评估不会自动修改配置。',
+      severity: 'suggestion',
+    });
+  }
+
+  return createFinding({
+    category: FINDING_CATEGORY.NOT_APPLICABLE,
+    code: 'PRE_HOOK_PUBLIC_SURFACE_CHECK_NOT_APPLICABLE',
+    fieldPath,
+    message: '当前没有可信且匹配当前 Hook 的至少 30 分钟实际运行证据，暂不建议启用 Hook 前公开表面检查。',
+  });
+}
+
 const STATUS_LABEL = Object.freeze({
   NOT_CONFIGURED: '尚未配置',
   PARTIALLY_ADOPTED: '部分接入（存在必选缺口）',

package/src/core/derived-artifact-gates.mjs

@@ -5,17 +5,20 @@
  * In the 0.6.1 cycle two prepares burned the full ~80s test hook before
  * surfacing drift that a sub-second check could have caught: adapter trees
  * out of sync with skills-src/, and self-bootstrap fact pins still bound to
- * the previous version. This module promotes those two exact checks to
- * prepare's earliest stage, alongside the bundle freshness gate:
+ * the previous version. This module promotes those checks and the platform
+ * manifest freshness check to prepare's earliest stage, alongside the bundle
+ * freshness gate:
  *
  * - adapter gate: runs `scripts/build-adapters.mjs --check` (drift list,
  *   exit 1 on drift — the same supported check the scripts surface offers);
+ * - platform manifest gate: runs
+ *   `scripts/generate-platform-manifest.mjs --check`;
  * - fact-pin gate: runs the version fact pins of
  *   `test/release-docs-self-bootstrap.test.mjs` — exactly its hermetic
  *   section 1 (`[self-bootstrap 1*]`: byte-level version assertions plus the
  *   in-process read-only planner), scoped via `--test-name-pattern`.
  *
- * Both promote the CANONICAL check logic — the gate and the full pipeline
+ * All three promote the CANONICAL check logic — the gates and the full pipeline
  * can never disagree about what "in sync" means. The facts gate is scoped to
  * the suite's hermetic fact-pin section deliberately: the suite's remaining
  * sections shell out to npm/git and drive fixture prepares, which would make
@@ -88,6 +91,15 @@ const GATES = Object.freeze({
       'Rebuild the existing adapters with: node scripts/build-adapters.mjs --apply ' +
       `(or run the one-click derived-artifact sync from the workspace root: ${DERIVED_SYNC_COMMAND}).`,
   }),
+  'platform-manifest': Object.freeze({
+    artifact: 'platform-manifest',
+    marker: join('scripts', 'generate-platform-manifest.mjs'),
+    argv: (pkgRoot) => [join(pkgRoot, 'scripts', 'generate-platform-manifest.mjs'), '--check'],
+    timeoutMs: 120000,
+    remediation:
+      'Regenerate the platform manifest with: node scripts/generate-platform-manifest.mjs ' +
+      `(or run the one-click derived-artifact sync from the workspace root: ${DERIVED_SYNC_COMMAND}).`,
+  }),
   'self-bootstrap-facts': Object.freeze({
     artifact: 'self-bootstrap-facts',
     marker: join('test', 'release-docs-self-bootstrap.test.mjs'),
@@ -118,7 +130,7 @@ async function isFile(path) {
 /**
  * Run one derived-artifact check (pure decision, never throws).
  *
- * @param {'adapters' | 'self-bootstrap-facts'} kind - Gate to run.
+ * @param {'adapters' | 'platform-manifest' | 'self-bootstrap-facts'} kind - Gate to run.
  * @param {string} pkgRoot - Absolute package root of the running checkout.
  * @param {object} [options]
  * @param {Function} [options.execFileFn] - execFile seam (tests).
@@ -202,6 +214,11 @@ export function checkAdapterFreshness(pkgRoot, options = {}) {
   return checkDerivedArtifactGate('adapters', pkgRoot, options);
 }
 
+/** Platform manifest freshness decision (generate-platform-manifest --check). */
+export function checkPlatformManifestFreshness(pkgRoot, options = {}) {
+  return checkDerivedArtifactGate('platform-manifest', pkgRoot, options);
+}
+
 /** Self-bootstrap fact-pin decision (single-file test). */
 export function checkSelfBootstrapFacts(pkgRoot, options = {}) {
   return checkDerivedArtifactGate('self-bootstrap-facts', pkgRoot, options);
@@ -215,7 +232,9 @@ async function assertGate(kind, pkgRoot, options = {}) {
   const gate = GATES[kind];
   const subject = kind === 'adapters'
     ? 'adapters/ is out of sync with its sources (build-adapters --check reported drift)'
-    : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
+    : kind === 'platform-manifest'
+      ? 'platform-manifest.json is out of sync with the current package tree (generate-platform-manifest --check reported drift)'
+      : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
   throw new ReleaseError(
     DERIVED_ARTIFACT_STALE,
     `${subject}. ${DERIVED_ARTIFACT_PREGATE_NOTE} ${gate.remediation}`,
@@ -243,6 +262,14 @@ export function assertAdapterFreshness(pkgRoot, options = {}) {
   return assertGate('adapters', pkgRoot, options);
 }
 
+/**
+ * Fail-closed platform manifest pre-gate used by prepare's earliest stage.
+ * Not-applicable layouts return quietly; drift throws DERIVED_ARTIFACT_STALE.
+ */
+export function assertPlatformManifestFreshness(pkgRoot, options = {}) {
+  return assertGate('platform-manifest', pkgRoot, options);
+}
+
 /**
  * Fail-closed self-bootstrap fact-pin pre-gate used by prepare's earliest
  * stage. Not-applicable layouts return quietly; drift throws

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

@@ -1,5 +1,5 @@
 /**
- * Release-domain thin adapter for Foundation 0.13 complete-plugin observation.
+ * Release-domain thin adapter for Foundation 0.15 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
@@ -19,6 +19,8 @@ import {
 } from 'skill-family-engineering-kit';
 import {
   createFilesystemRootBinding,
+  digestBytes,
+  observeFilesystemTree,
   readFileBound,
 } from 'skill-family-harness-node';
 
@@ -30,6 +32,176 @@ import { ReleaseError, POST_PUBLISH_VERIFY_FAILED } from './errors.mjs';
 // 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';
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+
+function isSafeRelativePath(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && !value.startsWith('/')
+    && !value.includes('\\')
+    && !value.includes(':')
+    && !value.includes('\0')
+    && value.split('/').every((part) => part.length > 0 && part !== '.' && part !== '..');
+}
+
+function decodeCanonicalBase64(value) {
+  if (typeof value !== 'string' || !BASE64_PATTERN.test(value)) return null;
+  const decoded = Buffer.from(value, 'base64');
+  return decoded.toString('base64') === value ? decoded : null;
+}
+
+function hasExactKeys(value, keys) {
+  return Object.keys(value).sort().join(',') === keys.join(',');
+}
+
+function compareUnicodeCodePoints(left, right) {
+  const leftPoints = Array.from(left, (character) => character.codePointAt(0));
+  const rightPoints = Array.from(right, (character) => character.codePointAt(0));
+  const length = Math.min(leftPoints.length, rightPoints.length);
+  for (let index = 0; index < length; index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) return leftPoints[index] - rightPoints[index];
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+function installCommandExited(result) {
+  const commands = result?.facts?.install?.commands;
+  if (!Array.isArray(commands)) return false;
+  return commands.every((command) => {
+    const execution = command?.execution;
+    return execution?.exitStatus === 0 && execution.processStatus === 'exited';
+  });
+}
+
+function assertStableInstallTreeState(state) {
+  if (state === undefined) return;
+  if (!state || typeof state !== 'object' || Array.isArray(state)) {
+    throw fail('Foundation install tree state is invalid');
+  }
+  if (
+    state.commandExited === false
+    || state.isolated === false
+    || state.stable === false
+    || state.namespaceWriterActive === true
+  ) {
+    throw fail('Foundation install tree is not a stable isolated post-command tree', {
+      commandExited: state.commandExited ?? null,
+      isolated: state.isolated ?? null,
+      stable: state.stable ?? null,
+      namespaceWriterActive: state.namespaceWriterActive ?? null,
+    });
+  }
+}
+
+function compareRecordedInstallTree(observation, expectedMembers) {
+  if (
+    !observation
+    || typeof observation !== 'object'
+    || observation.schemaVersion !== 1
+    || observation.kind !== 'skill-family.filesystem-tree-observation'
+    || !/^[0-9a-f]{64}$/u.test(observation.membersDigest ?? '')
+    || !Array.isArray(observation.members)
+  ) {
+    throw fail('Foundation install tree observation has an invalid shape');
+  }
+  if (digestDocument(observation.members) !== observation.membersDigest) {
+    throw fail('Foundation install tree observation digest does not match its members');
+  }
+  const actual = new Map();
+  const foldedPaths = new Set();
+  let previousPath = null;
+  for (const member of observation.members) {
+    const foldedPath = member?.path?.toLowerCase();
+    if (
+      !member
+      || !isSafeRelativePath(member.path)
+      || !['directory', 'file', 'symlink'].includes(member.type)
+      || actual.has(member.path)
+      || foldedPaths.has(foldedPath)
+      || previousPath !== null && compareUnicodeCodePoints(previousPath, member.path) >= 0
+    ) {
+      throw fail('Foundation install tree observation contains duplicate or invalid paths');
+    }
+    actual.set(member.path, member);
+    foldedPaths.add(foldedPath);
+    const requiredKeys = member.type === 'directory'
+      ? ['path', 'statMode', 'type']
+      : member.type === 'file'
+        ? ['bytes', 'contentBase64', 'path', 'sha256', 'statMode', 'type']
+        : ['bytes', 'path', 'statMode', 'targetBase64', 'type'];
+    if (!hasExactKeys(member, requiredKeys)) {
+      throw fail('Foundation install tree member has unknown or missing fields', { path: member.path });
+    }
+    previousPath = member.path;
+    if (
+      typeof member.statMode !== 'number'
+      || !Number.isInteger(member.statMode)
+      || member.statMode < 0
+      || member.statMode > 0xffff
+    ) {
+      throw fail('Foundation install tree member mode is invalid', { path: member.path });
+    }
+    if (member.type === 'file') {
+      const content = decodeCanonicalBase64(member.contentBase64);
+      if (
+        !content
+        || typeof member.sha256 !== 'string'
+        || !SHA256_PATTERN.test(member.sha256)
+        || !Number.isSafeInteger(member.bytes)
+        || member.bytes < 0
+        || member.bytes !== content.length
+        || member.sha256 !== digestBytes(content)
+      ) {
+        throw fail('Foundation install tree file record is invalid', { path: member.path });
+      }
+    }
+    if (member.type === 'symlink') {
+      const target = decodeCanonicalBase64(member.targetBase64);
+      if (
+        !target
+        || target.length === 0
+        || !Number.isSafeInteger(member.bytes)
+        || member.bytes < 1
+        || member.bytes !== target.length
+      ) {
+        throw fail('Foundation install tree link record is invalid', { path: member.path });
+      }
+    }
+  }
+  const expected = new Map(expectedMembers.map((member) => [member.path, member]));
+  for (const [path, expectedMember] of expected) {
+    const member = actual.get(path);
+    if (!member || member.type === 'symlink' || member.type !== expectedMember.type) {
+      throw fail('declared install tree member is missing or unsafe', { path });
+    }
+    if (member.type === 'file' && (
+      member.sha256 !== expectedMember.sha256
+      || member.bytes !== expectedMember.bytes
+      || ((member.statMode & 0o111) !== 0) !== expectedMember.executable
+    )) {
+      throw fail('declared install tree member drifted from the frozen payload', { path });
+    }
+  }
+  const extras = [...actual.values()].filter((member) => !expected.has(member.path));
+  const extraInstalledPaths = extras
+    .map((member) => member.path)
+    .sort(compareUnicodeCodePoints);
+  const extraInstalledLinks = extras
+    .filter((member) => member.type === 'symlink')
+    .map((member) => {
+      // Keep the target bytes supplied by Foundation. No path resolution or
+      // target read occurs here, so an added link can never be followed.
+      return {
+        path: member.path,
+        targetBase64: member.targetBase64,
+        bytes: member.bytes,
+        statMode: member.statMode,
+      };
+    })
+    .sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
+  return { extraInstalledPaths, extraInstalledLinks };
+}
 
 function fail(message, details = {}) {
   return new ReleaseError(POST_PUBLISH_VERIFY_FAILED, message, details);
@@ -135,6 +307,8 @@ export async function verifyFrozenPluginWithFoundation({
   root,
   runDir,
   runPluginVerificationFn = runPluginVerification,
+  observeFilesystemTreeFn = observeFilesystemTree,
+  installTreeState,
   clock = () => new Date().toISOString(),
 } = {}) {
   const unit = (plan?.units ?? []).find((candidate) => candidate.id === action?.unitId);
@@ -231,6 +405,38 @@ export async function verifyFrozenPluginWithFoundation({
   const result = await runPluginVerificationFn({ request, bindings, hostsRoot });
   assertResultMatchesRequest(result, request);
 
+  // A3: the installation command (if Foundation reports one) must have
+  // exited before the isolated tree is observed. The install-only Foundation
+  // path reports no commands, which is the completed local materialization.
+  if (!installCommandExited(result)) {
+    throw fail('Foundation install tree observation requires an exited install command');
+  }
+  assertStableInstallTreeState(installTreeState);
+
+  // Foundation's local install-only contract materializes the payload at the
+  // stable child of the isolated install container. Observe that payload root
+  // rather than the container, whose private siblings are not plugin bytes.
+  const installRoot = join(runDir, 'install', 'payload');
+  let treeObservation;
+  try {
+    const rootBinding = await createFilesystemRootBinding(installRoot);
+    treeObservation = await observeFilesystemTreeFn({
+      root: installRoot,
+      rootBinding,
+      symlinkPolicy: { mode: 'record' },
+    });
+    if (treeObservation?.rootBinding?.digest !== rootBinding.digest) {
+      throw fail('Foundation install tree observation root binding drifted');
+    }
+  } catch (error) {
+    if (error instanceof ReleaseError) throw error;
+    throw fail('Foundation install tree observation failed closed', {
+      cause: error?.message ?? String(error),
+      code: error?.code ?? null,
+    });
+  }
+  const extraInstallAudit = compareRecordedInstallTree(treeObservation, sourceMembers);
+
   return {
     planDigest: plan.digest,
     actionId: action.id,
@@ -243,5 +449,11 @@ export async function verifyFrozenPluginWithFoundation({
     payloadMatches: result.facts.install.payloadMatches,
     observationDigest: result.facts.install.observationDigest,
     observedAt: clock(),
+    ...(extraInstallAudit.extraInstalledPaths.length > 0
+      ? { extraInstalledPaths: extraInstallAudit.extraInstalledPaths }
+      : {}),
+    ...(extraInstallAudit.extraInstalledLinks.length > 0
+      ? { extraInstalledLinks: extraInstallAudit.extraInstalledLinks }
+      : {}),
   };
 }