Skip to content

Commit 8771726

Browse files
feat(spec,runtime): every served package row carries disableable, the disable door's own verdict, beside writable (#28371)
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>
1 parent 3ba5206 commit 8771726

9 files changed

Lines changed: 410 additions & 18 deletions
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/runtime': minor
4+
---
5+
6+
feat(spec,runtime): every served package row carries `disableable`, the disable door's own verdict, beside `writable`
7+
8+
Clause-②: yes (widening)
9+
Metadata-protocol: added
10+
11+
- **New key.** `SERVED_ROW_VERDICTS` in `@objectstack/spec/api-assembled` declares `disableable: boolean` on both stage branches of `InstalledPackageAtEitherStageSchema`, so `GET /api/v1/packages` and `GET /api/v1/packages/:id` serve it on every row. It answers "may an org disable this package here?": `true` for a writable base and for a module of an installed app (a `type: 'module'` package that directly depends on an installed `type: 'app'` package, outside a `system` / `cloud` scope), `false` for every other read-only package.
12+
- **One predicate.** The runtime computes the served value with the same predicate `PATCH /api/v1/packages/:id/disable` asks before it switches a package off, so the row and the door cannot disagree. The caller's own permission and a catalog wall are still asked at the door; the verdict is about the package only.
13+
- **`writable` is unchanged.** A module of an installed app is `disableable: true` and `writable: false`: it may be switched off, never authored into. A client offers Disable / Enable from `disableable`, and authoring from `writable`.
14+
- **Who sees it.** A customer admin on the Packages page: once the Console reads this key, it can offer Disable on a suite module the server already accepts.

‎content/docs/references/api/package-api-assembled.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,7 @@ Get installed package response
211211
| **upgradeHistory** | `{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]` | optional | Version upgrade history |
212212
| **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package |
213213
| **writable** | `boolean` | ✅ | Whether this server lets an org author into and manage this package (a writable base); false for a read-only package. Computed per read by the server's own predicate, never stored |
214+
| **disableable** | `boolean` | ✅ | Whether this server lets an org disable this package: the disable door's own verdict, true for a writable base and for a module of an installed app, false for every other read-only package. A client offers Disable / Enable from it, never from writable. Computed per read by the server's own predicate, never stored |
214215

215216
### Nested Shape: `GetInstalledPackageResponse.data[option 2]`
216217

@@ -230,6 +231,7 @@ Get installed package response
230231
| **upgradeHistory** | `{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]` | optional | Version upgrade history |
231232
| **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package |
232233
| **writable** | `boolean` | ✅ | Whether this server lets an org author into and manage this package (a writable base); false for a read-only package. Computed per read by the server's own predicate, never stored |
234+
| **disableable** | `boolean` | ✅ | Whether this server lets an org disable this package: the disable door's own verdict, true for a writable base and for a module of an installed app, false for every other read-only package. A client offers Disable / Enable from it, never from writable. Computed per read by the server's own predicate, never stored |
233235

234236

235237
---
@@ -262,6 +264,7 @@ This schema accepts one of the following structures:
262264
| **upgradeHistory** | `{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]` | optional | Version upgrade history |
263265
| **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package |
264266
| **writable** | `boolean` | ✅ | Whether this server lets an org author into and manage this package (a writable base); false for a read-only package. Computed per read by the server's own predicate, never stored |
267+
| **disableable** | `boolean` | ✅ | Whether this server lets an org disable this package: the disable door's own verdict, true for a writable base and for a module of an installed app, false for every other read-only package. A client offers Disable / Enable from it, never from writable. Computed per read by the server's own predicate, never stored |
265268

266269
### Nested Shape: `InstalledPackageAtEitherStage[option 1].manifest`
267270

@@ -325,6 +328,7 @@ This schema accepts one of the following structures:
325328
| **upgradeHistory** | `{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]` | optional | Version upgrade history |
326329
| **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package |
327330
| **writable** | `boolean` | ✅ | Whether this server lets an org author into and manage this package (a writable base); false for a read-only package. Computed per read by the server's own predicate, never stored |
331+
| **disableable** | `boolean` | ✅ | Whether this server lets an org disable this package: the disable door's own verdict, true for a writable base and for a module of an installed app, false for every other read-only package. A client offers Disable / Enable from it, never from writable. Computed per read by the server's own predicate, never stored |
328332

329333
### Nested Shape: `InstalledPackageAtEitherStage[option 2].manifest`
330334

‎packages/client/src/return-type-precision.test.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -645,10 +645,11 @@ export async function returnTypePrecisionPins12034(): Promise<void> {
645645
void (await scoped.packages.get('com.acme.crm')).package;
646646
}
647647

648-
// A SERVED row is the registry record plus the read door's own verdict,
649-
// `writable` (#23972 declared it on the served row, not on the record).
650-
declare const authoringRow: InstalledPackage & { writable: boolean };
651-
declare const assembledRow: AssembledInstalledPackage & { writable: boolean };
648+
// A SERVED row is the registry record plus the read door's own verdicts,
649+
// `writable` (#23972 declared it on the served row, not on the record) and
650+
// `disableable` (#28318, declared beside it).
651+
declare const authoringRow: InstalledPackage & { writable: boolean; disableable: boolean };
652+
declare const assembledRow: AssembledInstalledPackage & { writable: boolean; disableable: boolean };
652653

653654
/**
654655
* [#17536] The four `/packages` READ members declare the stage the DOOR is

‎packages/runtime/src/domains/package-door-producer-key-carry.test.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,12 +97,16 @@ const DELIBERATELY_NOT_SERVED: readonly string[] = [];
9797
* Not a record field: it is a property of the running engine, recomputed per
9898
* read and never stored. `isWritablePackage` is the same predicate the
9999
* authoring and lifecycle gates use.
100+
* - `disableable` — the disable door's verdict (`withDisableableVerdict`,
101+
* #28318). Not a record field either, for the same reason: it is computed
102+
* per read by `isDisableablePackage`, the predicate `PATCH
103+
* /packages/:id/disable` asks, and never stored.
100104
*
101105
* Compared by SET EQUALITY against the measured `served − record`, so both
102106
* directions are loud: a stamp that stops reaching the wire (the reorder this
103107
* card is about) and a stamp that arrives without a decision.
104108
*/
105-
const DOOR_COMPUTED_STAMPS: readonly string[] = ['writable'];
109+
const DOOR_COMPUTED_STAMPS: readonly string[] = ['writable', 'disableable'];
106110

107111
/** Authenticated caller holding the ADR-0106 D4 read capability. */
108112
const reader = (): any => ({

0 commit comments

Comments
 (0)