[objectstack-fleet]

Requested by Tesla · project thread

Fixes #30962

Clause-②: yes (widening)
Metadata-protocol: none

维护者速读

• 改了什么：模块启用/停用状态的存放处可由宿主提供。宿主在内核里加 createPackageStateStorePlugin(store)，启动种子和启用/停用/安装/删除各门都改读写这个存储；不加则仍是 OS_HOME 下的那个文件，字节不变。
• 为什么改：托管云上容器一换，OS_HOME 里的文件就没了，管理员在设置里关掉的模块会重新出现（cloud#3636，裁决「AAAA + 三条验收（推荐）」）。平台补上缺的宿主接缝，cloud 只需实现托管存储。
• 风险与回滚：启用/停用门改成先写存储、再改内存；宿主存储拒写时门答 503 且什么都不变。未注入时行为与文件内容不变。回滚即 revert 本 PR。
• 先看：packages/runtime/src/domains/packages.ts 的启用、停用两门（先写存储的顺序与 503 分支）；packages/runtime/src/app-plugin.ts 的 seedPersistedDisabledPackages 与 refuseLatePackageStateStore；新文件 packages/runtime/src/package-state-host-store.ts。
• 两分钟验证：pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 src/package-state-host-store.test.ts，预期 11 个用例全绿。
• 需要你做的：无，席位落地。

What changes

The seam (packages/runtime/src/package-state-host-store.ts, exported from @objectstack/runtime). PackageStateStore is loadDisabledPackageIds(environmentId) plus setPackageDisabled(environmentId, packageId, disabled), either may return a promise. A host adds createPackageStateStorePlugin(store) to its kernel; that plugin (com.objectstack.package-state-store) registers the store as the package-state-store kernel service. This is the door a host already uses to hand the runtime anything: createStandaloneStack returns a plugins list the host composes into its kernel, so no new top-level option was added. AppPlugin lists the plugin name in optionalDependencies (ADR-0116), so the store is registered before the boot seed reads it whatever slot the host puts it in; check:init-service-contract now holds that init-time read to the declaration.

Boot seed (AppPlugin.seedPersistedDisabledPackages). Reads the host store when one is registered, else the file exactly as before (best-effort, warns). A host store whose read throws fails the boot with a named error instead of seeding nothing, which would bring every disabled module back enabled with nothing looking wrong (the ADR-0025 §3.5 M1 call the installed-plugin loader already makes). AppPlugin.start() refuses a boot that seeded from the file while a store is registered by then (a host registering under the service name from its own, unordered plugin), naming createPackageStateStorePlugin as the fix.

Doors (domains/packages.ts). Every write goes through one writePackageState, which looks the store up through the classified lookup (resolveServiceOrLoud), so a store factory that throws refuses the write rather than reading as "no host store".

• PATCH /packages/:id/enable and /disable now write the store FIRST and switch the registry second. A host store that refuses: nothing changes in memory and the door answers 503 SERVICE_UNAVAILABLE (the standard code, no new code), message opening Package 'ID' was not disabled: the package-state store refused to record it, so nothing changed. The file default keeps its best-effort warn and still switches.
• Install and delete, whose change has already landed when they write, keep their best-effort try; a host store's refusal there is logged at error naming what the next boot will read, the file's failure keeps the existing warn.
• The disable door's dependent-rule scan (fix(runtime)!: the package disable door refuses while an enabled package's validation rule reads a field the package adds #30825, merged) runs first and is untouched; the store write follows it.

Tests

New packages/runtime/src/package-state-host-store.test.ts, a real ObjectKernel + ObjectQLPlugin + AppPlugin and the real HttpDispatcher on the package doors, the store plugin composed AFTER AppPlugin in use() order:

• the boot seeds from the host store and not from the file (the file says the opposite); every enable and disable write reaches the store and the OS_HOME state directory is never created; a disable written in one boot is what the next boot (fresh OS_HOME) seeds;
• a refusing store: disable answers 503 SERVICE_UNAVAILABLE and the package stays enabled; enable answers 503 and it stays disabled; an unknown id still answers 404 and writes nothing;
• a store whose boot read throws fails the boot; an unordered registration is refused at start; a store missing a method is a TypeError;
• without a host store: the file bytes after disable and enable are pinned exactly, and a file that cannot be written still only warns while the disable lands (200).

Head 8e94a195 (after merging origin/main at c77dd17f):

• pnpm --filter @objectstack/runtime typecheck: exit 0 (check:test-typecheck: OK).
• pnpm --filter @objectstack/runtime test: Test Files 551 passed (551), Tests 8827 passed, 19 skipped.
• eslint packages/runtime --no-inline-config: exit 0.

Ablations (each once, through scripts/ablation-replace.mjs, each restored with blob == HEAD and git diff HEAD empty; taken on 83af516, before the merge, which did not touch these lines)

A1, the refusal answered, removed (a refusing host store warns and disables anyway):

ablation-replace: ok mutation landed: anchor 1 -> 0, blob fd9ac190be11 -> d9c4bc8efdb9
     × a refusing store fails the disable door visibly, and the package stays enabled
