release-skill 0.9.1 → 0.9.4

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

@@ -15,11 +15,92 @@ import {
 } from './post-release-local.mjs';
 import {
   ReleaseError,
+  CONFIG_INVALID,
   GATE_FAILED,
   PLAN_DIGEST_MISMATCH,
   CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
 
+function normalizeNewShipUnitIds(releaseUnits, requestedUnitIds) {
+  if (requestedUnitIds === undefined) return undefined;
+  const availableUnitIds = (releaseUnits ?? []).map((unit) => unit.id);
+  if (!Array.isArray(requestedUnitIds) || requestedUnitIds.length === 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'explicit ship release-unit selection must contain at least one unit id',
+      { requestedUnitIds, availableUnitIds },
+    );
+  }
+  const requestedSet = new Set(requestedUnitIds);
+  const invalid = requestedUnitIds.filter((unitId) => typeof unitId !== 'string' || unitId.length === 0);
+  const unknown = requestedUnitIds.filter((unitId) => !availableUnitIds.includes(unitId));
+  if (invalid.length > 0 || requestedSet.size !== requestedUnitIds.length || unknown.length > 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'ship release-unit selection contains empty, duplicate, or unknown unit ids',
+      { requestedUnitIds, availableUnitIds },
+    );
+  }
+  return availableUnitIds.filter((unitId) => requestedSet.has(unitId));
+}
+
+function sameUnitSelection(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && new Set(left).size === left.length
+    && new Set(right).size === right.length
+    && left.every((unitId) => right.includes(unitId));
+}
+
+function sameUnitOrder(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((unitId, index) => unitId === right[index]);
+}
+
+function unitScopeMismatch(statePath, stateUnitIds, requestedUnitIds, message) {
+  return new ReleaseError(
+    GATE_FAILED,
+    message,
+    {
+      reason: 'SHIP_STATE_UNIT_SCOPE_MISMATCH',
+      statePath,
+      stateUnitIds: stateUnitIds ?? null,
+      requestedUnitIds: requestedUnitIds ?? null,
+    },
+  );
+}
+
+function assertFrozenPlanUnitScope({ statePath, stateUnitIds, expectedUnitIds, plan }) {
+  const planUnitIds = (plan.units ?? []).map((unit) => unit.id);
+  const exactMatch = Array.isArray(expectedUnitIds)
+    && planUnitIds.length === expectedUnitIds.length
+    && planUnitIds.every((unitId, index) => unitId === expectedUnitIds[index]);
+  if (!exactMatch) {
+    throw unitScopeMismatch(
+      statePath,
+      stateUnitIds,
+      planUnitIds,
+      'ship state release-unit scope does not match frozen plan.units',
+    );
+  }
+}
+
+async function readFrozenPlanForUnitScope(planPath, statePath, stateUnitIds) {
+  try {
+    return JSON.parse(await readFile(planPath, 'utf8'));
+  } catch (error) {
+    throw unitScopeMismatch(
+      statePath,
+      stateUnitIds,
+      null,
+      `cannot verify ship state release-unit scope against frozen plan: ${error.message}`,
+    );
+  }
+}
+
 async function writeJsonAtomic(path, value) {
   await mkdir(dirname(path), { recursive: true });
   const { stateDigest: _oldDigest, ...body } = value;
@@ -102,6 +183,7 @@ function publicState(state) {
     ...(state.hooks && state.hooks.length > 0 ? {
       hooks: state.hooks,
     } : {}),
+    ...(state.selectedUnitIds ? { selectedUnitIds: state.selectedUnitIds } : {}),
     ...(state.planPath ? {
       planPath: state.planPath,
       planDigest: state.planDigest,
@@ -315,6 +397,43 @@ 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 && options.unitIds !== undefined) {
+    if (!Array.isArray(state.selectedUnitIds)) {
+      throw unitScopeMismatch(
+        statePath,
+        null,
+        options.unitIds,
+        'an existing full-scope or legacy ship state cannot acquire --unit; provide a new --state path',
+      );
+    }
+    if (!sameUnitSelection(state.selectedUnitIds, options.unitIds)) {
+      throw unitScopeMismatch(
+        statePath,
+        state.selectedUnitIds,
+        options.unitIds,
+        'ship state release-unit scope does not match the requested --unit values',
+      );
+    }
+  }
   if (state?.gitTransport) {
     process.env.RELEASE_SKILL_GIT_TRANSPORT = state.gitTransport;
   }
@@ -322,6 +441,7 @@ export async function advanceShip(options = {}, injected = {}) {
   if (!state) {
     const loaded = await deps.loadProjectConfig({ root });
     const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
+    const selectedUnitIds = normalizeNewShipUnitIds(loaded.config.releaseUnits, options.unitIds);
     state = {
       schemaVersion: 2,
       root,
@@ -329,6 +449,7 @@ export async function advanceShip(options = {}, injected = {}) {
       targetVersion: options.targetVersion ?? null,
       configDigest: loaded.configDigest,
       hooks,
+      ...(selectedUnitIds ? { selectedUnitIds } : {}),
       status: 'NEW',
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
@@ -345,8 +466,53 @@ export async function advanceShip(options = {}, injected = {}) {
     await writeJsonAtomic(statePath, state);
   }
 
+  if (state.planPath && Array.isArray(state.selectedUnitIds)) {
+    const frozenPlan = await readFrozenPlanForUnitScope(
+      state.planPath,
+      statePath,
+      state.selectedUnitIds,
+    );
+    assertFrozenPlanUnitScope({
+      statePath,
+      stateUnitIds: state.selectedUnitIds,
+      expectedUnitIds: state.selectedUnitIds,
+      plan: frozenPlan,
+    });
+  }
+
   if (state.status === 'NEW') {
     const loaded = await deps.loadProjectConfig({ root });
+    let stateChanged = false;
+    if (Array.isArray(state.selectedUnitIds)) {
+      const normalizedStateUnitIds = normalizeNewShipUnitIds(
+        loaded.config.releaseUnits,
+        state.selectedUnitIds,
+      );
+      if (!sameUnitSelection(normalizedStateUnitIds, state.selectedUnitIds)) {
+        throw unitScopeMismatch(
+          statePath,
+          state.selectedUnitIds,
+          normalizedStateUnitIds,
+          'ship state release-unit scope no longer matches project configuration',
+        );
+      }
+      if (!sameUnitOrder(normalizedStateUnitIds, state.selectedUnitIds)) {
+        if (state.planPath) {
+          throw unitScopeMismatch(
+            statePath,
+            state.selectedUnitIds,
+            normalizedStateUnitIds,
+            'frozen ship state release-unit order no longer matches project configuration',
+          );
+        }
+        state = {
+          ...state,
+          selectedUnitIds: normalizedStateUnitIds,
+          updatedAt: new Date().toISOString(),
+        };
+        stateChanged = true;
+      }
+    }
     if (loaded.configDigest !== state.configDigest) {
       const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
       state = {
@@ -356,8 +522,9 @@ export async function advanceShip(options = {}, injected = {}) {
         status: 'NEW',
         updatedAt: new Date().toISOString(),
       };
-      await writeJsonAtomic(statePath, state);
+      stateChanged = true;
     }
+    if (stateChanged) await writeJsonAtomic(statePath, state);
     const prepared = await deps.prepareRelease({
       root,
       version: state.targetVersion ?? undefined,
@@ -366,10 +533,24 @@ export async function advanceShip(options = {}, injected = {}) {
       hooksAuthorized: true,
       verificationGatesAuthorized: true,
       hookCache: true,
+      ...(state.selectedUnitIds ? { unitIds: state.selectedUnitIds } : {}),
     });
+    let frozenPlan = null;
+    if (Array.isArray(state.selectedUnitIds) || deps.preflightGitTransports) {
+      frozenPlan = Array.isArray(state.selectedUnitIds)
+        ? await readFrozenPlanForUnitScope(prepared.planPath, statePath, state.selectedUnitIds)
+        : JSON.parse(await readFile(prepared.planPath, 'utf8'));
+    }
+    if (Array.isArray(state.selectedUnitIds)) {
+      assertFrozenPlanUnitScope({
+        statePath,
+        stateUnitIds: state.selectedUnitIds,
+        expectedUnitIds: state.selectedUnitIds,
+        plan: frozenPlan,
+      });
+    }
     let transportPreflight = null;
     if (deps.preflightGitTransports) {
-      const frozenPlan = JSON.parse(await readFile(prepared.planPath, 'utf8'));
       transportPreflight = await deps.preflightGitTransports(frozenPlan);
       process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
     }

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/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,196 @@ 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;
+
+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' || value.length % 4 !== 0) return null;
+  let paddingStart = -1;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 61) {
+      if (paddingStart === -1) paddingStart = index;
+      continue;
+    }
+    if (paddingStart !== -1 || !(
+      code >= 65 && code <= 90
+      || code >= 97 && code <= 122
+      || code >= 48 && code <= 57
+      || code === 43
+      || code === 47
+    )) return null;
+  }
+  if (
+    paddingStart !== -1
+    && value.length - paddingStart > 2
+    || paddingStart !== -1
+    && paddingStart % 4 < 2
+  ) 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 +327,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 +425,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 +469,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 }
+      : {}),
   };
 }