release-skill 0.9.1 → 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

@@ -315,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;
   }

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,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 }
+      : {}),
   };
 }