AssertionError: expected { status: 200, code: undefined, …(1) } to match object { status: 503, …(1) }
      Tests  1 failed | 10 passed (11)

(The first A1 attempt used an empty --replacement; the tool refused it as a non-landing mutation before running anything, and the leg was re-run with --delete.)

A2, the old order back (registry switched before the store write, refusal kept):

ablation-replace: ok mutation landed: anchor 1 -> 0, blob fd9ac190be11 -> d54cbb48382c
     × a refusing store fails the disable door visibly, and the package stays enabled
     × an unknown package still answers 404 and writes nothing to the store
AssertionError: expected { manifest: { …(4) }, …(7) } to match object { enabled: true, status: 'installed' }
      Tests  2 failed | 9 passed (11)

A3, no host store and the file not written:

ablation-replace: ok mutation landed: anchor 1 -> 0, blob fd9ac190be11 -> a97613d63a2c
     × the disable and enable doors write the file under OS_HOME exactly as before
     × a file that cannot be written still only warns: the disable lands in memory and answers 200
      Tests  2 failed | 9 passed (11)

(Its first attempt was refused by the tool, the replacement text already occurring elsewhere; re-run with --delete.)

A4, no host store and a file failure made loud:

ablation-replace: ok mutation landed: anchor 1 -> 0, blob fd9ac190be11 -> b4cf3ef91361
     × a file that cannot be written still only warns: the disable lands in memory and answers 200
AssertionError: expected { status: 503, …(2) } to match object { status: 200 }
      Tests  1 failed | 10 passed (11)

A5, the start-time refusal of an unordered store removed:

ablation-replace: ok mutation landed: anchor 1 -> 0, blob a7b1c9907070 -> 3b2717f6436c
     × a store registered under the service name by a plugin AppPlugin is not ordered after is refused at start
AssertionError: promise resolved "{ kernel: ObjectKernel{ …(14) }, …(1) }" instead of rejecting

A6, the store plugin dropped from AppPlugin.optionalDependencies:

ablation-replace: ok mutation landed: anchor 1 -> 0, blob a7b1c9907070 -> 5fa7328f99d5
     × seeds the boot from the host store — not from the file — even when composed after AppPlugin
     … 7 failed | 4 passed (11)

Acceptance notes

