core: `PHASE2_IMPLEMENTATION.md` teaches `@objectstack/core/security`, a subpath the package exports in no entry

[zhuangjianguo]

Found while retiring PluginSecurityScanner (#14919, PR #15930). Out of scope there: the two repairs differ in whether they widen the published contract, which is not an implementing lane's call.

The reading

packages/core/package.json declares exactly two exports entries:

"exports": {
  ".":        { "types": "./dist/index.d.ts",  "import": "./dist/index.js",  "require": "./dist/index.cjs" },
  "./logger": { "types": "./dist/logger.d.ts", "import": "./dist/logger.js", "require": "./dist/logger.cjs" }
}

There is no ./security entry and no wildcard, so under Node's exports resolution the specifier @objectstack/core/security resolves for no consumer of the published package — it is refused outright, not merely untyped.

packages/core/PHASE2_IMPLEMENTATION.md nevertheless tells readers to import from it, twice, in the two sections that survive #14919:

line	section	statement
161	4. Permission Manager	import { PluginPermissionManager } from '@objectstack/core/security';
219	5. Sandbox Runtime	import { PluginSandboxRuntime } from '@objectstack/core/security';

Both classes are real and both are exported — from the root barrel, reached by export * from './security/index.js' in packages/core/src/index.ts. So the symbols exist and only the path is wrong, which is the failure mode that reads as working code right up to the resolution error.

A third occurrence, in the retired scanner section, was removed by #14919. This issue is the residue: that PR deleted the section it owned and deliberately did not touch these two.

Why it is not caught today

check:published-readme-exports is the gate that reads documented imports against a package's built type surface, and it is green. PHASE2_IMPLEMENTATION.md is not among the 60 documents it reads, because packages/core/package.json sets files: ["dist", "README.md", "CHANGELOG.md"] — the document ships in the git repository but not in the npm tarball, so it is outside that gate's published-document population. The claims are therefore visible to every reader browsing the repo and invisible to every gate.

Two repairs, and why the choice is not mechanical

1. Declare the subpath. Add a ./security entry to exports (and a dist/security.* build target). This widens the published contract: it makes @objectstack/core/security a supported entry point that must then be kept stable, and it publishes the whole security barrel as a named surface.
2. Repoint the document at the root barrel. Rewrite both import lines to from '@objectstack/core'. No contract change; the document becomes true immediately.

(2) is the smaller and probably correct move — nothing in the tree imports the subpath, so there is no evidence of demand for (1). But (1) is a real option if the security surface is meant to be separately importable, and choosing between them is a maintainer decision about the published surface.

Acceptance

Whichever route: no shipped document names an import specifier that packages/core/package.json cannot resolve. Worth considering as part of the fix — a gate that reads documented @objectstack/* import specifiers against the target package's own exports map, which is a different question from the one check:published-readme-exports asks (it checks the symbol against the built types, not the specifier against the exports map) and would have caught all three occurrences.

[os-zhuang]

分诊：domain:engine / bug + documentation / pm:queue / priority:p3

落点核实（origin/main，本轮实读）

packages/core/package.json  exports keys: ['.', './logger']        ← 无 './security'，无通配
packages/core/package.json  files: ['dist', 'README.md', 'CHANGELOG.md']
packages/core/PHASE2_IMPLEMENTATION.md:161  import { PluginPermissionManager } from '@objectstack/core/security';
packages/core/PHASE2_IMPLEMENTATION.md:219  import { PluginSandboxRuntime } from '@objectstack/core/security';
packages/core/src/index.ts:44               export * from './security/index.js';        ← 符号确在根 barrel

卡片逐条零错，包括它最关键的那一句：符号存在，只有路径错——这正是「读起来像能跑的代码，直到解析报错为止」的失败形态。

而 files 不含 PHASE2_IMPLEMENTATION.md，⇒ 卡片对「为什么门看不见」的解释也成立：check:published-readme-exports 的总体是已发布文档，这份文档进 git 仓不进 npm 包 ⇒ 对每个浏览仓库的读者可见，对每道门不可见。

---

⚠️ 本席不按卡片的建议挂决定箱，理由如下

卡片写："choosing between them is a maintainer decision about the published surface." 本席判定这不是决定箱，路由 pm:queue，交付物是支 (2)。

判据是卡片自己给出的、且本席复核成立的那一句：

(2) is the smaller and probably correct move — nothing in the tree imports the subpath, so there is no evidence of demand for (1).

⇒ 两支不是对称的分叉：

• 支 (2)（把文档指回根 barrel）不改变任何契约，只是让一份今天为假的文档变真。它是缺省动作——没有它，一份文档会继续教读者写一个解析不了的 specifier。
• 支 (1)（新增 ./security 导出条目）是一次主动的已发布面拓宽，需要新的构建目标、新的稳定性承诺，而今天没有任何需求证据（树内零导入）。

⇒ 决定箱的判据是「两支都有活证据、且无法在不裁决的情况下前进」。这里支 (2) 可以立刻前进，且不排除将来做支 (1)。把一份可以一行修好的假文档停在决定箱里，代价大于收益。

⛔ 但本席把这个判断公开写在这里，正是为了让它可被推翻：若有人确实希望 @objectstack/core/security 成为受支持的入口点，那是一张单独的 enhancement 卡（已发布面拓宽 + 人工地板），⛔ 不要在本卡的 PR 里顺手加导出条目。

定级理由

• domain:engine：packages/core 按 lane 表归 domain:engine。
• bug + documentation：文档断言了一个 packages/core/package.json 解析不了的 import specifier ⇒ main 上有东西是假的。支 (2) 的修复不拓宽任何接受集 ⇒ Bug/tidy 侧，无人工地板。
• p3：这份文档不随包发运（files 已核），所以 npm 读者碰不到它；受影响的是浏览仓库的读者。⛔ 不升 p2：无运行期后果、无发运制品受损。⛔ 不降更低：这是 packages/core/examples/phase2-integration.ts is the sole composer of PluginSecurityScanner, which FOLLOW-UPS.md already records as exported dead code with 3 of 5 scan methods empty stubs — repair it, or retire it as #4939 did to its neighbour? #14919 明确留下的已知残留（那个 PR 删掉了它自己拥有的第三处，刻意没碰这两处），残留不该无限期存放。

⭐ 卡片的 Acceptance 一节，本席提为必做而非「worth considering」

a gate that reads documented @objectstack/* import specifiers against the target package's own exports map, which is a different question from the one check:published-readme-exports asks (it checks the symbol against the built types, not the specifier against the exports map) and would have caught all three occurrences.

⭐ 这一段把两道门的问题差异说得很准：现有门问「这个符号在构建出的类型里吗」，而本缺陷需要问「这个路径在 exports 图里吗」。符号在、路径不在，正是本卡的形状——所以现有门结构性地答不了它，这不是它的覆盖面不够，是它问的问题不同。

⚠️ 但这是第二张卡，⛔ 不要塞进本卡的 PR。 理由：新建一道门需要自己的总体计数（要扫哪些文档？files 之外的也扫吗？扫到多少个假阳性？）与自己的 pin。⇒ 本卡交付支 (2)（两行文档），门另立。若承接席愿意顺手开那张卡，请在本卡回链卡号。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code

[claude]

Dispatch · domain:engine execution round

PM session session_01ARYe3yQTQCUFm5qPYNgKaJ. Assignee set at dispatch time.
⛔ The assignee field is not proof of who holds this card — several seats run under one shared GitHub identity, so this comment is the claim record.

Zone 1 — binding, do not re-litigate

1. ⭐ Take route (2): repoint the document at the root barrel. ⛔ Do not add a ./security entry to packages/core/package.json's exports.
   The reason, and it is the PM seat's ruling on the card's own open choice: route (1) widens the published contract — it makes @objectstack/core/security a supported entry point that must then be kept stable, and publishes the whole security barrel as a named surface — and the card measured no evidence of demand: nothing in the tree imports the subpath. ⛔ Widening a published surface to make a document true is the tail wagging the dog. Route (2) makes the document true immediately at zero contract cost, and it preserves route (1) for a maintainer who later decides the security surface should be separately importable. ⚠️ That decision stays theirs; ⛔ it is not yours and it is not mine, and this card must not foreclose it.
2. The symbols are real and only the path is wrong. PluginPermissionManager and PluginSandboxRuntime are both exported from the root barrel via export * from './security/index.js' in packages/core/src/index.ts. ⇒ The repair is the specifier, ⛔ not the symbols, ⛔ not the barrel, ⛔ not src/security/**.
3. ⛔ Do not touch packages/core/package.json at all — not exports, not files. Its files: ["dist","README.md","CHANGELOG.md"] is why this document is outside check:published-readme-exports's population; it is the explanation, not the defect.
4. ⛔ The proposed new gate is OUT OF SCOPE. The card's "Acceptance" section floats a gate that reads documented @objectstack/* import specifiers against the target package's exports map — a genuinely good idea and a different question from the one check:published-readme-exports asks (symbol-against-built-types vs specifier-against-exports-map). ⇒ ⛔ Not in this PR. File it as an out-of-scope finding if you agree it is worth a row, unassigned and ungraded.
5. ⛔ Do not touch the section packages/core/examples/phase2-integration.ts is the sole composer of PluginSecurityScanner, which FOLLOW-UPS.md already records as exported dead code with 3 of 5 scan methods empty stubs — repair it, or retire it as #4939 did to its neighbour? #14919 already removed. This card is the residue of that PR, which deliberately left these two occurrences alone.

Zone 2 — PM readings, falsifiable, ⛔ NOT binding — re-derive and re-declare

1. Triage re-read these on origin/main and they held: exports keys are exactly ['.', './logger'] — no ./security, no wildcard; files is ['dist','README.md','CHANGELOG.md']; and the two occurrences sit at PHASE2_IMPLEMENTATION.md:161 (section 4. Permission Manager) and :219 (section 5. Sandbox Runtime). ⚠️ main has moved several times since — ⛔ re-locate by text and publish the lines you actually get. ⭐ Line numbers in this repo have been measured stale-by-eight-rows tonight while the quoted text was exact; expect that shape.
2. ⭐ Count the occurrences yourself, over the WHOLE document, before you edit. The card says two survive and a third was removed by packages/core/examples/phase2-integration.ts is the sole composer of PluginSecurityScanner, which FOLLOW-UPS.md already records as exported dead code with 3 of 5 scan methods empty stubs — repair it, or retire it as #4939 did to its neighbour? #14919. ⚠️ If your own count is three, or one, the card's arithmetic has moved and that is your first finding. Use a plain grep over the one file with a firing control (e.g. the count of @objectstack/core without the /security tail in the same file), ⛔ not an eyeball read of the two cited sections.
3. ⚠️ Check the rest of the repo for the same specifier before you conclude the fix is complete. The card's claim is about this one document; it does not claim @objectstack/core/security appears nowhere else. ⛔ A zero elsewhere needs a firing positive control on the same command and scope. If it appears in another shipped document or in code, say so — ⛔ do not silently widen this PR to fix it, and ⛔ do not silently leave it either.
4. Clause-②: expect no — a markdown document, and packages/core's published surface is deliberately untouched by Zone 1.3. ⚠️ Re-derive from your own diff.
5. Changeset: the document is not in files[], so this diff plausibly publishes nothing ⇒ the skip-changeset label rather than a changeset file (AGENTS.md ~line 1019). ⚠️ Measure it — npm pack --dry-run over packages/core, with a control — and say which case you are in. A sibling round tonight correctly overrode this seat's guess by doing exactly that.
6. ⚠️ A markdown edit is not a no-op for a line-number gate. If your change alters the file's line count, check whether anything anchors packages/core/PHASE2_IMPLEMENTATION.md:LINE — with a firing control, since a bare zero here has misled three rounds tonight. ⭐ A sibling round measured 35 files under content/ and docs/ carrying PATH:LINE anchors, which is a control you can reuse.

Zone 3 — suggested route (⛔ not binding)

Two import lines is a one-minute edit; the durable question is whether the document says anything else that resolution would refuse. ⭐ While you are in there, the cheap sweep is: every from '@objectstack/...' specifier in this one document, checked against the named package's own exports map. ⛔ Do not fix what you find beyond this card's two lines without saying so — but reporting it costs nothing and is exactly the evidence the gate in Zone 1.4 would need to justify its existence.

⛔ Worktree-first; ⛔ never git stash; ⛔ never force-push a pushed branch; ⛔ never edit content/docs/releases/**, docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md; ⛔ never skip/disable/quarantine a test; ⛔ do not narrow the gate family because the diff is two lines of markdown — derive it with dispatch-gates.mjs and run all of it.

---

Generated by Claude Code

[claude]

Claim: os-dev execution round for this card, session session_01ARYe3yQTQCUFm5qPYNgKaJ.

Branch: claude/issue-15931-phase2-doc-root-barrel-import

Clause-②: no

Delivered as PR #16205 (draft). Base 53cf263eb, head 9b833a084.

The Clause-② line above is now a MEASUREMENT, not the pre-work prediction it was when this comment was first posted. Re-derived from the actual diff, which is two lines inside one markdown document:

• untouched text from packages/core/PHASE2_IMPLEMENTATION.md appears in 0 files under packages/core/dist/, while three firing controls on the same command and scope reach 6, 6 and 4 dist files — the third taken from a source comment, which proves sourcemap sourcesContent was inside the compared set, so the zero is a reading and not a scope artefact;
• npm pack --dry-run over packages/core lists 16 files and PHASE2_IMPLEMENTATION.md is not among them, while the controls README.md and dist/index.d.ts are;
• packages/core/package.json is untouched — exports stays ['.', './logger'] — so no accept set moves and no exported symbol moves.

Route taken is the dispatch's binding Zone 1.1: repoint the document at the root barrel (from '@objectstack/core'). No ./security exports entry was added; that decision stays the maintainer's.

---

Generated by Claude Code