release-skill 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/schemas/.render-manifest.json

@@ -26,8 +26,8 @@
       "bytes": 35256
     },
     "release-project.schema.json": {
-      "digest": "a3d46be1e1e8105103a505c6d58d14f3733c8da91ab8289e097ffd259bf1cd93",
-      "bytes": 30982
+      "digest": "7ac18070ac41327a330ca35e32f466e3f2a8eb2b7df3a5755568e00f991ffdc1",
+      "bytes": 32497
     },
     "release-run.schema.json": {
       "digest": "bf3c8fb4ca2fc078272a45a6ee6bf663fd2420a722b2f995dbaabf2635e2179e",

package/schemas/release-project.schema.json

@@ -455,6 +455,9 @@
               ]
             }
           },
+          "expectedPublicSurface": {
+            "$ref": "#/definitions/expectedPublicSurface"
+          },
           "publicFiles": {
             "type": "array",
             "minItems": 1,
@@ -761,6 +764,63 @@
     }
   },
   "definitions": {
+    "expectedPublicSurface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scanRoots"
+      ],
+      "properties": {
+        "scanRoots": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/publicSurfaceScanRoot"
+          }
+        }
+      }
+    },
+    "publicSurfaceScanRoot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "include",
+        "exclude"
+      ],
+      "properties": {
+        "sourceScope": {
+          "type": "string",
+          "enum": [
+            "unit",
+            "workspace"
+          ],
+          "default": "unit"
+        },
+        "root": {
+          "type": "string",
+          "minLength": 1,
+          "default": ".",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$"
+        },
+        "include": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "exclude": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
     "hook": {
       "type": "object",
       "required": [

package/skills/release-prepare/SKILL.md

@@ -36,6 +36,10 @@ description: Freeze an immutable release plan with local configuration, document
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
+每个 npm tarball 在计划落盘前必须静态验证 `package.json` 的具体
+`bin`/`main`/`module`/`types`/`typings`/`exports` 入口均为 tarball 内普通文件；
+该门禁不依赖项目是否配置 `requiredPublicFiles` 或 `smokeBin`。通配符 exports 不做
+猜测展开；它与 fallback array 都属于首版最小边界外的阻断形态。
 每个 release unit 必须显式配置 `previousPublicBaseline`。只有确认不存在前序公开
 版本时用 `mode: none`；已有版本必须用 `mode: bound` + 精确 repo/ref/commit，并以
 `--online --production` 逐 unit 观察 ref→commit mapping。默认 observer 不下载远端
@@ -79,6 +83,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 | GATE_FAILED (gate 授权) | 向用户展示 snapshot gate 命令和风险，获得授权后加 `--acknowledge-gate-side-effects` 重试 |
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
+| GATE_FAILED (`npm-entry-closure`) | 修复打包内容或入口声明后重新 prepare；不得用 `requiredPublicFiles`/`smokeBin` 缺省绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |

package/skills/release-setup/SKILL.md

@@ -14,6 +14,9 @@ description: "首次接入 release-skill：只读发现发布单元与个性化
 - 默认只读。README、slogan、CHANGELOG、业务脚本和已有配置均为人工权威内容，不得重写或覆盖。
 - 发现脚本不等于选择或授权。间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除；项目特有 hook/gate 只能人工增量注册。
 - 仓库、公开文件等证据冲突时停止自动提案，交给人工修正权威事实后重新发现。
+- npm 单元只读提取 `package.json` 的具体入口和旧 `npmRequiredPackagePaths`，报告
+  tracked/untracked/ignored/missing/non-regular 状态与覆盖漂移；这些是人工复核候选，
+  不得自动写入 `publicFiles` 或 `requiredPublicFiles`。
 - 写入只允许 create-once（仅创建一次），必须同时提供 answers 与精确 `setupDigest`；无安全原生写入能力时失败关闭。
 - Agent 的多次 shell 调用彼此独立；只能用首轮打印的会话目录绝对路径续接，不得假设变量仍存在。
 
@@ -43,7 +46,13 @@ node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.
 node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
 ```
 
-若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实，删除本会话目录后从第 2 步重跑，不得猜测选边。无冲突时可人工增量编辑 `answers.json`：hook 写入 `recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入 `verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持 `mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
+若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实或 npm 入口候选，
+删除本会话目录后从第 2 步重跑，不得猜测选边。构建后才产生且被忽略的入口应先由
+人工确认构建流程与最终 tarball 边界，不能因为 setup 发现了路径就自动信任或纳入公开
+配置。无冲突时可人工增量编辑 `answers.json`：hook 写入
+`recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入
+`verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持
+`mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
 
 3. 使用上一步打印的两个绝对字面量重新赋值，运行绑定 dry-run；任何人工编辑后都必须重跑本步：
 

package/skills/release-verify/SKILL.md

@@ -17,7 +17,7 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 
 ## 职责与边界
 
-验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
+验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
 
 **阶段通过规则**: 只有 CLI exit code 0 和结构化状态码 `VERIFIED` 才是完整终态。
 
@@ -55,8 +55,10 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <
 - 在 `os.tmpdir()` 创建隔离目录
 - 执行 `npm install <package>@<version>` 带安全标志
 - 验证安装的 `package.json` name 和 version 精确匹配
+- 无条件静态验证已安装包中具体 `bin`/`main`/`module`/`types`/`typings`/`exports`
+  目标是普通文件；失败时不得写入 `VERIFIED`
 - 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），从精确安装根、隔离 HOME 和最小环境执行并验证输出；这会运行已安装代码，必须显式授权
-- 若未配置 `smokeBin`：仅安装 + name/version 检查即通过
+- 若未配置 `smokeBin`：跳过运行代码，但静态入口闭包检查仍然强制执行
 
 ## 常见错误
 

package/skills-src/release-prepare/SKILL.md

@@ -36,6 +36,10 @@ description: Freeze an immutable release plan with local configuration, document
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
+每个 npm tarball 在计划落盘前必须静态验证 `package.json` 的具体
+`bin`/`main`/`module`/`types`/`typings`/`exports` 入口均为 tarball 内普通文件；
+该门禁不依赖项目是否配置 `requiredPublicFiles` 或 `smokeBin`。通配符 exports 不做
+猜测展开；它与 fallback array 都属于首版最小边界外的阻断形态。
 每个 release unit 必须显式配置 `previousPublicBaseline`。只有确认不存在前序公开
 版本时用 `mode: none`；已有版本必须用 `mode: bound` + 精确 repo/ref/commit，并以
 `--online --production` 逐 unit 观察 ref→commit mapping。默认 observer 不下载远端
@@ -79,6 +83,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 | GATE_FAILED (gate 授权) | 向用户展示 snapshot gate 命令和风险，获得授权后加 `--acknowledge-gate-side-effects` 重试 |
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
+| GATE_FAILED (`npm-entry-closure`) | 修复打包内容或入口声明后重新 prepare；不得用 `requiredPublicFiles`/`smokeBin` 缺省绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |

package/skills-src/release-setup/SKILL.md

@@ -14,6 +14,9 @@ description: "首次接入 release-skill：只读发现发布单元与个性化
 - 默认只读。README、slogan、CHANGELOG、业务脚本和已有配置均为人工权威内容，不得重写或覆盖。
 - 发现脚本不等于选择或授权。间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除；项目特有 hook/gate 只能人工增量注册。
 - 仓库、公开文件等证据冲突时停止自动提案，交给人工修正权威事实后重新发现。
+- npm 单元只读提取 `package.json` 的具体入口和旧 `npmRequiredPackagePaths`，报告
+  tracked/untracked/ignored/missing/non-regular 状态与覆盖漂移；这些是人工复核候选，
+  不得自动写入 `publicFiles` 或 `requiredPublicFiles`。
 - 写入只允许 create-once（仅创建一次），必须同时提供 answers 与精确 `setupDigest`；无安全原生写入能力时失败关闭。
 - Agent 的多次 shell 调用彼此独立；只能用首轮打印的会话目录绝对路径续接，不得假设变量仍存在。
 
@@ -43,7 +46,13 @@ node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.
 node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
 ```
 
-若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实，删除本会话目录后从第 2 步重跑，不得猜测选边。无冲突时可人工增量编辑 `answers.json`：hook 写入 `recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入 `verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持 `mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
+若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实或 npm 入口候选，
+删除本会话目录后从第 2 步重跑，不得猜测选边。构建后才产生且被忽略的入口应先由
+人工确认构建流程与最终 tarball 边界，不能因为 setup 发现了路径就自动信任或纳入公开
+配置。无冲突时可人工增量编辑 `answers.json`：hook 写入
+`recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入
+`verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持
+`mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
 
 3. 使用上一步打印的两个绝对字面量重新赋值，运行绑定 dry-run；任何人工编辑后都必须重跑本步：
 

package/skills-src/release-verify/SKILL.md

@@ -17,7 +17,7 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 
 ## 职责与边界
 
-验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
+验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
 
 **阶段通过规则**: 只有 CLI exit code 0 和结构化状态码 `VERIFIED` 才是完整终态。
 
@@ -55,8 +55,10 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <
 - 在 `os.tmpdir()` 创建隔离目录
 - 执行 `npm install <package>@<version>` 带安全标志
 - 验证安装的 `package.json` name 和 version 精确匹配
+- 无条件静态验证已安装包中具体 `bin`/`main`/`module`/`types`/`typings`/`exports`
+  目标是普通文件；失败时不得写入 `VERIFIED`
 - 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），从精确安装根、隔离 HOME 和最小环境执行并验证输出；这会运行已安装代码，必须显式授权
-- 若未配置 `smokeBin`：仅安装 + name/version 检查即通过
+- 若未配置 `smokeBin`：跳过运行代码，但静态入口闭包检查仍然强制执行
 
 ## 常见错误
 

package/src/adapters/npm.mjs

@@ -16,6 +16,11 @@ import {
   createResult,
   matchObservation,
 } from './contract.mjs';
+import {
+  checkNpmEntryClosure,
+  buildTarballFileIndex,
+} from '../npm/npm-entry-closure.mjs';
+import { ReleaseError, GATE_FAILED } from '../core/errors.mjs';
 
 const execFile = promisify(execFileCb);
 const NAME = 'npm';
@@ -349,6 +354,53 @@ export async function verifyFrozenNpmTarballIdentity(action, root) {
   });
 }
 
+async function verifyNpmTarballBufferContract(buffer, action, tarballDir) {
+  const manifest = extractManifestFromTarball(buffer, {
+    name: action.package,
+    version: action.version,
+  });
+  const fileIndex = await buildTarballFileIndex(buffer, tarballDir);
+  const closureResult = checkNpmEntryClosure(manifest, fileIndex);
+  if (closureResult.errors.length > 0) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `npm entry closure check failed for ${action.package}@${action.version}: ${closureResult.errors.length} error(s)`,
+      {
+        gate: 'npm-entry-closure',
+        package: action.package,
+        version: action.version,
+        entries: closureResult.entries,
+        errors: closureResult.errors,
+        diagnostics: closureResult.diagnostics,
+      },
+    );
+  }
+  return { manifest, closureResult };
+}
+
+/**
+ * Shared frozen tarball contract helper: reads the verified tarball bytes ONCE
+ * and performs both identity verification (name/version from manifest) and
+ * entry closure validation (bin/main/module/types/typings/exports targets
+ * exist as regular files inside the tarball).
+ *
+ * The same Buffer that passes `readVerifiedTarballBytes` is reused for both
+ * the existing identity reader and the controlled extraction/file-index
+ * boundary. This adds no new tar parser and performs no second source read.
+ *
+ * @param {object} action - The frozen action with tarballPath, tarballSha256,
+ *   integrity, package, and version.
+ * @param {string} root - Absolute project root.
+ * @param {string} [tarballDir] - Temp directory for tar extraction (defaults to os.tmpdir()).
+ * @returns {Promise<{ manifest: object, closureResult: object }>}
+ * @throws {ReleaseError} GATE_FAILED with details.gate='npm-entry-closure'
+ *   when any declared entry is missing or invalid.
+ */
+export async function verifyFrozenNpmTarballContract(action, root, tarballDir) {
+  const buffer = await readVerifiedTarballBytes(action, root);
+  return verifyNpmTarballBufferContract(buffer, action, tarballDir);
+}
+
 /**
  * Read and verify the frozen tarball, then write it to a controlled named
  * temp file under a temp directory adjacent to the source. Returns the temp
@@ -700,7 +752,7 @@ export function createNpmAdapter(deps = {}) {
           }
           const cwd = resolvePackageCwd(action.cwd, context.root);
           if (action.tarballPath) {
-            await verifyFrozenNpmTarballIdentity(action, context.root);
+            await verifyFrozenNpmTarballContract(action, context.root);
           }
 
           let whoamiUser;
@@ -775,7 +827,7 @@ export function createNpmAdapter(deps = {}) {
             throw new Error('frozen npm tarball requires a stable Buffer publish capability');
           }
           const buffer = await readVerifiedTarballBytes(action, context.root);
-          const manifest = extractManifestFromTarball(buffer, { name: action.package, version: action.version });
+          const { manifest } = await verifyNpmTarballBufferContract(buffer, action);
           let token;
           try {
             token = await resolveAuthToken({ registry: normalizedRegistry, cwd, exec, env: authEnv });

package/src/adapters/plugin-marketplace.mjs

@@ -2393,7 +2393,7 @@ export function createPluginMarketplaceAdapter(deps = {}) {
 
           // A non-automatable platform (kimi) has NO scriptable install CLI.
           // It is handled entirely by its manual-requirement strategy, which
-          // uses a stable plan-digest-keyed home and deliberately SKIPS the
+          // uses a stable plugin-level authority directory and deliberately SKIPS the
           // per-run isolated consumer dir and its runDir containment check
           // (that model only fits structured-cli platforms, which exec a real
           // CLI into a per-run HOME).
@@ -2913,25 +2913,12 @@ export function createPluginMarketplaceAdapter(deps = {}) {
               });
             }
 
-            // installPath 验证：必须在 managed root 内，不得逃逸，不得是符号链接
+            // installPath 验证：必须是真实目录，不得是符号链接。
+            // 安装路径不要求位于 attestationDir 内（用户使用实际全局/用户安装目录）。
             let verifiedInstallPath = null;
             if (normalizedAttestation.installPath) {
-              const managedRoot = resolve(attestationDir, 'kimi-home', 'plugins', 'managed');
               const installPathAbs = resolve(normalizedAttestation.installPath);
 
-              // 先验证 managed root 存在（KIMI_CODE_HOME 检查）
-              const managedRootReal = await realpath(managedRoot).catch(() => null);
-              if (!managedRootReal) {
-                return createResult({
-                  actionType,
-                  status: ActionStatus.OBSERVED,
-                  observation: {
-                    installed: false,
-                    error: 'KIMI_CODE_HOME does not exist',
-                  },
-                });
-              }
-
               // 检查 installPath 词法路径是否存在（lstat 在 realpath 之前）
               let lexicalStat;
               try {
@@ -2968,18 +2955,6 @@ export function createPluginMarketplaceAdapter(deps = {}) {
                   },
                 });
               }
-              const rel = relative(managedRootReal, installPathReal);
-              const sep = process.platform === 'win32' ? '\\' : '/';
-              if (rel === '' || rel === '..' || isAbsolute(rel) || rel.startsWith(`..${sep}`)) {
-                return createResult({
-                  actionType,
-                  status: ActionStatus.OBSERVED,
-                  observation: {
-                    installed: false,
-                    error: `kimi attestation installPath escapes the managed root: ${normalizedAttestation.installPath}`,
-                  },
-                });
-              }
               verifiedInstallPath = installPathReal;
             }
 
@@ -3283,7 +3258,7 @@ export function createPluginMarketplaceAdapter(deps = {}) {
                 try {
                   codexRequirement = JSON.parse(await readFile(resolve(codexAttestationDir, CODEX_REQUIREMENT_FILE), 'utf8'));
                 } catch {
-                  // No requirement file — must not read isolated attestation
+                  // No requirement file — must not read the stable attestation
                 }
 
                 // Validate requirement binds to this action and plan (完整绑定验证)

package/src/commands/prepare.mjs

@@ -29,6 +29,7 @@ import { loadProjectConfig } from '../core/config.mjs';
 import { captureBaseline } from '../core/baseline.mjs';
 import { runHook } from '../core/hooks.mjs';
 import { computeHookCacheKey, readHookCache, writeHookCache } from '../core/hook-cache.mjs';
+import { assertExpectedPublicSurface } from '../core/public-surface.mjs';
 import { runSnapshotVerificationGates } from '../core/verification-gates.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { computePlanDigest, writePlanAtomic, writePlanImmutable } from '../core/plan.mjs';
@@ -58,7 +59,7 @@ import {
 } from '../core/source-authority.mjs';
 import { acquireProjectLock } from '../artifacts/project-lock.mjs';
 import { assertPreviousPublicBaselineTarget, observePreviousPublicBaseline } from '../core/previous-public-baseline.mjs';
-import { verifyFrozenNpmTarballIdentity } from '../adapters/npm.mjs';
+import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 import { createProductionPrepareRunDir } from '../core/run.mjs';
 import { PLATFORMS } from '../platforms/registry.mjs';
 import { validateMarketplaceSourceSelection, MARKETPLACE_SOURCE_TYPES, resolvePluginManifestFromMarketplaceEntrySource, resolveMarketplaceRoot } from '../adapters/plugin-marketplace.mjs';
@@ -930,13 +931,13 @@ async function buildProductionAssets(
         tarballDir: resolveUnitScopedPath(resolve(runDir, 'tarballs'), unit.id),
         expectedSnapshotDigest: sealed.digest,
       });
-      await verifyFrozenNpmTarballIdentity({
+      await verifyFrozenNpmTarballContract({
         package: npmDistribution.package,
         version,
         tarballPath: relative(root, npm.tarballPath),
         tarballSha256: npm.sha256,
         integrity: npm.integrity,
-      }, root);
+      }, root, resolveUnitScopedPath(resolve(runDir, 'tarballs'), unit.id));
     }
 
     assets.push({
@@ -1925,6 +1926,51 @@ export async function prepareRelease(options) {
       });
     }
 
+    // --- Step 3b.1: Validate the post-build expected public surface ---
+    // This gate runs after every declared hook (and the post-hook docs check)
+    // but before source-authority closure, baseline, snapshots, remote reads,
+    // and plan write. Therefore build-generated files must be explicitly
+    // classified and every included source must already exist in publicFiles
+    // before downstream authorities bind the release inputs.
+    for (const unit of configUnits) {
+      if (!unit?.expectedPublicSurface) continue;
+      await evidence.append({
+        phase: 'public-surface',
+        status: 'started',
+        unitId: unit.id,
+      });
+      try {
+        const surface = await assertExpectedPublicSurface({
+          root: realRoot,
+          unit,
+        });
+        await evidence.append({
+          phase: 'public-surface',
+          status: 'completed',
+          unitId: unit.id,
+          ...surface.summary,
+        });
+      } catch (error) {
+        await evidence.append({
+          phase: 'public-surface',
+          status: 'failed',
+          unitId: unit.id,
+          reason: error.details?.reason ?? 'PUBLIC_SURFACE_CHECK_FAILED',
+          error: {
+            code: error.code,
+            message: error.message,
+          },
+          diagnostics: {
+            missingMappings: error.details?.missingMappings ?? [],
+            unexpectedMappings: error.details?.unexpectedMappings ?? [],
+            unclassifiedFiles: error.details?.unclassifiedFiles ?? [],
+            ambiguousFiles: error.details?.ambiguousFiles ?? [],
+          },
+        });
+        throw error;
+      }
+    }
+
     // --- Step 3c: Source authority content closure gate ---
     // After hooks complete, compute the deterministic source-input closure
     // and verify that closure inputs are clean (no staged/unstaged/untracked

package/src/commands/publish.mjs

@@ -77,7 +77,7 @@ import {
   verifyFrozenGitRepository,
   verifyFrozenSnapshot,
 } from '../snapshot/frozen.mjs';
-import { verifyFrozenNpmTarballIdentity } from '../adapters/npm.mjs';
+import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 
 function assertInsideAssetRoot(assetRoot, candidate, label) {
   const rel = relative(assetRoot, candidate);
@@ -607,7 +607,7 @@ export async function publishRelease(options) {
           if (!npmDistribution) {
             throw new ReleaseError(GATE_FAILED, `unit "${unit.id}" has a frozen npm tarball but no npm distribution`);
           }
-          await verifyFrozenNpmTarballIdentity({
+          await verifyFrozenNpmTarballContract({
             package: npmDistribution.package,
             version: unit.targetVersion,
             tarballPath: frozen.npm.tarballPath,

package/src/commands/reconcile.mjs

@@ -62,6 +62,7 @@ import { assertTransition, PARTIAL, PUBLISHED, BLOCKED } from '../core/state-mac
 import { verifySourceAuthorityReceipt } from '../core/source-authority.mjs';
 import { matchObservation } from '../adapters/contract.mjs';
 import { observeWithRetry, clampPolicyToTimeout, DEFAULT_OBSERVE_RETRY_POLICY } from '../core/observe-retry.mjs';
+import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -210,6 +211,44 @@ export async function reconcileRelease(options) {
 
     await evidence.append({ phase: 'safety-gate', gate: 'action-completeness', status: 'passed' });
 
+    // =======================================================================
+    // Safety Gate 2c: Unconditional frozen npm entry-closure recheck
+    // This is plan-global and intentionally precedes source-run observation:
+    // a previously consistent npm checkpoint must not exempt a bad frozen
+    // tarball while another action is being reconciled.
+    // =======================================================================
+    for (const unit of plan.units ?? []) {
+      const frozen = unit.frozenSnapshot;
+      if (!frozen?.npm) continue;
+      const npmDistribution = (unit.distributions ?? []).find((distribution) => distribution.type === 'npm');
+      if (!npmDistribution) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" has a frozen npm tarball but no npm distribution`,
+          { gate: 'npm-entry-closure', unitId: unit.id },
+        );
+      }
+      await evidence.append({
+        phase: 'safety-gate',
+        gate: 'npm-entry-closure',
+        unitId: unit.id,
+        status: 'started',
+      });
+      await verifyFrozenNpmTarballContract({
+        package: npmDistribution.package,
+        version: unit.targetVersion,
+        tarballPath: frozen.npm.tarballPath,
+        tarballSha256: frozen.npm.tarballSha256,
+        integrity: frozen.npm.integrity,
+      }, root);
+      await evidence.append({
+        phase: 'safety-gate',
+        gate: 'npm-entry-closure',
+        unitId: unit.id,
+        status: 'passed',
+      });
+    }
+
     // =======================================================================
     // Safety Gate 3: Load and validate source run
     // =======================================================================