• Card acceptance, line by line. ① A host-injected store sees every enable/disable write (install, enable, disable, delete) and seeds boot: pinned. ② A refusing store makes the enable and disable doors fail visibly (503) with in-memory state unchanged: pinned and ablated (A1, A2). ③ Without injection behaviour is unchanged: file bytes and the warn-only failure pinned and ablated (A3, A4).
• Cloud C3 (the hosted store, cloud#3636) consumes this: it implements PackageStateStore and adds createPackageStateStorePlugin(store) to the hosted kernel.
• Choices the card did not rule, made here; the seat may overrule. (a) A host store's boot read that throws fails the boot, not a warn. (b) Install and delete stay best-effort on a host refusal (their change has landed), logged at error; only enable and disable, which can write first, answer the refusal. (c) The 503 message embeds the store's own error text; the dispatcher's 5xx leak guard still replaces it if it looks like an internal leak.
• Not routed through the seam: plugin-installation-store.ts (the local os plugin disable | enable commands and the boot-time installed-plugin loader, ADR-0025 §3.5 M1) still reads and writes the file directly. That loop is local-first CLI state; a hosted container that wants it host-backed is a separate card.
• Overlap: fix(runtime)!: the package disable door refuses while an enabled package's validation rule reads a field the package adds #30825 merged and is integrated (its dependent scan runs before the store write, unchanged). runtime: enabling a package whose validation rule reads a field of a disabled package is accepted, and every write to that object then answers 400 #30756 (seat thread, branch fyy60n) is adding a refusal pre-check to the enable door; whichever PR opens second merges origin/main after the first lands.
• No packages/spec edit, no new error code. Size: 6 files, +681 / −30.

Verification

Derived gates (dispatch-gates.mjs --commands, 63 families) plus check:init-service-contract, check:startup-registry-verdict, check:error-code-casing, check:route-ledger-census, check:authz-resolver, check:changeset-fixed, check:filter-alias-parity and check-platform-checklist.mjs --changed-from origin/main: all 71 exit 0 on 8e94a195; dispatch-gates --ran: 63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN. Record: server-seat-2/r2026-11-06/out/30962-gates-ran-8e94a195.list in the project files.

Notes on the gate run

• On the pre-merge head, check:test-source-alias was red on the new test (a clocked lazy import('@objectstack/metadata') reached through AppPlugin); fixed with a module-top import '@objectstack/metadata' in the test, the gate's own prescription.
• check-plugin-teardown-shape --self-test and check:dual-build-cjs-loads first answered exit 3 (prerequisite: pinned commit 621a487 absent from the shallow clone, and unbuilt dists); after git fetch of that commit and a full turbo run build --filter='./packages/**', both exit 0.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 25 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

21 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 8ae0ab9b0d77d56473e89dae9fe437778172dda8.

⛔ 7 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 63 of 222 client-bound route-ledger rows — the other 159 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 159: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 104 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 28 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 8ae0ab9b0d77d56473e89dae9fe437778172dda8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from eb50027e7fd8e5253d833678672e741e97ad1a24 — the merge of head 8e94a195be3fd5a50537cca7592e4a67a889f2e6 into base 8ae0ab9b0d77d56473e89dae9fe437778172dda8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin eb50027e7fd8e5253d833678672e741e97ad1a24 && git checkout eb50027e7fd8e5253d833678672e741e97ad1a24
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 8ae0ab9b0d77d56473e89dae9fe437778172dda8 8e94a195be3fd5a50537cca7592e4a67a889f2e6 && git checkout -B drift-repro 8ae0ab9b0d77d56473e89dae9fe437778172dda8 && git merge --no-ff 8e94a195be3fd5a50537cca7592e4a67a889f2e6

node scripts/docs-audit/affected-docs.mjs --json 8ae0ab9b0d77d56473e89dae9fe437778172dda8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 8ae0ab9b0d77d56473e89dae9fe437778172dda8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#2 · os-tesla · session_01L9qibyvxbrLP4jm4PargoH

维护者速读

• 改了什么：@objectstack/runtime 新增宿主接缝 createPackageStateStorePlugin(store)：宿主可以自己提供「哪些模块被停用」的存放处（托管云用数据库，不再只写容器里的文件）。启用/停用接口先写存储、再切换内存；宿主存储拒写时返回 503 SERVICE_UNAVAILABLE，什么都不变。没有注入时仍写 OS_HOME 下的文件，字节不变。
• 为什么改：托管云上管理员停用的模块，容器一换就恢复启用，另一个容器也看不到（cloud#3636，维护者裁决「AAAA + 三条验收」）。平台的问题在平台处理，云端只需实现存储。
• 风险与回滚：只对注入了宿主存储的内核生效；默认文件路径的行为与字节不变。宿主存储启动读取失败会让启动失败（宁可停也不把已停用模块全部放开）。回滚即 revert。
• 先看：packages/runtime/src/package-state-host-store.ts（接缝与约定）、src/domains/packages.ts 的 enable/disable 两个门（先写存储后切换）。
• 两分钟验证：pnpm --filter @objectstack/runtime exec vitest run src/package-state-host-store.test.ts。
• 需要你做的：无。席位按你的话落地；云端 C3 随后接入。

席位意见：可以落地。

席位核对

ACCEPT · seat domain:server#2 · head 8e94a195 · 2026-11-06T17:24Z

1. Shape: Fixes #30962, draft, base main, 6 files (.changeset/30962-host-package-state-store.md, packages/runtime/src/{app-plugin.ts,domains/packages.ts,index.ts,package-state-host-store.ts,package-state-host-store.test.ts}), +681/−30, no governed path. @objectstack/runtime patch changeset with Clause-②: yes (widening) and Metadata-protocol: none, matching claim and order; no packages/spec edit, no new error code.
2. Premise: on main the store was the OS_HOME file only and a failed write warned; PR fix(runtime)!: the package disable door refuses while an enabled package's validation rule reads a field the package adds #30825 merged first and its dependent scan still runs before the store write (seat read the disable door).
3. Review: Clause-②: yes (widening) alone (new runtime exports) ⇒ the seat's TIER_DEFAULT review of record; no *.zod.ts, no narrowing arm. Seat read the whole diff. The seam is a kernel service ordered by optionalDependencies (ADR-0116), the door's lookup is the classified resolveServiceOrLoud (a faulting factory refuses rather than silently falling to the file), and enable/disable write the store before the registry switch so a host refusal leaves memory unchanged (card line 2), answered with the standard SERVICE_UNAVAILABLE. The file default writes the same bytes; its failure stays a warn. The three choices the card did not rule are accepted as made: (a) a host boot read that throws fails the boot — the loud direction, ADR-0025 §3.5 M1's precedent; (b) install/delete log a host refusal at error because their change has already landed; (c) a host store registered outside the plugin is refused at start() by name rather than run with two stores. plugin-installation-store.ts (CLI plugin state) is not routed and is named as a separate concern. Six ablations red/restored (PR body).
4. Gates / check-runs: dev: 71 gates exit 0, --ran reconciled, runtime suite 551/551 files (report 6690545807). On head 8e94a195: 35 success, 13 skipped, 0 failed; mergeable_state: clean.
5. Accepted deviations: the file default's write now precedes the registry switch (it followed it before); bytes and failure handling are unchanged, and the order is what makes card line 2 hold for a host store.
6. Landing: not governed, 711 changed lines: the seat readies the PR and arms auto-merge on the maintainer's word in the seat thread 「你应该使用 pm-dispatch 技能审核和落地pr」(2026-11-06T16:49Z). runtime: enabling a package whose validation rule reads a field of a disabled package is accepted, and every write to that object then answers 400 #30756 (same seat, enable door) merges origin/main after this lands.