release-skill 0.7.5 → 0.7.7

package/src/commands/prepare.mjs

@@ -25,7 +25,7 @@ import { promisify } from 'node:util';
 
 const execFile = promisify(execFileCb);
 
-import { classifyPathInput } from 'skill-family-harness-node';
+import { classifyPathInput, writeFileAtomic } from 'skill-family-harness-node';
 import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
@@ -62,6 +62,7 @@ import { PKG_ROOT } from '../core/pkg-root.mjs';
 import { writeFrozenMarker, FROZEN_MARKER_FILENAME } from '../core/frozen-marker.mjs';
 import {
   SOURCE_INPUT_ALGORITHM_VERSION,
+  createPublicSourceAuthorityReceipt,
   computeSourceInputClosure,
   checkSourceInputDirty,
   verifySnapshotSourcesMatchClosure,
@@ -80,6 +81,7 @@ import {
   PAYLOAD_SOURCE_TAG_WORKTREE,
 } from '../core/postpublish.mjs';
 import { freezeExecutionBundle, bundleRootForAuthorityDir } from '../core/postpublish-bundle.mjs';
+import { digestReleaseAssetIdentities } from '../core/release-assets.mjs';
 
 // ---------------------------------------------------------------------------
 // 安装契约常量
@@ -247,7 +249,7 @@ export {
 import { boundedOutputTail } from '../core/bounded-output.mjs';
 
 /**
- * Run all declared project hooks in order: docs, build, test, typecheck.
+ * Run all declared project hooks in order: lint, docs, build, test, typecheck.
  *
  * Incremental cache (T3.2): a hook that opts in with `cacheable: true` and a
  * non-empty `cacheInputs` is fingerprinted by its configuration plus the
@@ -286,13 +288,14 @@ import { boundedOutputTail } from '../core/bounded-output.mjs';
  * @throws {ReleaseError} GATE_FAILED if any hook returns a non-zero exit code,
  *   throws, or declares a cacheInputs glob that matches no file.
  */
+export const HOOK_EXECUTION_ORDER = Object.freeze(['lint', 'docs', 'build', 'test', 'typecheck']);
+
 export async function runDeclaredHooks(config, root, evidence, hookFn = runHook, options = {}) {
-  const hookOrder = ['docs', 'build', 'test', 'typecheck'];
   const hooks = config.hooks ?? {};
   const cacheEnabled = options.hookCache !== false;
   const records = [];
 
-  for (const name of hookOrder) {
+  for (const name of HOOK_EXECUTION_ORDER) {
     const hook = hooks[name];
     if (!hook) continue;
 
@@ -1512,7 +1515,7 @@ export async function resolveExternalMarketplaceFreezes({
  * @param {string} realRoot - The project root for relative path calculation.
  * @returns {object[]} Array of external action descriptors.
  */
-export function buildExternalActions(unitResults, resolvedVersions, productionAssets, externalFreezes = new Map(), frozenDistributions = null) {
+export function buildExternalActions(unitResults, resolvedVersions, productionAssets, externalFreezes = new Map(), frozenDistributions = null, publicSourceAuthorityReceipt = null) {
   const actions = [];
 
   if (!productionAssets) {
@@ -1784,6 +1787,9 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
     }
 
     // GitHub release
+    const releaseAssets = publicSourceAuthorityReceipt?.coordinatorUnitId === unit.id
+      ? [publicSourceAuthorityReceipt.asset]
+      : null;
     actions.push({
       id: `github-release-${unit.id}`,
       type: 'github-release',
@@ -1801,10 +1807,12 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
           .replaceAll('{version}', unitVersion)
           .replaceAll('{unit}', unit.id),
         notes: unit.production?.releaseNotes ?? `Release ${resolvedTag}`,
+        ...(releaseAssets ? { releaseAssets } : {}),
       },
       expected: {
         tag: resolvedTag,
         commit: asset.commit,
+        ...(releaseAssets ? { releaseAssetsDigest: digestReleaseAssetIdentities(releaseAssets) } : {}),
       },
       status: 'PENDING',
     });
@@ -3647,7 +3655,68 @@ export async function prepareRelease(options) {
     // 构建冻结分发映射：unitId -> frozen distributions
     const frozenDistributionsMap = new Map(units.map((u) => [u.id, u.distributions]));
 
-    let externalActions = buildExternalActions(unitResults, resolvedVersions, productionAssets, externalMarketplaceFreezes, frozenDistributionsMap);
+    let publicSourceAuthorityReceipt = null;
+    if (config.publicSourceAuthorityReceipt) {
+      if (!production || !sourceAuthority) {
+        throw new ReleaseError(
+          CONFIG_INVALID,
+          'publicSourceAuthorityReceipt requires a production prepare with source-authority closure enabled',
+        );
+      }
+      const unitsById = new Map(units.map((unit) => [unit.id, unit]));
+      const subjects = config.publicSourceAuthorityReceipt.subjectUnitIds.map((unitId) => {
+        const unit = unitsById.get(unitId);
+        const npmDistribution = unit?.distributions?.find((distribution) => distribution.type === 'npm');
+        const npm = unit?.frozenSnapshot?.npm;
+        if (!unit || !npmDistribution || !npm) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `public source-authority subject unit "${unitId}" is missing its frozen npm tarball`,
+          );
+        }
+        return {
+          packageName: npmDistribution.package,
+          version: unit.targetVersion,
+          filename: basename(npm.tarballPath),
+          sha256: npm.tarballSha256,
+        };
+      });
+      const builtReceipt = createPublicSourceAuthorityReceipt({
+        sourceRepository: sourceAuthority.sourceRepository,
+        sourceBaseCommit: baseline.gitHead,
+        subjects,
+      });
+      const assetName = 'source-authority-receipt.json';
+      const assetDirectory = resolve(runDir, 'release-assets');
+      await mkdir(assetDirectory, { recursive: true });
+      await writeFileAtomic(assetDirectory, assetName, builtReceipt.bytes, { mode: 0o644 });
+      publicSourceAuthorityReceipt = {
+        coordinatorUnitId: config.publicSourceAuthorityReceipt.coordinatorUnitId,
+        subjectUnitIds: [...config.publicSourceAuthorityReceipt.subjectUnitIds],
+        asset: {
+          name: assetName,
+          path: relative(realRoot, resolve(assetDirectory, assetName)),
+          sha256: builtReceipt.sha256,
+        },
+      };
+      await evidence.append({
+        phase: 'public-source-authority-receipt',
+        status: 'frozen',
+        coordinatorUnitId: publicSourceAuthorityReceipt.coordinatorUnitId,
+        subjectUnitIds: publicSourceAuthorityReceipt.subjectUnitIds,
+        assetPath: publicSourceAuthorityReceipt.asset.path,
+        assetSha256: publicSourceAuthorityReceipt.asset.sha256,
+      });
+    }
+
+    let externalActions = buildExternalActions(
+      unitResults,
+      resolvedVersions,
+      productionAssets,
+      externalMarketplaceFreezes,
+      frozenDistributionsMap,
+      publicSourceAuthorityReceipt,
+    );
 
     // Compute overall snapshot digest
     const overallSnapshotDigest = sha256Hex(snapshotDigests.join(':'));
@@ -3822,6 +3891,7 @@ export async function prepareRelease(options) {
       } : {}),
       units,
       externalActions,
+      ...(publicSourceAuthorityReceipt ? { publicSourceAuthorityReceipt } : {}),
       ...(frozenPostPublish ? { postPublish: frozenPostPublish } : {}),
       ...(sourceAuthority ? { sourceAuthority } : {}),
       createdAt: production ? createdAtTimestamp : (clock ? clock() : new Date().toISOString()),

package/src/commands/publish.mjs

@@ -61,6 +61,7 @@ import {
   GATE_FAILED,
   CONFIG_MISSING,
   BASELINE_CHANGED,
+  CONTENT_MISMATCH,
   PARTIAL_RELEASE,
   CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
@@ -78,6 +79,7 @@ import {
   verifyFrozenSnapshot,
 } from '../snapshot/frozen.mjs';
 import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
+import { normalizeReleaseAssets } from '../core/release-assets.mjs';
 
 function assertInsideAssetRoot(assetRoot, candidate, label) {
   const rel = relative(assetRoot, candidate);
@@ -608,6 +610,17 @@ export async function publishRelease(options) {
           }, root);
         }
       }
+      for (const action of plan.externalActions ?? []) {
+        for (const releaseAsset of normalizeReleaseAssets(action.parameters?.releaseAssets)) {
+          const verifiedAsset = await verifyFrozenFile({
+            root,
+            filePath: releaseAsset.path,
+            expectedSha256: releaseAsset.sha256,
+            label: `frozen GitHub Release asset "${releaseAsset.name}"`,
+          });
+          assertInsideAssetRoot(assetRoot, verifiedAsset.physical, 'frozen GitHub Release asset');
+        }
+      }
       await evidence.append({ phase: 'safety-gate', gate: 'frozen-artifacts', status: 'passed' });
     }
 
@@ -987,6 +1000,29 @@ export async function publishRelease(options) {
         );
       }
 
+      if (
+        plan.publicSourceAuthorityReceipt
+        && remoteResult.observation?.observedCommit !== plan.baseline.headCommit
+      ) {
+        const observedCommit = remoteResult.observation?.observedCommit ?? null;
+        await evidence.append({
+          phase: 'safety-gate',
+          gate: 'source-authority',
+          status: 'failed',
+          expectedCommit: plan.baseline.headCommit,
+          observedCommit,
+        });
+        throw new ReleaseError(
+          CONTENT_MISMATCH,
+          'source authority commit gate failed: remote observedCommit does not match the public receipt sourceBaseCommit',
+          {
+            gate: 'source-authority',
+            expectedCommit: plan.baseline.headCommit,
+            observedCommit,
+          },
+        );
+      }
+
       // Create receipt for successful verification
       sourceAuthorityReceipt = createSourceAuthorityReceipt({
         plan,

package/src/commands/verify.mjs

@@ -46,7 +46,11 @@ import {
   POST_PUBLISH_VERIFY_FAILED,
   CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
-import { verifySourceAuthorityReceipt } from '../core/source-authority.mjs';
+import {
+  consumePublicSourceAuthorityReceipt,
+  verifySourceAuthorityReceipt,
+} from '../core/source-authority.mjs';
+import { verifyFrozenFile } from '../snapshot/frozen.mjs';
 import {
   deriveBaselineAdvances,
   applyBaselineAdvances,
@@ -61,6 +65,7 @@ import {
   normalizeRegistry,
   registryTokenKey,
   resolveNpmRegistryAuthToken,
+  verifyFrozenNpmTarballContract,
 } from '../adapters/npm.mjs';
 import { runConsumerVerificationGates } from '../core/verification-gates.mjs';
 import {
@@ -109,6 +114,40 @@ export const VERIFICATION_RESOLVED_TYPES = Object.freeze({
   NOT_REQUIRED_UNCHANGED: 'NOT_REQUIRED_UNCHANGED',
 });
 
+/** Re-read every frozen subject tarball before consuming the public receipt. */
+export async function verifyPublicSourceAuthorityReceiptOffline({ plan, root }) {
+  const descriptor = plan.publicSourceAuthorityReceipt;
+  const verifiedAsset = await verifyFrozenFile({
+    root,
+    filePath: descriptor.asset.path,
+    expectedSha256: descriptor.asset.sha256,
+    label: 'public source-authority receipt',
+  });
+  const actualSubjects = [];
+  for (const unitId of descriptor.subjectUnitIds) {
+    const unit = plan.units.find((candidate) => candidate.id === unitId);
+    const npmDistribution = unit?.distributions?.find((distribution) => distribution.type === 'npm');
+    const npm = unit?.frozenSnapshot?.npm;
+    await verifyFrozenNpmTarballContract({
+      package: npmDistribution?.package,
+      version: unit?.targetVersion,
+      tarballPath: npm?.tarballPath,
+      tarballSha256: npm?.tarballSha256,
+      integrity: npm?.integrity,
+    }, root);
+    actualSubjects.push({
+      packageName: npmDistribution.package,
+      version: unit.targetVersion,
+      filename: basename(npm.tarballPath),
+      sha256: npm.tarballSha256,
+    });
+  }
+  return consumePublicSourceAuthorityReceipt(
+    await readFile(verifiedAsset.physical),
+    actualSubjects,
+  );
+}
+
 /**
  * Map plan action type to adapter ActionType.
  * Must match publish.mjs and reconcile.mjs.
@@ -1689,6 +1728,19 @@ export async function verifyRelease(options) {
 
     await evidence.append({ phase: 'verify', step: 'adapter-verify', status: 'completed' });
 
+    if (plan.publicSourceAuthorityReceipt) {
+      const consumed = await verifyPublicSourceAuthorityReceiptOffline({ plan, root });
+      await evidence.append({
+        phase: 'public-source-authority-receipt',
+        status: 'passed',
+        verificationMode: 'offline-consumer',
+        sourceRepository: consumed.sourceRepository,
+        sourceBaseCommit: consumed.sourceBaseCommit,
+        subjectCount: consumed.subjects.length,
+        assetSha256: consumed.sha256,
+      });
+    }
+
     // =======================================================================
     // Step 4: Installation smoke test
     // =======================================================================

package/src/core/config.mjs

@@ -504,6 +504,37 @@ export async function loadProjectConfig({ root, configPath } = {}) {
   // inferred at execution time. A gate must name one existing unit and, for
   // consumer verification, one distribution that the unit actually ships.
   const unitsById = new Map(config.releaseUnits.map((unit) => [unit.id, unit]));
+  const publicReceipt = config.publicSourceAuthorityReceipt;
+  if (publicReceipt) {
+    if (!config.project?.sourceRepository) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        'publicSourceAuthorityReceipt requires project.sourceRepository',
+      );
+    }
+    if (!unitsById.has(publicReceipt.coordinatorUnitId)) {
+      throw new ReleaseError(
+        CONFIG_INVALID,
+        `publicSourceAuthorityReceipt references unknown coordinator unit "${publicReceipt.coordinatorUnitId}"`,
+      );
+    }
+    for (const unitId of publicReceipt.subjectUnitIds) {
+      const unit = unitsById.get(unitId);
+      if (!unit) {
+        throw new ReleaseError(
+          CONFIG_INVALID,
+          `publicSourceAuthorityReceipt references unknown subject unit "${unitId}"`,
+        );
+      }
+      const npmDistributions = (unit.distributions ?? []).filter((distribution) => distribution.type === 'npm');
+      if (npmDistributions.length !== 1) {
+        throw new ReleaseError(
+          CONFIG_INVALID,
+          `publicSourceAuthorityReceipt subject unit "${unitId}" must declare exactly one npm distribution`,
+        );
+      }
+    }
+  }
   const gateIds = new Set();
   for (const gate of config.verificationGates ?? []) {
     if (gateIds.has(gate.id)) {

package/src/core/plan.mjs

@@ -26,6 +26,8 @@ import { canonicalJson, sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
 import { computeInstallationContractDigest, INSTALLATION_CONTRACT_ALGORITHM_VERSION } from './installation-contract.mjs';
+import { createPublicSourceAuthorityReceipt } from './source-authority.mjs';
+import { digestReleaseAssetIdentities, normalizeReleaseAssets } from './release-assets.mjs';
 // NOTE (T2.2 step 3): plan.mjs and the platform registry form a module cycle
 // (plan -> registry -> platforms/kimi -> plan, because the kimi strategies
 // bind computePlanDigest). PLATFORMS is therefore only ever read inside
@@ -450,6 +452,57 @@ export function validatePlanActionCompleteness(plan, options = {}) {
   const units = Array.isArray(plan.units) ? plan.units : [];
   const actions = Array.isArray(plan.externalActions) ? plan.externalActions : [];
   const expectedAdapterMap = buildExpectedAdapterMap();
+  let publicReceiptBinding = null;
+  if (plan.publicSourceAuthorityReceipt) {
+    try {
+      if (plan.production?.mode !== 'github-npm-v1') {
+        failures.push('publicSourceAuthorityReceipt requires a production plan');
+      }
+      if (!plan.sourceAuthority?.sourceRepository || !plan.baseline?.headCommit) {
+        failures.push('publicSourceAuthorityReceipt requires sourceAuthority.sourceRepository and baseline.headCommit');
+      }
+      const descriptor = plan.publicSourceAuthorityReceipt;
+      const coordinator = units.find((unit) => unit.id === descriptor.coordinatorUnitId);
+      if (!coordinator) failures.push(`publicSourceAuthorityReceipt references unknown coordinator unit "${descriptor.coordinatorUnitId}"`);
+      const subjectIds = descriptor.subjectUnitIds ?? [];
+      if (new Set(subjectIds).size !== subjectIds.length) {
+        failures.push('publicSourceAuthorityReceipt subjectUnitIds must be unique');
+      }
+      const subjects = subjectIds.map((unitId) => {
+        const unit = units.find((candidate) => candidate.id === unitId);
+        if (!unit) throw new Error(`unknown subject unit "${unitId}"`);
+        const npmDistributions = (unit.distributions ?? []).filter((distribution) => distribution.type === 'npm');
+        if (npmDistributions.length !== 1 || !unit.frozenSnapshot?.npm) {
+          throw new Error(`subject unit "${unitId}" must bind exactly one frozen npm tarball`);
+        }
+        return {
+          packageName: npmDistributions[0].package,
+          version: unit.targetVersion,
+          filename: basename(unit.frozenSnapshot.npm.tarballPath),
+          sha256: unit.frozenSnapshot.npm.tarballSha256,
+        };
+      });
+      const rebuilt = createPublicSourceAuthorityReceipt({
+        sourceRepository: plan.sourceAuthority?.sourceRepository,
+        sourceBaseCommit: plan.baseline?.headCommit,
+        subjects,
+      });
+      const assets = normalizeReleaseAssets([descriptor.asset]);
+      if (descriptor.asset.name !== 'source-authority-receipt.json') {
+        failures.push('publicSourceAuthorityReceipt asset name must be source-authority-receipt.json');
+      }
+      if (descriptor.asset.sha256 !== rebuilt.sha256) {
+        failures.push('publicSourceAuthorityReceipt asset SHA-256 does not match the mechanically derived receipt bytes');
+      }
+      publicReceiptBinding = {
+        coordinatorUnitId: descriptor.coordinatorUnitId,
+        assets,
+        assetsDigest: digestReleaseAssetIdentities(assets),
+      };
+    } catch (error) {
+      failures.push(`publicSourceAuthorityReceipt is invalid: ${error.message}`);
+    }
+  }
 
   // --- Must have at least one action ---
   if (actions.length === 0) {
@@ -666,6 +719,31 @@ export function validatePlanActionCompleteness(plan, options = {}) {
             _checkRequired(action, 'parameters.notes', action.parameters?.notes, productionConfig.releaseNotes ?? `Release ${expectedTag}`, unitId, failures);
             _checkRequired(action, 'expected.tag', action.expected?.tag, expectedTag, unitId, failures);
             _checkRequired(action, 'expected.commit', action.expected?.commit, frozen?.commit, unitId, failures);
+            if (publicReceiptBinding?.coordinatorUnitId === unitId) {
+              try {
+                const actualAssets = normalizeReleaseAssets(action.parameters?.releaseAssets);
+                if (canonicalJson(actualAssets) !== canonicalJson(publicReceiptBinding.assets)) {
+                  failures.push(`unit "${unitId}", action "${action.id}": parameters.releaseAssets do not match publicSourceAuthorityReceipt.asset`);
+                }
+              } catch (error) {
+                failures.push(`unit "${unitId}", action "${action.id}": invalid parameters.releaseAssets: ${error.message}`);
+              }
+              _checkRequired(
+                action,
+                'expected.releaseAssetsDigest',
+                action.expected?.releaseAssetsDigest,
+                publicReceiptBinding.assetsDigest,
+                unitId,
+                failures,
+              );
+            } else {
+              if (action.parameters?.releaseAssets !== undefined) {
+                failures.push(`unit "${unitId}", action "${action.id}": unexpected parameters.releaseAssets`);
+              }
+              if (action.expected?.releaseAssetsDigest !== undefined) {
+                failures.push(`unit "${unitId}", action "${action.id}": unexpected expected.releaseAssetsDigest`);
+              }
+            }
           }
         }
       }

package/src/core/release-assets.mjs

@@ -0,0 +1,54 @@
+/**
+ * Frozen GitHub Release asset identities.
+ *
+ * This module owns only release-domain mapping: a plan freezes local asset
+ * paths and their already-computed SHA-256 values, while remote observation
+ * reduces the downloaded bytes to the same name/digest identity list.
+ */
+
+import { basename } from 'node:path';
+
+import { canonicalJson, sha256Hex } from './digest.mjs';
+
+const SHA256_RE = /^[a-f0-9]{64}$/u;
+const SAFE_ASSET_NAME_RE = /^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+
+/** Validate and normalize a plan's optional frozen Release assets. */
+export function normalizeReleaseAssets(assets) {
+  if (assets === undefined) return [];
+  if (!Array.isArray(assets) || assets.length === 0) {
+    throw new TypeError('releaseAssets must be a non-empty array when present');
+  }
+  const names = new Set();
+  const normalized = assets.map((asset, index) => {
+    if (!asset || typeof asset !== 'object' || Array.isArray(asset)) {
+      throw new TypeError(`releaseAssets[${index}] must be an object`);
+    }
+    const keys = Object.keys(asset).sort();
+    if (canonicalJson(keys) !== canonicalJson(['name', 'path', 'sha256'])) {
+      throw new TypeError(`releaseAssets[${index}] must contain only name, path, and sha256`);
+    }
+    if (typeof asset.path !== 'string' || asset.path.length === 0) {
+      throw new TypeError(`releaseAssets[${index}].path must be a non-empty project-relative path`);
+    }
+    if (!SAFE_ASSET_NAME_RE.test(asset.name ?? '') || basename(asset.path) !== asset.name) {
+      throw new TypeError(`releaseAssets[${index}].name must be a safe basename matching path`);
+    }
+    if (!SHA256_RE.test(asset.sha256 ?? '')) {
+      throw new TypeError(`releaseAssets[${index}].sha256 must be a lowercase SHA-256 digest`);
+    }
+    if (names.has(asset.name)) {
+      throw new TypeError(`releaseAssets contains duplicate asset name "${asset.name}"`);
+    }
+    names.add(asset.name);
+    return Object.freeze({ name: asset.name, path: asset.path, sha256: asset.sha256 });
+  });
+  normalized.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  return Object.freeze(normalized);
+}
+
+/** Digest only public remote identity, never local paths. */
+export function digestReleaseAssetIdentities(assets) {
+  const identities = normalizeReleaseAssets(assets).map(({ name, sha256 }) => ({ name, sha256 }));
+  return sha256Hex(canonicalJson(identities));
+}

package/src/core/source-authority.mjs

@@ -27,9 +27,115 @@ import {
 const execFile = promisify(execFileCb);
 const REPOSITORY_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/u;
 const GIT_MODE_RE = /^(?:100644|100755)$/u;
+const COMMIT_RE = /^[a-f0-9]{40,64}$/u;
+const SHA256_RE = /^[a-f0-9]{64}$/u;
+const NPM_PACKAGE_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/u;
+const TARBALL_FILENAME_RE = /^(?!\.{1,2}$)[A-Za-z0-9@][A-Za-z0-9._@+-]*\.tgz$/u;
 
 export const SOURCE_INPUT_ALGORITHM_VERSION = 1;
 
+/**
+ * Build the intentionally small public source-authority receipt.
+ *
+ * The receipt is an external release asset. It contains no plan/run fields
+ * and no self digest; the frozen action binds the canonical bytes instead.
+ */
+export function createPublicSourceAuthorityReceipt({
+  sourceRepository,
+  sourceBaseCommit,
+  subjects,
+}) {
+  if (!REPOSITORY_RE.test(sourceRepository ?? '')) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt requires an explicit GitHub owner/repo');
+  }
+  if (!COMMIT_RE.test(sourceBaseCommit ?? '')) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt requires a full hexadecimal source base commit');
+  }
+  if (!Array.isArray(subjects) || subjects.length === 0) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt requires at least one npm tarball subject');
+  }
+  const packageNames = new Set();
+  const normalizedSubjects = subjects.map((subject, index) => {
+    const keys = Object.keys(subject ?? {}).sort();
+    if (canonicalJson(keys) !== canonicalJson(['filename', 'packageName', 'sha256', 'version'])) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject ${index} has an invalid field set`);
+    }
+    if (!NPM_PACKAGE_RE.test(subject.packageName ?? '')) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject ${index} has an invalid packageName`);
+    }
+    if (packageNames.has(subject.packageName)) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority receipt has duplicate packageName "${subject.packageName}"`);
+    }
+    packageNames.add(subject.packageName);
+    if (typeof subject.version !== 'string' || subject.version.length === 0) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject "${subject.packageName}" has an invalid version`);
+    }
+    if (!TARBALL_FILENAME_RE.test(subject.filename ?? '')) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject "${subject.packageName}" has an invalid tarball filename`);
+    }
+    if (!SHA256_RE.test(subject.sha256 ?? '')) {
+      throw new ReleaseError(CONFIG_INVALID, `public source-authority subject "${subject.packageName}" has an invalid SHA-256`);
+    }
+    return {
+      packageName: subject.packageName,
+      version: subject.version,
+      filename: subject.filename,
+      sha256: subject.sha256,
+    };
+  });
+  normalizedSubjects.sort((left, right) => (
+    left.packageName < right.packageName ? -1 : left.packageName > right.packageName ? 1 : 0
+  ));
+  const receipt = {
+    schemaVersion: 1,
+    kind: 'skill-family.source-authority-receipt',
+    sourceRepository,
+    sourceBaseCommit,
+    subjects: normalizedSubjects,
+  };
+  const bytes = Buffer.from(canonicalJson(receipt), 'utf8');
+  return Object.freeze({ receipt: Object.freeze(receipt), bytes, sha256: sha256Hex(bytes) });
+}
+
+/** Parse public bytes and verify them against actual offline tarball facts. */
+export function consumePublicSourceAuthorityReceipt(bytes, actualSubjects) {
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.isBuffer(bytes) ? bytes.toString('utf8') : String(bytes));
+  } catch (error) {
+    throw new ReleaseError(CONFIG_INVALID, `public source-authority receipt is not valid JSON: ${error.message}`);
+  }
+  const topKeys = Object.keys(parsed ?? {}).sort();
+  if (canonicalJson(topKeys) !== canonicalJson([
+    'kind', 'schemaVersion', 'sourceBaseCommit', 'sourceRepository', 'subjects',
+  ])) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt has an invalid field set');
+  }
+  if (parsed.schemaVersion !== 1 || parsed.kind !== 'skill-family.source-authority-receipt') {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt kind or schemaVersion is unsupported');
+  }
+  const rebuilt = createPublicSourceAuthorityReceipt(parsed);
+  if (!Buffer.from(bytes).equals(rebuilt.bytes)) {
+    throw new ReleaseError(CONFIG_INVALID, 'public source-authority receipt bytes are not canonical JSON');
+  }
+  if (actualSubjects !== undefined) {
+    const actual = createPublicSourceAuthorityReceipt({
+      sourceRepository: parsed.sourceRepository,
+      sourceBaseCommit: parsed.sourceBaseCommit,
+      subjects: actualSubjects,
+    }).receipt.subjects;
+    if (canonicalJson(actual) !== canonicalJson(rebuilt.receipt.subjects)) {
+      throw new ReleaseError(CONTENT_MISMATCH, 'public source-authority receipt subjects do not match actual tarballs');
+    }
+  }
+  return Object.freeze({
+    sourceRepository: rebuilt.receipt.sourceRepository,
+    sourceBaseCommit: rebuilt.receipt.sourceBaseCommit,
+    subjects: rebuilt.receipt.subjects,
+    sha256: rebuilt.sha256,
+  });
+}
+
 /**
  * Compute the deterministic source-input closure for release units.
  *
@@ -325,6 +431,7 @@ async function verifyWithInjectedReader({
   sourceRepository,
 }) {
   const mismatchedPaths = [];
+  let observedCommit;
   for (const entry of closure.entries) {
     let result;
     try {
@@ -334,6 +441,12 @@ async function verifyWithInjectedReader({
     }
     const classified = classifyRemoteStatus(result, sourceRepository, defaultBranch);
     if (classified) return classified;
+    if (result.observedCommit !== undefined) {
+      if (observedCommit !== undefined && observedCommit !== result.observedCommit) {
+        return failure(REMOTE_UNAVAILABLE, 'remote source reader returned inconsistent observed commits');
+      }
+      observedCommit = result.observedCommit;
+    }
     if (
       sha256Hex(Buffer.isBuffer(result.content) ? result.content : Buffer.from(result.content))
         !== entry.digest
@@ -349,6 +462,7 @@ async function verifyWithInjectedReader({
         observation: {
           defaultBranch,
           entryCount: closure.entries.length,
+          ...(observedCommit ? { observedCommit } : {}),
           sourceRepository,
         },
       };
@@ -515,12 +629,22 @@ export function verifySourceAuthorityReceipt({ plan, run }) {
     && receipt.planDigest === plan.digest
     && receipt.result === 'CONSISTENT'
   ));
-  return matching
-    ? { passed: true, receipt: matching }
-    : {
+  if (!matching) {
+    return {
         passed: false,
         reason: 'publish run has no CONSISTENT source-authority receipt bound to this plan digest',
       };
+  }
+  if (
+    plan.publicSourceAuthorityReceipt
+    && matching.observedCommit !== plan.baseline?.headCommit
+  ) {
+    return {
+      passed: false,
+      reason: 'publish source-authority receipt observedCommit does not match the public receipt sourceBaseCommit',
+    };
+  }
+  return { passed: true, receipt: matching };
 }
 
 /** Create the digest-bound receipt persisted by publish. */

package/src/producers/build-adapters.mjs

@@ -317,7 +317,7 @@ async function collectSkills(srcDir, physicalRoot) {
 const CODEX_PREAMBLE = `\
 > **Codex 安装入口解析协议**：在调用 CLI 前，Agent 必须从宿主当前已加载技能的元数据中取得本 \`SKILL.md\` 的实际绝对路径，并将该字面量记为 \`SKILL_FILE\`。\n\
 > \`SKILL_FILE\` 不是环境变量；禁止从工作目录、可执行搜索路径、源码仓库或 shell 调用上下文猜测。若宿主未提供该绝对路径，立即停止并报告安装定位失败。\n\
-> 对 \`SKILL_FILE\` 执行 \`realpath\`，取其目录向上两级得到 \`PLUGIN_ROOT\`；校验真实技能路径匹配 \`PLUGIN_ROOT/skills/*/SKILL.md\`。\n\
+> 对 \`SKILL_FILE\` 执行 \`realpath\`，取其目录向上两级得到 \`PLUGIN_ROOT\`；校验真实技能路径匹配 \`PLUGIN_ROOT/skills/*/SKILL.md\` 且仍位于插件根内（路径包含检查）。\n\
 > 令 \`RELEASE_SKILL_ENTRY=PLUGIN_ROOT/bin/release-skill.mjs\`，对入口执行 \`realpath\` containment、\`lstat\` 非符号链接且为普通文件校验。\n\
 > 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 \`RELEASE_SKILL_ENTRY\`，然后执行 \`node "$RELEASE_SKILL_ENTRY" ...\`；不得依赖前一次 shell 的变量。\n\
 >\n\