Repository navigation
Commit d6e0967
feat(metadata-protocol,cli,cloud-connection)!: the override write gate — only the base's paired .custom declares an override (ADR-0146 D2) (#28554)
domain:server#1 · os-project-manager · session_01R1q2xdtYgU6FKrZ7LgjPCC
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XNNCo1UH18c8rw38MKwdp8C)_
Fixes #28410
Clause-②: yes (narrowing)
New refusals at the save and publish doors, at `os validate` and at the
marketplace managed install narrow the accepted set; the base's paired
`.custom` declaring an override is admitted beside them. The one
`packages/spec/**` file touched is the error-code provenance ledger: two
rows naming `os validate` and the marketplace install as emitters of the
already-registered `NOT_OVERRIDABLE`; no schema, type or runtime
interface moves.
Metadata-protocol: narrowed
Skills-docs: none — no file under `skills/**` teaches the `overrides`
declaration, a `<base>.custom` package or the sealed-write sentence; the
`content/docs/references/**` pages that show `overrides` are generated
from the spec and do not move.
## 维护者速读
- 改了什么:覆盖写门(ADR-0146 D2,#28390 裁决 A)落在三个门点:保存/发布门、`os
validate`、市场托管安装。只有基础包配对的 `<base>.custom` 能声明
`overrides`;依赖包里与闭包内只读包同名的条目被拒(改名),五类拒绝各有一句(未声明同名、非配对包声明、基础包不在闭包或不含该条目、排除类型、object),flow/action
声明答「尚不可用」。
- 为什么改:依赖包可以在基础包的名字下发布条目,读者拿到哪一份没有定论(#28238 的形状:今天 200)。
- 风险与回滚:收窄只拦闭包内同名与不被接纳的声明;预检计数 hotcrm 与仓内示例为 0 处。码与状态不变(`403
NOT_OVERRIDABLE`),未声明同名的拒绝排在各门已有拒绝之后。回滚即 revert,无数据迁移。
-
先看:`packages/metadata-protocol/src/protocol-packaged-base-refusal.ts`(`judgeOverrideWrite`、`overrideWriteItemsOf`),`protocol.ts`
的保存门与 `promoteDraftForPublish` 两处接线,`cloud-connection` 安装门的步骤 2d。
- 两分钟验证:`pnpm --filter @objectstack/metadata-protocol exec vitest run
src/protocol.packaged-base-refusal.test.ts`,预期 `Tests 63 passed (63)`。
- 需要你做的:卡上的安装门点从 `installPackage` 移到市场托管安装(席位已批);另有一个开放问题:`os build`
要不要也拒(见报告)。
## What changes
- **The rule, once** (`@objectstack/metadata-protocol`,
`protocol-packaged-base-refusal.ts`). `judgeOverrideWrite(subject,
closure)` is a pure verdict: `admit`, one named `refuse`, or
`not_concerned`. It reads N-08's surface from `@objectstack/spec/kernel`
(`OVERRIDE_TYPE_CLASSIFICATION`, `isCustomizationPairOf`,
`customizationPackageId`, `customizationBasePackageId`) and copies none
of it. `overrideWriteItemsOf(body)` is the item walk the two outside
doors share (an action keyed `<objectName>:<name>`, a `views:` container
expanded by the loader's own `expandViewContainer`). Both are exported
from the package index in one export line.
- **The refusals**, all `403 NOT_OVERRIDABLE`, each with its own
sentence:
- (a) `undeclared_same_name`: a dependent's item under the name a
read-only package in its closure ships, on an overridable type. In
`<base>.custom`: "Declare it … or rename the item". Elsewhere: "Rename
the item".
- (b) `declared_outside_pair`: `overrides` on a package that is not the
base's pair.
- (c) `declared_package_outside_closure` ("Declare a dependency on
'<base>' …") and `declared_package_ships_no_such_item`.
- (d) `declared_type_not_overridable`: an excluded type, pointing to a
new item under a new name.
- (e) `declared_object`: pointing to `objectExtensions`.
- `declared_type_not_yet_available`: a declared `flow` ("flow
customization is not yet available") or `action`.
- **Admit.** The pair declaring an override of an item its base ships,
on an open type: the save door skips the sealed refusal for it and the
repository is told a `runtime-only` write (the pair's own row), at the
save and at the promotion.
- **Save and publish doors** (`protocol.ts`). The save door judges every
save; a refused declaration throws before the flow-only regime check (so
a declared flow reads its own sentence, not the clone sentence), and an
undeclared same name throws last, just before the store, so every
refusal the door already answered keeps its code and status (a view
container's name collision keeps its 400, a lock its `ITEM_LOCKED`). The
promotion (`publishMetaItem`, `publishPackageDrafts`) judges the draft
body and throws once, last before the store; a batch publish reports it
in `failed`.
- **Base = read-only.** Only a package `isWritablePackage` answers false
for is a base the gate guards: an override replaces an installed item,
and a writable package's item is edited in place (ADR-0070). Every
artifact a kernel serves is registered through `registerApp`, which puts
it in `manifests`, so this keeps no real base out.
- **The sealed sentence.** On an open type its tail is writer-aware. For
the base's pair (or a write naming no package) it reads "To change it,
declare an override from '<base>.custom' (overrides: { package:
'<base>', basedOn }), or rename the item." For any other package it
reads "To change it, rename the item: only <base>.custom may declare an
override of <base>." The base id is read through the existing
`packagedArtifactOwner`, so no new `lookupArtifactItem` call site.
- **A malformed `overrides` is not a declaration.** A value
`OverrideDeclarationSchema` refuses is not judged as a declaration: the
save door's schema gate answers it (`422 INVALID_METADATA`), and `os
validate`'s schema step reports it.
- **A save naming no package** is re-judged for the package its address
gives (the publish address or the draft address), so it cannot write a
dependent's undeclared same-named row. This is the one write behaviour
refused on purpose (see Tests).
- **`os validate`** (`@objectstack/cli`,
`utils/override-declarations.ts`, step 3a-iii). Each package of the
artifact (or the stack as one package) is judged against its closure,
followed through the artifact's packages. A same name is found where
both packages are in the artifact; a declaration is judged whole
wherever its base lives. Exit 1, the rows on `errors` with `path`,
`code`, `rule`, `packageId`, `message`.
- **Marketplace managed install** (`@objectstack/cloud-connection`, step
2d, before any write). Every delivered package (a `packages[]` artifact
judged per entry) is judged against its closure (registry dependencies
plus the artifact's own) with shippers read from the protocol's
per-package listing. A refusal answers `403 NOT_OVERRIDABLE` with
`details.refusals`; nothing registers and no ledger entry is written. On
an install of a base, `overrideCollisions` on the `200` answer lists
each name an installed dependent already holds undeclared (the judge's
sentence per row); the key is omitted when empty.
## Tests
- `protocol.packaged-base-refusal.test.ts`: the gate describe block, 63
tests in the file, including the package-less save re-judged for its
address's package (the one write behaviour refused on purpose). Red
first on main (`b24adb3a`): 20 failed, 35 passed.
- `protocol.sealed-remedy-kind.test.ts`: the one-sentence pin reads the
declare-or-rename tail from the classification, never transcribed.
- `packages/cli/src/utils/override-declarations.test.ts` (7, unit tier)
and `packages/cli/test/validate-override-declarations.test.ts` (2, the
command, exit code).
-
`packages/cloud-connection/src/marketplace-install-local-override-gate.test.ts`
(6): refusals, nothing written, the pair's admit, the control, the
collision list.
- `protocol.org-scoped-write-refused.test.ts` is green and unchanged
(`git diff 23d1303 -- <file>` empty).
- The #28409 and #28238 read pins in the rest and objectql suites seed
their same-named rows before the gate (pre-gate seeding), so they keep
pinning the read side the gate now keeps from being written.
- Ablations, 19, each through `scripts/ablation-replace.mjs` with its
restore proved clean (`git diff HEAD` empty); each reads red: (a) 7
failed, (b) 4, (c) closure 1, (c) ships 1, (d) 1, (e) 1, not-yet 2,
sealed tail 5, read-only base filter 127 (the org-scoped file), save
door declared throw 4, save door undeclared throw 5, promotion throw 3,
admitted runtime-only intent 1, install refusal 3, install collisions 1,
validate wiring 1. Round 2 adds A18 (writer-aware tail, 1 failed), A19
(malformed `overrides` is not a declaration, 5 failed) and A20
(package-less re-judge, 1 failed). Two first attempts were no-ops (the
anchor's replacement count did not rise) and were redone; one (an early
declared throw at the promotion) read green and was removed as
redundant.
## Acceptance notes
- **The card's `installPackage` gate point moved to the marketplace
managed install** (seat 1 amendment, posted on #28410). `installPackage`
takes a manifest and no items (`PackageInstallManifestSchema`), and the
unmanaged install copies through the save door, which is gated; the
managed install is where a package's items arrive unjudged.
- `os build` does not run the gate. The parity ledger records
`findOverrideDeclarationRefusals` in `VALIDATE_ONLY_GATES` with the
reason; whether the build refuses too is an open question on the card.
- The validate and install tests live beside their doors, not in
`protocol.packaged-base-refusal.test.ts` as the order put it:
metadata-protocol cannot import cli or cloud-connection (they depend on
it).
- Not handled: a rollback (`rollbackMetaItem`) of a declared override
row still computes the `override-artifact` intent from
`isArtifactBacked` alone. Rolling back the pair's row is N-10/N-16
territory and not a door this card names.
- The install door's collision list reads dependents through the
protocol listing (`getMetaItems({ type, packageId })`), which serves
code-registered and stored items alike, so a `.custom` built in Studio
is covered.
## Verification
Run on `21bc1b51` (a merge of `origin/main`) under `os-verify-lock`
(`VERDICT command-exit 0`).
- Merge: the only conflict was
`scripts/engine-double-contract.pinned.json`. Main's pin was taken and
regenerated with `check-engine-double-contract.mjs --write`; it differs
from main only by this branch's three rows (the gate test's `delete`,
`findOne` and `update`). `check:engine-double-contract` exit 0.
- `pnpm install --frozen-lockfile` exit 0; closure rebuild exit 0.
Typecheck metadata-protocol, cli and cloud-connection: exit 0.
- metadata-protocol full suite: Test Files 290 passed | 4 skipped (294),
Tests 21929 passed | 26 skipped.
- objectql full suite: Test Files 512 passed, Tests 9888 passed.
- rest full suite: Test Files 368 passed, Tests 7195 passed | 352
skipped.
- cloud-connection full suite: Test Files 64 passed, Tests 778 passed.
- cli unit tier plus `test/validate-override-declarations` and
`test/validate-build-gate-parity`: Test Files 290 passed | 1 skipped,
Tests 3730 passed | 8 skipped.
- Derived gates (`dispatch-gates.mjs --commands`, reconciled with
`--ran`): `✓ dispatch-gates --ran: 98 derived famil(ies) accounted for —
98 run, 0 NOT-MEASURED`, including `check:error-code-provenance` and the
i18n and dual-build families with their prerequisites built first.
- Ablations: the round-1 sixteen plus A18–A20, all red, each restore
proved clean.
Re-run on `cd852e2a` (a merge of `origin/main` bringing in #28595, then
the re-seed of `packages-customizations.test.ts`) under `os-verify-lock`
(`VERDICT command-exit 0`).
- Red first: CI Test Core (3/8), job 124795448012, 2 failed on
`21bc1b51` (the two `packages-customizations.test.ts` cases seeding
through `saveMetaItem`, which the gate now refuses).
- Re-seed: each case first asserts the door's 403 `NOT_OVERRIDABLE` with
its own sentence ("carries `overrides`" for the non-pair declaration,
"declares no override" for the undeclared pair row), then lays the row
down below the gate through the same draft save and publish with the
gate shadowed to `not_concerned` for that save alone. The read
assertions are unchanged.
- `packages-customizations.test.ts`: 13/13. `@objectstack/runtime` full
suite: Test Files 505 passed (505), Tests 9106 passed | 19 skipped.
- Derived gates: `✓ dispatch-gates --ran: 98 derived famil(ies)
accounted for — 98 run, 0 NOT-MEASURED`.
- `4a25192b` changes only the `declarationOf` docblock (it now names the
door's 422 `INVALID_METADATA`); comment only in a non-exported function,
eslint exit 0.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01FEkQ5oYcVD24TCK4yt5e1i
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent d2c4874 commit d6e0967
20 files changed
Lines changed: 1956 additions & 34 deletions
File tree
- .changeset
- packages
- cli
- src
- commands
- utils
- test
- cloud-connection/src
- metadata-protocol/src
- objectql/src
- rest/src
- runtime/src/domains
- spec/src/api
- scripts
| 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 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
74 | 74 | | |
75 | 75 | | |
76 | 76 | | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
77 | 80 | | |
78 | 81 | | |
79 | 82 | | |
| |||
658 | 661 | | |
659 | 662 | | |
660 | 663 | | |
| 664 | + | |
| 665 | + | |
| 666 | + | |
| 667 | + | |
| 668 | + | |
| 669 | + | |
| 670 | + | |
| 671 | + | |
| 672 | + | |
| 673 | + | |
| 674 | + | |
| 675 | + | |
| 676 | + | |
| 677 | + | |
| 678 | + | |
| 679 | + | |
| 680 | + | |
| 681 | + | |
| 682 | + | |
| 683 | + | |
| 684 | + | |
| 685 | + | |
| 686 | + | |
| 687 | + | |
| 688 | + | |
| 689 | + | |
| 690 | + | |
| 691 | + | |
| 692 | + | |
661 | 693 | | |
662 | 694 | | |
663 | 695 | | |
| |||
| 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 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
0 commit comments