Skip to content

Commit 2b4b970

Browse files
docs: retire manifest-deps from the plugin-distribution note, re-point two stale plugin-build checklist negatives, correct the liveness manifest cell (#27698)
Fixes #27685 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:三处文档对齐 #27679 之后的代码:插件分发设计文档只剩 `bundled` 一种打包策略;cli 检查清单条目的两条过期否定句改指向真正做校验与分发的代码;liveness README 的 `manifest` 单元格改正 dead 集合(19 → 与生成分片一致的 13)并补上 `packaging` 为何是 `planned` 的一句。 - 为什么改:`manifest-deps` 已被移除并按名拒收,文档却仍把它写成可选策略;检查清单仍说「解包时无人复核 integrity」「无人按 runtime 分发」,而 #27123 的前两片已经实现了这两件事;README 的手写计数早已过期。 - 风险与回滚:纯文档,无代码、无 schema 改动;`packages/spec/liveness/README.md` 随 npm 包发布,故带一个 `@objectstack/spec` patch changeset。回滚即 revert 本 PR。 - 先看:`docs/qa/platform-checklist/areas/cli.json`(两条否定句与 revision 5 历史条目)、`packages/spec/liveness/README.md`(`manifest` 行的 dead 集合句)、`docs/design/plugin-distribution.md` §4.3。 - 两分钟验证:`grep -rn "manifest-deps" docs/design/plugin-distribution.md docs/qa/platform-checklist/areas/cli.json packages/spec/liveness/README.md`,预期只剩「已退役、按名拒收」的叙述,不再有把它当现行策略的句子。 - 需要你做的:无,席位落地。 ## What changes - **`docs/design/plugin-distribution.md`.** The artifact tree no longer lists `package.json` / `pnpm-lock.yaml`; the compiled-manifest sentence gives `packaging` as `bundled` alone; §4.3 is rewritten as "Packaging strategy: bundled only" with one dated note (in the file's existing note shape, as in §4.2) saying `manifest-deps` was retired and is refused by name (#27679, ADR-0025 v2 §3.3); the publish-time tier gate no longer names `manifest-deps`; §6 step 5 says no dependency install runs at materialize. One same-class line beyond the claim's list: §8's supply-chain bullet named a lockfile and `--ignore-scripts`, both of which existed only for the retired strategy, so it now says no install-time package manager runs at all. Same file, same defect class, mechanical. - **`docs/qa/platform-checklist/areas/cli.json`, `cli.plugin-manifest-build-contract` only** (revision 4 to 5, history entry added). The integrity and trust-tier ⛔ negatives said nothing re-verifies the map at unpack and nothing dispatches on `runtime`. Both are false since slices 1 and 2 of #27123. Each negative now names the code that does it as the check this item does NOT score: `packages/cli/src/commands/plugin/install.ts#PluginInstall` through `packages/core/src/security/plugin-artifact-integrity.ts#verifyIntegrity`, and `packages/runtime/src/installed-plugin-loader.ts#dispatchPluginRuntime`. The tracker numbers they cited (#11331, #11330) answer 404 in this repository and are gone from the negatives. Three source rows are added for that code. Scored clauses and steps are unchanged. - **`packages/spec/liveness/README.md`, the `manifest` cell only.** "Dead 19" was a hand-typed count, and it was stale. It counted the seven per-child rows of `capabilities` / `configuration` instead of their two tombstone rows, and a `loading` row that left the ledger with #26599. The cell now partitions the dead set the ledger holds (ten `contributes` members, plus the three retired containers at one row each) and says it sums to 13, the count in the generated `state-counts/manifest.md` shard. It also gains the missing sentence for `packaging`, the type's only `planned` row. - **`.changeset/27685-manifest-liveness-cell.md`**: `@objectstack/spec` patch. `liveness` is in the package's `files`, so the README ships. ## Tests No code changed, so no unit tests were added and none were run. Nothing was ablated, because no tested behaviour moved. ## Acceptance notes - Item 4 of the card (`ui/packages/app-shell/src/console/marketplace/marketplaceApi.ts:171`) is untouched, per triage 6504381957. It rides the next `domain:ui` PR there. - Not edited, recorded here, no card (stale prose, no reach): `docs/adr/0025-plugin-package-distribution.md` still names `manifest-deps` as live at L159 (the manifest example comment), L267 (§3.5 step 5) and L595–596 (the consequences bullet), while its own §3.3 retires it. The ADR is a governed surface and outside this card. - Not edited, outside this card's passages: `plugin-distribution.md` says the bundle is built with `tsup` (§4.1 tree, §5 step 1). The build uses esbuild (`packages/cli/src/commands/plugin/build.ts`; ADR-0025 v2 §3.3 says the same). §4.3 as rewritten names no bundler. - Coverage observation, no card: no platform-checklist item scores the install-time integrity refusal or the boot-time tier dispatch. The two re-pointed negatives now name that code as unscored here. ## Verification H3: the count is generated, not hand-kept. `pnpm --filter @objectstack/spec gen:liveness-counts` exited 0 and rewrote 0 shards, and the committed `state-counts/manifest.md` already reads dead 13 / planned 1. Only the README prose was stale, so it was corrected from `liveness/manifest.json`, and no number was typed into the shard. Gates, derived by `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` at `8dee70e6bb` (59 commands), every exit code captured before any pipe: <details><summary>54 exit 0 · 5 NOT MEASURED (exit 3, PREREQUISITE NOT MET) · --ran reconciliation 59/59 accounted</summary> - `--ran` verdict: `✓ dispatch-gates --ran: 59 derived famil(ies) accounted for — 54 run, 5 NOT-MEASURED (5 DERIVED from a recorded exit 3).` - `pnpm check:platform-checklist` exit 0: `check-platform-checklist: OK — 16 areas, 352 items (347 active, 1 planned)` (the three new `path#symbol` source anchors resolve). - `pnpm --filter @objectstack/spec run check:liveness` exit 0: `✓ packages/spec/liveness/state-counts/ is current — one shard per governed type, the same 43 row(s) as the README, no count column left in the README.` - `pnpm check:doc-authoring` exit 0 · `pnpm check:nul-bytes` exit 0 · `pnpm check:issue-citations` exit 0 · `pnpm check:published-files` exit 0. - `node scripts/check-adr-0087-registration.mjs --base origin/main` exit 0: `this PR adds no declared-breaking changeset` · `check-changeset-no-major` exit 0 · `check-empty-changeset` exit 0. - NOT MEASURED: `check:doc-formula-expressions` (`@objectstack/formula` not built), `check:dts-closure`, `check:dual-build-cjs-loads`, `check:lean-entry-closure` (`@objectstack/objectql` dist absent), `check:sourcemap-no-sources-content`. Reason: each reads the built dist of packages this diff does not change, and building the workspace for a docs-only diff is the declared narrowing. CI's `Lint & Repo Gates` runs them on a built tree. - Local-only families `check:dev-prereqs` / `check:skill-frame-freshness`: not run, because the diff touches neither the `packages/spec` build nor the four-axis frame files. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01QSeKYmTYfaPbLQD4BJfomW)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent c5d51f0 commit 2b4b970

4 files changed

Lines changed: 52 additions & 22 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
docs(spec): the liveness ledger README's `manifest` cell names the type's dead set as the ledger holds it, and says why `packaging` is `planned`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The `manifest` row of `liveness/README.md` said "Dead 19", counting the per-child rows of the retired `capabilities` and `configuration` containers and a `loading` row that has since left the ledger. The cell now partitions the dead set the ledger carries (the ten dead `contributes` members and the three retired containers, one tombstone row each), which sums to the count in the generated `liveness/state-counts/manifest.md` shard. It also gains the missing sentence for `packaging`, the type's only `planned` row: `bundled` is the one strategy, `manifest-deps` is refused by name, and `os plugin build` reads the key only to echo it. No ledger status, evidence, schema or accepted shape changes: only the README prose moves.

‎docs/design/plugin-distribution.md‎

Lines changed: 29 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -111,15 +111,13 @@ A `tar.gz`:
111111
<id>-<version>.osplugin
112112
├── objectstack.plugin.json # compiled manifest (below)
113113
├── dist/ # pre-built ESM bundle (tsup); @objectstack/* externalized
114-
├── package.json # only for the manifest-deps strategy
115-
├── pnpm-lock.yaml # only for the manifest-deps strategy
116114
├── assets/ README LICENSE icon
117115
└── SIGNATURE # detached signature + publisher cert chain
118116
```
119117

120118
Compiled manifest adds four blocks to the existing `ObjectStackManifest`:
121119
`engines` (protocol + platform ranges), `runtime` (`node|sandbox|worker`),
122-
`packaging` (`bundled|manifest-deps`), `permissions` (services/hooks/network/fs
120+
`packaging` (`bundled`, the one strategy and the default — §4.3), `permissions` (services/hooks/network/fs
123121
+ RLS data scopes), and `integrity` (per-file hashes).
124122

125123
### 4.2 UI plugin (`runtime: 'ui'` — ADR-0026 §3.1)
@@ -135,15 +133,27 @@ client-scoped `permissions` (data read/write via SDK, network → CSP, navigatio
135133
> `ManifestSchema` and `PluginSchema` refuse `ui-plugin`; this section and
136134
> worked example C in §10 use `ui`.
137135
138-
### 4.3 Packaging strategies (default: bundled)
139-
140-
- **Bundled (default).** `tsup --noExternal` bundles third-party JS into `dist`;
141-
no npm at install time. **`@objectstack/*` is externalized** as a host-provided
142-
peer-dep singleton (bundling it forks the engine — duplicate registries / broken
143-
`instanceof` / double Zod validation). Native addons disallowed.
144-
- **manifest-deps (opt-in).** Ships `package.json` + lockfile; install runs
145-
`pnpm install --frozen-lockfile --ignore-scripts`. For native addons / huge
146-
deps only; disallowed for unverified publishers.
136+
### 4.3 Packaging strategy: bundled only
137+
138+
- **Bundled — the one strategy, and the default.** `os plugin build` inlines
139+
every dependency the entry imports into `dist/index.mjs`, so install is unpack +
140+
verify with no npm or toolchain at install time: `os plugin install` and the
141+
boot-time loader import `dist/index.mjs` as packed, and the artifact carries
142+
neither `package.json` nor a lockfile. **`@objectstack/*` is externalized** as a
143+
host-provided peer-dep singleton (bundling it forks the engine — duplicate
144+
registries / broken `instanceof` / double Zod validation). A native (`.node`)
145+
addon is refused by name at build, before any artifact is written.
146+
147+
> **Note (2026-10-29, #27679).** This section used to list a second, opt-in
148+
> strategy, `manifest-deps`, which shipped `package.json` + a lockfile for an
149+
> install-time `pnpm install`. Nothing ever ran that install, so an artifact
150+
> built with it could not load the dependencies it left out. It is retired
151+
> (ADR-0025 v2 §3.3): `PluginPackagingSchema`
152+
> (`packages/spec/src/kernel/manifest.zod.ts`) accepts `bundled` alone and
153+
> refuses `packaging: 'manifest-deps'` by name with its migration prescription
154+
> (delete the key), and `os plugin build` no longer forks on the value. A plugin
155+
> that needs a native addon or a very large dependency is a fresh ADR-0025 M3
156+
> decision, not a strategy here. §4.1, §5, §6 and §8 name no second strategy.
147157
148158
## 5. Build → Sign → Publish
149159

@@ -164,8 +174,8 @@ os plugin build → os plugin sign → os plugin publish
164174
`sys_plugin_version` (`status: pending_review → published`).
165175
- **Server gates:** schema validation; secret/malware/known-vuln scan;
166176
**permission audit** (sensitive permissions → human review); **publish-time
167-
tier enforcement** (an unverified publisher cannot ship `runtime: 'node'` or
168-
`manifest-deps`); marketplace **counter-signs** with the platform key on
177+
tier enforcement** (an unverified publisher cannot ship `runtime: 'node'`);
178+
marketplace **counter-signs** with the platform key on
169179
approval.
170180
- Listed in the **contribution catalog** (not the consumer App Marketplace),
171181
with a "contains code" badge and a permission-disclosure screen.
@@ -191,8 +201,8 @@ resolve → compat check → permission consent → download+verify → material
191201
are wired to the KV secret store (ADR-0007) — never stored in the artifact.
192202
4. **Download + verify.** Verify signature (publisher + marketplace keys) and each
193203
file against `integrity`; reject on mismatch.
194-
5. **Materialize.** Unpack to `<OS_HOME>/plugins/<env>/<id>/<version>/`;
195-
manifest-deps runs `pnpm install --frozen-lockfile --ignore-scripts` here.
204+
5. **Materialize.** Unpack to `<OS_HOME>/plugins/<env>/<id>/<version>/`. No
205+
dependency install runs here: the bundle is imported as packed (§4.3).
196206
6. **Register.** Write `sys_plugin_installation` (env_id, plugin_id, version_id,
197207
granted_permissions incl. RLS scopes, status, is_preview). Persist to a local
198208
store so installs survive restarts (the ADR-0016 §9.7 disable-state pattern).
@@ -242,8 +252,9 @@ Reuses existing components, adds two compositions:
242252
- **Secrets.** `configuration` secret fields → KV secret store (ADR-0007) via
243253
secret-refs; the artifact never carries credentials; the plugin reads them
244254
through `PluginContext` gated by the network/service permission.
245-
- **Supply chain.** Lockfile + per-file integrity; server-side secret/vuln scans;
246-
SBOM on the version row; **always `--ignore-scripts`** (no `postinstall`).
255+
- **Supply chain.** Per-file integrity; server-side secret/vuln scans; SBOM on
256+
the version row; **no install-time package manager at all** (bundled only,
257+
§4.3), so no dependency's `postinstall` ever runs.
247258
- **Server-authoritative UI data.** UI plugins read/write only via the client SDK
248259
under the user's session → every access re-checked by server RLS; manifest
249260
`permissions.data` is a UI hint/guard, not the boundary. U1 iframes cannot read

‎docs/qa/platform-checklist/areas/cli.json‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1716,7 +1716,7 @@
17161716
"title": "os plugin build enforces the manifest at the packaging boundary: an invalid manifest is refused with located errors, `bundled` is the one packaging strategy (the retired `manifest-deps` is refused at the manifest, a native addon is refused by name), and the compiled manifest the artifact carries is readable back",
17171717
"since": "v15",
17181718
"status": "active",
1719-
"revision": 4,
1719+
"revision": 5,
17201720
"priority": "P2",
17211721
"surface": "cli",
17221722
"personas": [
@@ -1787,8 +1787,8 @@
17871787
"negative": [
17881788
"an artifact written from a manifest that failed the schema, or from one missing id/version, is the FAIL this item exists for — the refusal is worthless if the build still produces something publishable",
17891789
"a build that accepts `manifest-deps` — writes an artifact, or packs package.json and keeps a dependency external — is a FAIL of the bundled clause: that fork was retired because nothing ever installed the dependencies it left out, so its artifact could not load them. Likewise a native-addon refusal that prints and still writes the .osplugin hands os plugin sign the very artifact it refused",
1790-
"⛔ the `integrity` map's PRESENCE is not evidence of an integrity CHECK. os plugin build computes it and writes it into the compiled manifest, and nothing re-verifies it at unpack — #11331 is open on exactly that. Scoring the printed 'Integrity entries' count as a working integrity guarantee is the false-compliance shape the enforce-or-remove ledger exists for, and this item asserts only that the map is PRODUCED",
1791-
"⛔ likewise the plugin trust tier: build and publish both print `runtime: <value|unset>`, and nothing in this repo dispatches on it — #11330 is open. A run that reads that printed line as isolation has scored a log line, not a capability",
1790+
"⛔ the `integrity` map's PRESENCE is not evidence that this item scored an integrity CHECK. os plugin build computes the map and writes it into the compiled manifest, and this item asserts only that the map is PRODUCED. The check is another door's: os plugin install re-hashes every unpacked entry against the map and refuses the install by name (`integrity_mismatch`) before it writes anything (packages/cli/src/commands/plugin/install.ts#PluginInstall, through packages/core/src/security/plugin-artifact-integrity.ts#verifyIntegrity), and os plugin publish runs the same verifier as its own preflight — no clause here scores either. Reading the printed 'Integrity entries' count as that check scores a log line for a capability this item never exercised",
1791+
"⛔ likewise the plugin trust tier: build and publish both print `runtime: <value|unset>`, and neither dispatches on it. The dispatch is at load — the boot-time loader passes every plugin os plugin install installed through packages/runtime/src/installed-plugin-loader.ts#dispatchPluginRuntime before importing it (`node` loads in process, which is not isolation; `sandbox` and `worker` are refused by name, `runtime_not_dispatched`; an undeclared tier is refused, `runtime_undeclared`), and os plugin install warns when the next boot will refuse the tier. This item scores none of that: a run that reads the printed line as isolation has scored a log line, not a capability",
17921792
"a lint warning that fires on a manifest-less metadata fragment is a FAIL of the scoping half even though the rule itself works"
17931793
],
17941794
"traps": [
@@ -1799,6 +1799,9 @@
17991799
"packages/cli/src/commands/plugin/build.ts#formatZodErrors — manifest read + named refusal; ManifestSchema.safeParse + formatZodErrors; the explicit id/version guard; packaging default and the Loaded line; entry resolution; the bundled-only esbuild call (only `@objectstack/*` external); findNativeAddons and the native-addon refusal ahead of the integrity map; computeIntegrity + the compiled manifest; the artifact write and its printed block",
18001800
"packages/cli/src/utils/osplugin.ts#MANIFEST_FILENAME — MANIFEST_FILENAME = 'objectstack.plugin.json'; OSPLUGIN_EXT; computeIntegrity (manifest and SIGNATURE excluded, keys sorted); the ustar writer with mtime pinned to 0; readOspluginManifest",
18011801
"packages/cli/src/commands/plugin/publish.ts#version — artifact discovery; readOspluginManifest before any network call; the id/version refusal; the unsigned-artifact notice; the auth refusal",
1802+
"packages/cli/src/commands/plugin/install.ts#PluginInstall — the install-time re-verification the integrity negative points at (verifyIntegrity over the unpacked entries, `integrity_mismatch` / `integrity_malformed`, nothing installed) and the install-time tier warning; not scored here",
1803+
"packages/core/src/security/plugin-artifact-integrity.ts#verifyIntegrity — the one integrity verifier, shared by the publish preflight and the install-time check; not scored here",
1804+
"packages/runtime/src/installed-plugin-loader.ts#dispatchPluginRuntime — the boot-time tier dispatch point the trust-tier negative points at (`node` only; `sandbox` / `worker` refused by name; an undeclared tier refused); not scored here",
18021805
"packages/spec/src/kernel/manifest.zod.ts#ManifestSchema — ManifestSchema id and version (both required, version regex-pinned); PluginPackagingSchema ('bundled' only — 'manifest-deps' is a retired value refused with its migration prescription, ADR-0025 v2 §3.3); PluginRuntimeSchema (the trust tier, ADR-0025 §3.6)",
18031806
"packages/cli/src/commands/lint.ts#manifest — the protocol/missing-engines-range rule, its manifest scoping and its fix string",
18041807
"packages/rest/src/package-routes.ts#PACKAGE_MANIFEST_INVALID — the server mirror (400 PACKAGE_MANIFEST_INVALID), recorded in knownGaps rather than scored here",
@@ -1829,6 +1832,12 @@
18291832
"date": "2026-10-29",
18301833
"change": "A3 rewritten and a native-addon clause added: `packaging` no longer forks the artifact. PluginPackagingSchema is narrowed to `bundled` (manifest.zod.ts), so `manifest-deps` is refused at safeParse with its migration prescription and the build.ts externalize + package.json / pnpm-lock.yaml forks are gone — the old fork clause described a property the build no longer has. os plugin build now also refuses a native `.node` addon by name before writing the artifact (findNativeAddons, build.ts). Steps 2, 3, 4 and 8, the first fixture, the archive knownGap, the second negative and two source rows re-pointed to match; probes 6f-6h added for the addon refusal, and a knownGap records the addon an absolute or computed runtime path loads, which the build cannot see. Verified in the same PR through the real door (PluginBuild.run over on-disk projects, plugin-build-bundled-only.test.ts) — a verification re-run, no qa-run record. Untouched and not re-verified here: the integrity and trust-tier negatives",
18311834
"ref": "#27123"
1835+
},
1836+
{
1837+
"revision": 5,
1838+
"date": "2026-10-29",
1839+
"change": "the integrity and trust-tier negatives re-pointed, no clause changed: both said nothing in this repo verifies or dispatches, and both stopped being true with the install loop — os plugin install re-verifies the integrity map at unpack (install.ts#PluginInstall through verifyIntegrity, slice 1, 10f27b6508) and the boot-time loader dispatches on `runtime` before any import (installed-plugin-loader.ts#dispatchPluginRuntime, slice 2, d4ff1a025f). Each negative now names that code as the check this item does NOT score, in place of the tracker numbers it cited, which do not resolve in this repository; three source rows added for the code they point at. The scored clauses and steps are unchanged. Re-verified against the source at 86f2afeb23, no qa-run record",
1840+
"ref": "#27685"
18321841
}
18331842
]
18341843
},

0 commit comments

Comments
 (0)