Repository navigation
Commit 8771726
feat(spec,runtime): every served package row carries
domain:spec#1 · os-tesla · session_01L9qibwb6hBqszPTYJobitm
<!-- claude-projects-attribution: {"github_login":"os-tesla"} -->
_Requested by **Tesla** · [project
thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6Jao1XRKZUtKz7e6nQRc15wpX4)_
Fixes #28318
Clause-②: yes (widening)
Metadata-protocol: added
Skills-docs: follow-up #28118 (the Console half rides the doc:
`content/docs/deployment/marketplace-handbook.mdx` "Disabling a module"
names the served `disableable` key when the Console reads it; no
`skills/**` page names the package read doors' verdicts — `git grep -n
"writable" -- skills/` names no package row)
domain:spec#1 · os-tesla · session_01L9qibzWzEjBsCfzgaacoEm
## 维护者速读
- **改了什么**:`GET /api/v1/packages` 和 `GET /api/v1/packages/:id` 返回的每一行包,在
`writable` 旁边多了一个服务端判定 `disableable`(布尔),回答「这个包在这里能不能停用」。已安装应用下的模块是
`disableable: true`、`writable: false`。
- **为什么改**:#28308 让停用门接受「已安装应用下的模块」,但 Console 只在 `writable`
为真时才显示停用按钮,而模块的 `writable` 一直是 `false`,所以服务端接受的停用,界面给不出来。按裁决不能把
`writable` 改成两个意思,于是单独给一个键。
-
**风险与回滚**:低。只是响应里多一个键,取值用的就是停用门自己问的那个判定(`isDisableablePackage`,门也改成通过它问),两边不可能不一致;`writable`
与所有写门都不变。回滚即 revert。
-
**先看**:`packages/runtime/src/domains/packages.ts`(`isDisableablePackage`、`withDisableableVerdict`、停用门那一行);`packages/spec/src/api/package-api-assembled.zod.ts`(`SERVED_ROW_VERDICTS`);`packages/runtime/src/domains/packages-disableable-verdict.test.ts`(逐行一致性测试)。
- **两分钟验证**:`pnpm --filter @objectstack/runtime exec vitest run
--maxWorkers=2 src/domains/packages-disableable-verdict.test.ts`,预期
22/22 通过:模块 `disableable: true` 且 `writable: false`,11 个包逐行「返回的
disableable = 停用门 200/422」。
- **需要你做的**:无,席位落地。
## What changes
### 1. The key (`@objectstack/spec`)
`SERVED_ROW_VERDICTS` in
`packages/spec/src/api/package-api-assembled.zod.ts` declared one server
verdict on a served package row, `writable`. It now declares a second,
`disableable: z.boolean()`, on both stage branches of
`InstalledPackageAtEitherStageSchema` (so on
`ListInstalledPackagesResponseSchema` and
`GetInstalledPackageResponseSchema` too). Required, like `writable`,
because both read doors serve it on every row. Its describe says what a
client does with it: offer Disable / Enable from it, never from
`writable`. The block comment states that neither verdict is derived
from the other.
**Name.** `disableable`, as triage ruled. The spec's served boolean
verdicts are named VERB-able (`writable` here; `editable`, `deletable`,
`resettable` on the meta item envelope in `api/protocol.zod.ts`;
`undoable`, `repairable`, `sortable` elsewhere in `api/`), so the
convention measures the same name.
### 2. Serving it (`@objectstack/runtime`, triage's one-PR exception)
- **One predicate.** `isDisableablePackage(engine, id)` is the disable
door's verdict on a package: `isDisableableAppModule(engine, id) ||
isWritablePackage(engine, id)`. The door (`PATCH /packages/:id/disable`)
now asks it in place of `isDisableableAppModule` alone. That is
behaviour-identical, because the refusal branch,
`requireWritablePackage`, already answers `null` for a writable package.
The read doors serve the same call as `disableable`. Neither site spells
the rule.
- **Every row door that serves `writable`.** `withDisableableVerdict`
stamps it after the projection, beside `withWritableVerdict`, on the two
doors that serve `writable` from this file: `GET /packages` and `GET
/packages/:id`. The order is the same project-then-stamp order, for the
same reason.
- **Package facts only.** The verdict ignores the caller's own
permission (`manage_metadata`) and a catalog wall, exactly as `writable`
does. The door still asks both.
- `isDisableableAppModule` is unchanged. Its header now says the door
asks it through `isDisableablePackage`, in place of "the served row does
not carry this verdict yet".
## Tests
- **Contract** (`packages/spec/src/api/package-api.test.ts`):
`disableable` is required as a boolean on both stages, is declared on
both branches beside `writable`, keeps `disableable: true` beside
`writable: false`, and is stripped by both record schemas. The shared
`LIFECYCLE` fixture gains `disableable: false`.
- **Runtime**
(`packages/runtime/src/domains/packages-disableable-verdict.test.ts`,
new, 22 tests): a real `SchemaRegistry` through the real dispatcher,
with an 11-package fixture set.
- A suite module (code boot, `scope: 'project'`) and a scope-less
marketplace module of the same app: `disableable: true`, `writable:
false`.
- Controls: modules of the app in a `system` or `cloud` scope give
`false`. A module with no dependency, one whose app is not installed,
and one whose installed dependency is a plugin give `false`. The app, a
plugin, a writable base and a `system` base give `disableable ===
writable`, the door's answer.
- The detail door serves the same pair as the list door, row by row, and
so does `?type=module`.
- **Agreement:** for each of the 11 rows, on a fresh registry, the
served `disableable` equals the door's answer: 200 with the package
disabled, or 422 `WRITABLE_PACKAGE_REQUIRED` with it still enabled. A
non-vacuity case checks that the set holds both answers and a
disableable row that is not writable.
- The served bodies parse through `ListInstalledPackagesResponseSchema`
/ `GetInstalledPackageResponseSchema` with both verdicts kept. The
registry's records never gain the key. Uninstalling the app turns its
module's verdict to `false` on the next read.
- **Existing pins updated:** `packages-writable-verdict.test.ts` pin 5
sets aside `disableable` by name beside `writable`.
`package-door-producer-key-carry.test.ts` registers `disableable` in
`DOOR_COMPUTED_STAMPS`, with its reason. That set-equality register went
red on the first full run, as it is meant to when a stamp arrives
without a decision.
<details><summary>Ablation (one-time, restored)</summary>
Through `node scripts/ablation-replace.mjs` under the verify lock, on
`packages/runtime/src/domains/packages.ts`. The suite imports the
dispatcher from `src/`, so no build sits between mutation and run.
Anchor `disableable: isDisableablePackage(engine, id) }`, x1 → x0.
1. → `disableable: true }`. Blob `24535658be09` → `6aa4c641424a`.
`packages-disableable-verdict.test.ts`: 15 failed, including the
agreement case for every refused row (the app, both platform-scoped
modules, the orphan, the module of an absent app, the plugin, the module
of the plugin, the `system` base).
2. → `disableable: false }`. Blob `24535658be09` → `176b3b97b534`. 9
failed, including the agreement case for every accepted row (both suite
modules, the writable base).
Restored after each leg: blob `24535658be09` = HEAD, `git diff HEAD`
empty.
</details>
<details><summary>Package suites, typecheck, lint</summary>
Under the verify lock, after `pnpm --filter '@objectstack/runtime^...'
build` on the merged tree:
- `pnpm --filter @objectstack/runtime --filter @objectstack/spec
--no-bail test` at `f559c37c`: spec `Test Files 771 passed (771)`,
`Tests 22808 passed | 1 todo (22809)`. Runtime `Test Files 1 failed |
489 passed (490)`, `Tests 1 failed | 7956 passed | 19 skipped (7976)`.
The one red was the `DOOR_COMPUTED_STAMPS` register (above), fixed in
`c2a97b40`. That file and the response-conformance file then gave `Tests
22 passed (22)`.
- `main` then moved 7 commits (spec and runtime among them, #28171),
merged at `b4d79818`. Refreshed per AGENTS.md §9 (`pnpm install
--frozen-lockfile`, `pnpm build`: `Tasks: 116 successful, 116 total`),
then in one locked run: `check:generated` green, typecheck exit 0, spec
`Tests 22808 passed | 1 todo (22809)`, runtime `Test Files 491 passed
(491)`, `Tests 7981 passed | 19 skipped (8000)`, `VERDICT command-exit
0`.
- `pnpm exec eslint --no-inline-config` on the five touched source and
test files: exit 0.
- `pnpm --filter @objectstack/spec check:generated`: one artifact was
stale (`content/docs/references/**`), regenerated with `--fix` and
re-checked green.
</details>
## Acceptance notes
- **`GET /api/v1/meta/package` also stamps `writable`**
(`packages/metadata-protocol/src/protocol.ts`, `getMetaItems` for `type:
'package'`). It is a different producer: its rows are not declared with
`SERVED_ROW_VERDICTS`, and it lives outside this card's file surface.
The one predicate is private to the runtime, so serving `disableable`
there would need the rule moved into `@objectstack/metadata-protocol`,
which is a second card. The Console's Packages page reads `/packages`
(`PackagesPage.tsx`, typed `InstalledPackageAtEitherStage`), which this
PR serves. Noted, not filed.
- The enable door (`PATCH /packages/:id/enable`) has no package gate, so
any disabled package can be re-enabled. The describe therefore says
"disable", and leaves the Console to offer Enable on a disabled row as
it does today (`writable || !enabled`, read by #28118).
- The Console half is #28118. This PR changes nothing under `ui/`.
`InstalledPackageRow` picks `source | writable` from the spec type, so
the new required key does not red `Type Check UI`.
## Verification
Gates from `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` on this diff (105 commands), each run on the
final head `b4d79818` with stdin from /dev/null and its exit code
captured before any pipe: all 105 exit 0. `dispatch-gates --ran`: "105
derived famil(ies) accounted for — 105 run, 0 NOT-MEASURED". On the
first sweep (head `f559c37c`), three answered exit 3, PREREQUISITE NOT
MET, and measured nothing: `check-plugin-teardown-shape --self-test`
(shallow clone), `check:skill-examples` (no client dist),
`check:dual-build-cjs-loads` (no full build). The clone was deepened and
`pnpm build` run, and all three exit 0 on the final head. The families
CI runs are cited from this PR's check-runs in the report on the card.
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(The predicate lives in the runtime; spec declares the key.)
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes (scoped to the touched
files; the repo sweep is CI's).
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset
(`.changeset/28318-served-disableable-verdict.md`, `minor` for spec and
runtime), and both declaration lines are filled in here and in the
changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English (the 维护者速读 block is the
seat's required Chinese summary).
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01L9qibzWzEjBsCfzgaacoEm)_
---------
Co-authored-by: Claude <noreply@anthropic.com>disableable, the disable door's own verdict, beside writable (#28371)1 parent 3ba5206 commit 8771726
9 files changed
Lines changed: 410 additions & 18 deletions
File tree
- .changeset
- content/docs/references/api
- packages
- client/src
- runtime/src/domains
- spec/src/api
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
211 | 211 | | |
212 | 212 | | |
213 | 213 | | |
| 214 | + | |
214 | 215 | | |
215 | 216 | | |
216 | 217 | | |
| |||
230 | 231 | | |
231 | 232 | | |
232 | 233 | | |
| 234 | + | |
233 | 235 | | |
234 | 236 | | |
235 | 237 | | |
| |||
262 | 264 | | |
263 | 265 | | |
264 | 266 | | |
| 267 | + | |
265 | 268 | | |
266 | 269 | | |
267 | 270 | | |
| |||
325 | 328 | | |
326 | 329 | | |
327 | 330 | | |
| 331 | + | |
328 | 332 | | |
329 | 333 | | |
330 | 334 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
645 | 645 | | |
646 | 646 | | |
647 | 647 | | |
648 | | - | |
649 | | - | |
650 | | - | |
651 | | - | |
| 648 | + | |
| 649 | + | |
| 650 | + | |
| 651 | + | |
| 652 | + | |
652 | 653 | | |
653 | 654 | | |
654 | 655 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
97 | 97 | | |
98 | 98 | | |
99 | 99 | | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
100 | 104 | | |
101 | 105 | | |
102 | 106 | | |
103 | 107 | | |
104 | 108 | | |
105 | | - | |
| 109 | + | |
106 | 110 | | |
107 | 111 | | |
108 | 112 | | |
| |||
0 commit comments