fix(metadata-protocol,runtime,app-shell)!: refuse a save or draft publish naming a package that is not installed - #26920

Fixes #26708

Clause-②: yes (narrowing)
Metadata-protocol: none
Skills-docs: updated here — content/docs/concepts/metadata-lifecycle.mdx (no skills/** page teaches saving into a named package: skills/objectstack-api names ?package= only as a read parameter)

维护者速读

• 改了什么：/meta 保存时若 ?package= 指向本部署未安装的包，所有类型（不只 flow）的草稿和直接保存都会被拒（422 WRITABLE_PACKAGE_REQUIRED，什么都不写）；publish-drafts 对未知包 id 先回 404；Studio 打开不存在的包显示"未找到包"，未知栏目显示"页面不存在"。
• 为什么改：之前拼错包 id 也能保存成功，生成挂在"幽灵包"下的对象/仪表盘/页面，没有命名空间、无法卸载或导出，publish-drafts 还会把它们发布上线。
• 风险与回滚：只收紧请求，不改存储形状；已存在的幽灵行照常可读，可用 discard-drafts 清理。回滚即还原本 PR，无数据迁移。夹具改动量大（约 50 个测试文件改为先安装包），是规则收紧的直接后果。
• 先看：packages/metadata-protocol/src/protocol.ts（uninstalledNamedBaseRefusal 与 saveMetaItem 的调用点）、packages/runtime/src/domains/packages.ts（publish-drafts 的 404 位置）、ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx（pkgMissing 判定）。
• 两分钟验证：pnpm dev -- --fresh -p 4417 后登录，PUT /api/v1/meta/dashboard/x?mode=draft&package=com.example.nosuch 应回 422 WRITABLE_PACKAGE_REQUIRED；再打开 /_console/studio/com.example.nosuch/data 应看到"未找到包"。
• 需要你做的：无，席位落地。

What changes

• @objectstack/metadata-protocol — the flow-only named-base rule (metadata: the /meta flow save accepts a write bound to a package id that no installed package has, and stores it active #20863) is now one private helper, uninstalledNamedBaseRefusal, and saveMetaItem asks it for every type, draft and active, on authoring saves (not on the migrate-stored and package-duplicate rewrites of stored rows). A save naming a package id the registry does not hold is refused 422 WRITABLE_PACKAGE_REQUIRED with packageId and the ADR-0070 docs link, before anything is written or registered. The flow arm (tenantAuthoredWriteRefusal) calls the same helper, so its sentence is unchanged byte for byte and other types get the same sentence with their type name. The sys_metadata sentinel, a save naming no package and a save naming an installed package are unchanged.
• @objectstack/runtime — POST /packages/:id/publish-drafts on an id the registry does not hold answers 404 RESOURCE_NOT_FOUND (the GET /packages/:id answer, the existing unknown-id code) before the protocol is asked, even when drafts are stored under that id. The check sits after the capability probe, like discard-drafts and the commit trail, so a host that cannot publish still answers 501. No error code was added. Stored rows under such an id are not migrated or deleted.
• @object-ui/app-shell — /studio/ID/… for an id the package list does not hold renders "Package not found" (no pillars, no Changes / Publish / create-app, one button back to the Studio landing). A pillar segment Studio has no pillar for renders a not-found state instead of falling through to Interfaces. It reads the existing GET /api/v1/packages (no new endpoint, still one request): a switcher entry counts as installed; otherwise the id is looked up among every listed id, so kernel packages the switcher hides still open. A list that failed to load leaves the builder as it was.
• Docs: one paragraph in content/docs/concepts/metadata-lifecycle.mdx; changeset 26708-named-base-every-type.md (patch on the three packages, BREAKING banner, both declaration lines).

Why

PUT /api/v1/meta/:type/:name?package=ID stored the item bound to ID even when no installed package had that id, as a draft or live, and with no manifest the object namespace rule was skipped too. publish-drafts on that id then put the drafts live, owned by a package that cannot be uninstalled or exported. Only flow refused it.

Tests

• New packages/metadata-protocol/src/protocol.named-base-every-type.test.ts (13 tests): object, dashboard and page, draft and active, refused with the envelope (code, status, packageId, message first sentence) and nothing inserted or registered; the flow arm's exact sentence; a plural type spelling; controls for an installed package, the sentinel / null / no package, and the two server-side rewrites.

• packages/runtime/src/domains/packages-draft-doors-unknown-package.test.ts: drafts stored under an unknown id are not published (404, the protocol is not asked, no visibility flip); controls that a known package still publishes and an unknown id's drafts are still discarded.

• New ui/…/StudioDesignSurface.notFound-26708.test.tsx (10 tests): not-found on all four pillars with no pillar links or package actions and one list request, the way back, controls for a listed package, a kernel package and a failed list, and the unknown pillar segment.

• Red first: on the base tree the protocol pins fail 7 of 13 (the 6 controls pass), the runtime pin fails, and the Studio pins fail 6 of 10 (the 4 controls pass).

• Fixtures: about 50 test files across metadata-protocol, objectql, runtime and rest saved into package ids that were never installed. Each now installs the package it names, as a boot or POST /packages does (authored, or code where the file's premise is a shipped package). Where the package's closure now judges a view's object (list-view-object-outside-closure), the fixture registers the bound object under the package or declares the owner as a dependency. None of these widened the rule.

• Dogfood: three files saved into package ids no boot installs (package-first-authoring, package-uninstall-revokes-named-grants, flow-shipped-name-published-door). Each now creates its base package first through protocol.installPackage (as POST /api/v1/packages does) under a valid reverse-domain id with its own namespace; the old ids used underscores, which the install door refuses as invalid package ids.

• StudioDesignSurface.flowCanvasChip-11665.test.tsx: the zh tooltip assertion now waits for the lazily fetched studio catalogue it reads (it answers en until the zh catalogue lands and re-renders the pillar). It passed before only because of module load order; adding two keys to i18n.ts changed that order.

• Package suites on the final head (48af4d05fc, after merging main at 96e7a4335c, which holds fix(runtime)!: the package draft doors refuse a query parameter they do not read #26853's draft-door query refusal in the same handler): @objectstack/runtime 7468 passed / 19 skipped, @objectstack/metadata-protocol 21679 passed / 26 skipped, @objectstack/objectql 8843 passed, @objectstack/rest 6513 passed / 326 skipped; typecheck exit 0 on all four. UI packages/app-shell/src/views/studio-design + metadata-admin: 835 files, 8321 passed / 1 skipped; @object-ui/app-shell type-check exit 0.

• scripts/engine-double-contract.pinned.json: the new protocol test's engine double answers delete, findOne and update it never reads; recorded with pnpm check:engine-double-contract --write.

Acceptance notes

• How rows already stored under an uninstalled id surface (live, on one dev DB written by main, then booted on this branch): the active row still reads (GET /meta/dashboard/NAME 200) and still lists under ?package=ID; its draft still reads; a save naming the id is refused 422; publish-drafts answers 404; discard-drafts answers 200 and removes the drafts; the id is not in GET /api/v1/packages, so Studio shows "Package not found" for it.
• Two doors still write or publish under such an id, both outside this card's ruling: a save naming NO package for an item whose active row is bound to the phantom id inherits that binding (SqlDriver org auto-scope makes SysMetadataRepository.listDrafts blind to env-wide drafts (organization_id IS NULL ∧ injected org = always empty); mode=draft saves drop package_id #11087), and the per-item POST /meta/:type/:name/publish?package=ID publishes a phantom-bound draft (200). Both only reach rows written before this change.
• Studio's recent-packages list can still hold an id that later reads "Package not found"; the not-found page offers the way back.

Verification

• Live red/green on pnpm dev -- --fresh, signed in as the dev admin, same probe on both trees. Base (4f05de4): six PUT /api/v1/meta/{object,dashboard,page}/NAME[?mode=draft]&package=com.example.nosuch all answered 200 and stored the rows bound to that id; POST /packages/com.example.nosuch/publish-drafts answered 200 while GET /packages/com.example.nosuch answered 404. This branch: the same six saves answer 422 WRITABLE_PACKAGE_REQUIRED ("Cannot save dashboard 'ghost_dashboard_a' into package 'com.example.nosuch': no package with that id is installed in this deployment, …"), publish-drafts answers 404 RESOURCE_NOT_FOUND. Controls unchanged on both: a save naming no package (200), and a package created through POST /api/v1/packages then saved into and published (201, 200, 200).

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on 48af4d05fc: 105 commands, each run with its exit code captured before any pipe; all 105 exit 0. --ran reconciliation: "105 derived, 105 run, 0 NOT-MEASURED, 0 UNRUN".

• Full dogfood once on the final head 48af4d05fc (pnpm --filter @objectstack/dogfood test): exit 0, 327 files passed / 3 skipped, 2683 tests passed / 20 skipped.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (packages/spec untouched.)
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes. (Scoped to the touched files on the final head: root ESLint exit 0; ui ESLint exit 0, 0 errors, 14 warnings, all on lines this PR did not write — the one inside the edited effect is the existing setPkgWritable(undefined) call.)
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: not touched.
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01FEkQ5nhhuhjVQJ8R3qK9UB