Repository navigation
Commit 3e0fd7a
feat(spec,metadata-protocol,rest,objectql,runtime): GET /meta/object serves switched-off packaged actions beside the item, and the disabled-action refusal reads as a plain sentence (#27964)
<!-- claude-projects-attribution: {"github_login":"marchtian"} -->
_Requested by **田騏** · [project
thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiEosMC3zDfHaauURHFNq1GJ)_
Fixes #27842
Clause-②: yes (widening)
Metadata-protocol: added
## 维护者速读
- **改了什么**:`GET /meta/object/:name`(含默认缓存通道)与 `GET /meta/object` 列表,在
item 旁边新增 `disabledActions`,列出本部署在「设置 › 打包自动化」里被关掉的打包动作;点被关动作时的 409
提示改成给终端用户看的白话句子。
- **为什么改**:以前元数据读取里没有“已关闭”这件事,按钮照常显示、一点就红色报错,报错还点名系统表和 ADR;这是
#27504(控制台隐藏按钮)的服务端一半。
- **风险与回滚**:新键是可选的、在 item 之外,`item.actions`
一字不改;没有台账的部署不出这个键,行为同今天。代价是带键的对象读取不再回 304(与 #23316 的 `registration`
同一取舍)。回滚即还原本 PR。
-
**先看**:`packages/metadata-protocol/src/protocol-action-activation-reads.ts`(读取缝与“缺席≠空”)、`packages/rest/src/meta-item-read-routes.ts`(对象缓存通道的
304 让路那一处)、`packages/spec/src/api/protocol.zod.ts`(三个 schema 的新键与说明)。
- **两分钟验证**:`pnpm --filter @objectstack/metadata-protocol exec vitest
run src/protocol.object-disabled-actions.test.ts`,预期 11 条全绿;在 showcase
关掉 `showcase_mark_done` 后 `GET /api/v1/meta/object/showcase_task` 返回
`"disabledActions":["showcase_mark_done"]`。
- **需要你做的**:在本 PR 里批准键名 `disabledActions`(单项读取为名字数组,列表为按对象名分组的同名键)——这是
Clause-② yes 的协议新增,键名由你定。
## What changes
The action twin of `registration` (#23316, PR #23358), served beside the
item and never inside it.
- **Spec** (`@objectstack/spec`, minor). `GetMetaItemResponseSchema` and
`GetMetaItemCachedResponseSchema` gain the optional `disabledActions:
string[]`; `GetMetaItemsResponseSchema` gains the optional
`disabledActions: Record<objectName, string[]>`. `IObjectQLEngine`
(`contracts/objectql-engine.ts`, the engine contract the dispatch doors
already reach) gains the optional `getDisabledActions(): string[] |
undefined`. Docblocks state the four choices below.
- **The fact** (`@objectstack/objectql`).
`ObjectQL.getDisabledActions()` answers the names the engine's
`ActionActivationProjection` switches off (the projection both dispatch
doors consult before the 409), or `undefined` while no ledger is
attached. `listDisabledActions()` keeps answering `[]` for both cases.
- **The seam** (`@objectstack/metadata-protocol`).
`protocol-action-activation-reads.ts` reads
`getServicesRegistry().get('objectql').getDisabledActions` per call, the
way `getFlowRegistration` is read from `automation`. `metadata-protocol`
imports nothing from `objectql`. The item read (served face, not on
draft returns) spreads `disabledActions` beside `lock`; the list spreads
it beside `items`, one entry per listed non-draft object;
`getMetaItemCached` carries it beside `data` and skips the 304 when it
is present.
- **The default door** (`@objectstack/rest`). The cached branch of `GET
/meta/:type/:name` rebuilds the envelope with `disabledActions` for
`object`. An object's validator is folded and compared in REST
(`audienceFolds`), so the REST-side 304 also stands down for a read that
carries the key. The ETag header itself is unchanged.
- **The plain sentence** (`@objectstack/objectql`,
`@objectstack/runtime`). `describeDisabled()` now reads: "This action is
turned off for this deployment. An administrator can turn it on again
under Setup › Packaged automation, or you can use another action." No
table, no ADR, no tracker number. The 409 and the `ACTION_DISABLED` code
are unchanged. `ObjectQL.describeDisabledAction()`, which both doors
call exactly when they refuse, writes one `info` log line with the code,
the action name, `sys_metadata_activation` and ADR-0126 §8 item 2.
`disabledActionRefusal`'s fallback for an engine with no sentence is
plain as well.
### The key name, and empty versus absent
- **Key name: `disabledActions`**, the triage route's spelling, on all
three reads (the list keyed by object name, as `registrations` is keyed
by flow name). **The maintainer approves the key name in this PR**
(Clause-② yes).
- **Absent vs `[]`.** Measured on `registration`: when the engine
answers, every served flow gets a verdict (`unregistered` included) and
the list holds one entry per listed non-draft flow (`Object.fromEntries`
over every item); the key is absent only when no engine declares the
member. This PR does the same. The key is **absent** when no ledger
answered: no `objectql` service, an engine without the member, or
`getDisabledActions()` returning `undefined` because no store is
attached. It is **`[]`** when a ledger answered and none of this
object's actions is off. That leaves absence to mean "unknown, keep
today's behaviour" and never "nothing is switched off". The choice and
its reason are in the spec docblock.
- **Which names.** The names in the served `item.actions[]` that the
projection holds, in declared order. Packaged standalone actions bound
to the object are merged into `actions[]` by `defineStack` /
`registerApp` (`mergeActionsIntoObjects`), so they are covered. The key
never names more than `item.actions` already discloses.
## Tests
- `metadata-protocol` — `src/protocol.object-disabled-actions.test.ts`
(new, 11 cases): the names of this object only; `item.actions`
byte-identical with and without the key; `[]` for no matches and for an
object with no actions; absent for no engine, an engine without the
member, and an engine with no ledger; the plural type folded; other
types are never asked; the execution face carries none; the list keyed
by object name with `[]` entries, one engine call per list; a draft gets
no entry; the cached door carries it beside `data` with the same ETag; a
read that carries it is not answered 304 while the unjudged control is.
- `rest` — `src/meta-object-cached-disabled-actions.test.ts` (new, 4
cases): the default cached object door carries the key, `[]` and
absence; with `If-None-Match` equal to the issued ETag the judged read
answers 200 and the unjudged control answers 304.
- `objectql` — `src/protocol-meta-disabled-actions.test.ts` (new, 3
cases): the real `ObjectQL` and the real protocol through the service
table; a `setActionActive` flip appears on the next item read, the list
and the cached door; no ledger means no key.
`src/action-activation.test.ts`: `getDisabledActions` (`undefined` /
`[]` / names), the log line, and the plain-sentence pin.
- `runtime` — `src/domains/action-activation-dispatch.test.ts`: the REST
door's 409 + code + the first sentence + no table/ADR/tracker number;
the MCP door serves the same sentence from the one producer; the
no-sentence engine fallback is plain. The doubles there and in
`api-action-forward.test.ts` now call the real
`ActionActivationProjection.describeDisabled`, not a transcribed copy.
- `spec` — `src/api/meta-item-response-shapes.test.ts`: type-level `Eq`
pins for the three keys, parses for names / `[]` / absent, and a located
refusal for a non-string name.
- Pin sweep: every pin of the old sentence and `ACTION_DISABLED`'s
message was flipped in one pass: the two files above,
`packages/qa/dogfood/test/packaged-action-disabled-dispatch-live.dogfood.test.ts`
(sentence helper),
`packages/qa/dogfood/test/packaged-activation-ledger-reach.dogfood.test.ts`
(`/ACTION_DISABLED|is disabled/` → the code), and
`docs/qa/platform-checklist/areas/api-backend.json`
(`api-backend.packaged-action-disabled-dispatch` acceptance[0], revision
9 → 10 with a history entry). `ui/` carries no pin of the sentence or
the code.
Full suites on the final head (merge of `origin/main` included):
| Package | typecheck | test |
|---|---|---|
| `@objectstack/spec` | 0 | 0 — 756 files, 22483 passed, 1 todo |
| `@objectstack/metadata-protocol` | 0 | 0 — 283 files (4 skipped),
21854 passed, 26 skipped |
| `@objectstack/objectql` | 0 | 0 — 493 files, 9587 passed |
| `@objectstack/rest` | 0 | 0 — 350 files, 6759 passed, 332 skipped |
| `@objectstack/runtime` | 0 | 0 — 481 files, 7837 passed, 19 skipped |
The first runtime typecheck exited 1 on
`organization-ownership-boot-guard.turso-remote.kernel.test.ts` (TS2307,
`@objectstack/driver-turso` had no local `dist`). That file is not in
this diff. After building `driver-turso` the rerun exited 0. The two
dogfood files boot example apps and were not run locally; CI's Dogfood
Regression Gate runs on `main`'s push battery, not on this PR.
### Ablation (serve path)
`packages/metadata-protocol/src/protocol.ts`: the item read's
`...(readDisabledActions ? { disabledActions:
readDisabledActions(decorated) } : {})` was replaced with `/*
ABLATION-27842 */` (`scripts/ablation-replace.mjs`). Then `vitest run
src/protocol.object-disabled-actions.test.ts` gave **5 failed / 6
passed**. Red: names on the item read; `[]` cases; the plural fold; the
cached door carries it; no 304 while carried. Green: the absence
controls, the other-type case, the execution face and the three list
cases, which use their own spread. Restored by the same tool; the blob
equals HEAD and `git diff HEAD` is empty.
## Acceptance notes
- **The 304 trade, stated for the contract review.** The card fixes the
#23316 trade: never in the ETag, never 304 when present. Any deployment
that composes `sys_metadata_activation` (every `PlatformObjectsPlugin`
boot) attaches a ledger, so every cached `GET /meta/object/:name` there
now answers 200 with the full body. A ledger with no rows still serves
`[]`. The alternative is to fold the switched-off names into the
REST-side validator, as REST already folds visibility, runtime-view and
audience fingerprints. That keeps 304s and stays correct. It is not done
here because the card rules it out.
- **The log line** is `info` and written by the engine in
`describeDisabledAction`. That method is the one place both doors pass
on every refusal, and it holds the host's logger. The dispatcher's
`deps.logger` is not wired on `HttpDispatcher`. The sentence producer
`ActionActivationProjection.describeDisabled` stays pure.
- **Not changed.** The 503 `SERVICE_UNAVAILABLE` refusal of the
activation write door still names `sys_metadata_activation` and
ADR-0126. It answers an administrator's flip, not an end user's click,
and the card does not name it.
- `docs/qa/platform-checklist/areas/platform-core.json` (the ledger
posture note) says "the data-API read IS the only 'what is off here'
surface today". After this PR, `GET /meta/object` also answers it. Left
for the checklist owner. Carrier: seat.
- The flow twin's ledger refusal (`describeDisabledFlow`,
`packages/services/service-automation/src/subflow-guards.ts`) still
names `sys_metadata_activation` and ADR-0126 §7.2 in the `FLOW_DISABLED`
message. QA keys the ledger-vs-status distinction on that message
(automation checklist, negative[3]), so a change there is its own
decision. Carrier: seat.
## Verification
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` on the final head `7237921e36`: **119
commands**, each exit code recorded before any pipe. `--ran`: "119
derived, 119 run, 0 NOT-MEASURED, 0 UNRUN" (exit 0).
- On the first pass:
- `check:skill-examples` and `check:dual-build-cjs-loads` exited **3**
(PREREQUISITE NOT MET: no `dist/` for packages outside the touched
closure). After `pnpm turbo run build --filter='./packages/**'`, both
exited 0.
- `check:engine-double-contract` exited **1** (RETAINED: the new
metadata-protocol test's pinned `findOne` double was not yet in the
ledger). Fixed with `--write`, which adds only that one entry to
`scripts/engine-double-contract.pinned.json`, and committed. The rerun
exited 0.
- That ledger commit derived 8 more `scripts/` gates. All 8 exited 0.
- `node scripts/check-adr-0087-registration.mjs --base origin/main`,
`check-changeset-no-major`, `check-empty-changeset`, `check:generated`,
`check:api-surface` and `check:authorable-surface` are all in the 119
and all exited 0.
- Diff: 23 files, +1127 / −45 (under the 3000-line human-merge
threshold).
- Not measured here: the CI-only jobs dispatch-gates lists outside the
runnable set (Build Core, Build Docs, the type-check lanes), and the
Dogfood and Temporal jobs, which run on `main` after the merge.
Independent review: none run (quota); the PR waits for the seat's
contract-review hand-off.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_017ihL2fi9zfJhUTubyJYb6V
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent bc496bf commit 3e0fd7a
23 files changed
Lines changed: 1131 additions & 48 deletions
File tree
- .changeset
- content/docs/references/api
- docs/qa/platform-checklist/areas
- packages
- metadata-protocol/src
- objectql/src
- qa/dogfood/test
- rest/src
- runtime/src
- domains
- spec
- authorable-surface
- src
- api
- contracts
- scripts
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1332 | 1332 | | |
1333 | 1333 | | |
1334 | 1334 | | |
| 1335 | + | |
1335 | 1336 | | |
1336 | 1337 | | |
1337 | 1338 | | |
| |||
1458 | 1459 | | |
1459 | 1460 | | |
1460 | 1461 | | |
| 1462 | + | |
1461 | 1463 | | |
1462 | 1464 | | |
1463 | 1465 | | |
| |||
1522 | 1524 | | |
1523 | 1525 | | |
1524 | 1526 | | |
| 1527 | + | |
1525 | 1528 | | |
1526 | 1529 | | |
1527 | 1530 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1674 | 1674 | | |
1675 | 1675 | | |
1676 | 1676 | | |
1677 | | - | |
| 1677 | + | |
1678 | 1678 | | |
1679 | 1679 | | |
1680 | 1680 | | |
| |||
1706 | 1706 | | |
1707 | 1707 | | |
1708 | 1708 | | |
1709 | | - | |
| 1709 | + | |
1710 | 1710 | | |
1711 | | - | |
| 1711 | + | |
1712 | 1712 | | |
1713 | 1713 | | |
1714 | 1714 | | |
| |||
1833 | 1833 | | |
1834 | 1834 | | |
1835 | 1835 | | |
| 1836 | + | |
| 1837 | + | |
| 1838 | + | |
| 1839 | + | |
| 1840 | + | |
| 1841 | + | |
1836 | 1842 | | |
1837 | 1843 | | |
1838 | 1844 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
0 commit comments