Skip to content

Commit 50015d8

Browse files
fix(objectql)!: the registry fold merges validation rules by name; a tenant's same-named copy carries only its message and active, and a changed condition is reported at load, never run (#28445)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoSvkSSxNZcoCwT3AFsNcUvy)_ Fixes #27949 (the load-path half of ruling B; the save-door refusal is a follow-up card the seat files, `Blocked-by:` this PR). Clause-②: no (narrowing) Metadata-protocol: none Ruling-ref: 6545641964 (letter B, maintainer 「同意」 2026-10-31T15:47Z), under ruling 6524229156 (letter C′, maintainer 「同意」 2026-10-30T13:40Z). ## 维护者速读 - 改了什么:同一对象里的校验规则按 `name` 合并,不再把各层的规则数组拼接。租户覆盖层里与包内规则同名的副本只取它的 `message` 和 `active`,条件和类型始终用包里的;不同名的规则照旧叠加。加载时发现副本改了条件或类型,只记一条 `error` 日志并照包的规则执行,不抛错。ADR-0029 D9.2a 加一段带日期的说明。 - 为什么改:租户在 Studio 里改写扩展包某条规则的提示语后,旧折叠会让两条同名规则同时生效,被拒的写入会报两句话;同时租户复制的规则会冻结住,包里后来的修复到不了租户。 - 风险与回滚:改了条件的租户副本不再执行自己的条件,改由包的条件判定(启动日志点名该规则);升级不会因存量数据失败。没有任何键的增删。回滚即 revert 本 PR。 - 先看:`packages/objectql/src/registry.ts` 的 `mergeValidationsByName` 与 `withPackagedOwnerRules`、`reportChangedRuleCopies`(只报告不拒绝);`docs/adr/0029-…md` 的 D9.2a 说明。 - 两分钟验证:`pnpm --filter @objectstack/objectql exec vitest run --maxWorkers=2 src/registry-validation-rule-by-name.test.ts`,预期 14 个用例全绿。 - 需要你做的:本 PR 改了 `docs/adr/**`(Tier H),合约复审通过后请用 os-zhuang 批准。 ## What changes **The fold merges `validations` by name** (`packages/objectql/src/registry.ts`). A validation rule's identity within an object is its `name`, so `mergeObjectDefinitions` no longer concatenates the arrays. `mergeValidationsByName` lets a later layer's rule replace every earlier rule of its name, and adds a rule of a new name. Rules of different names stay additive, as ADR-0029 D9.2a protects. Between two code layers, the later layer's same-named rule replaces the earlier one, the way a field does. **What a tenant's copy carries.** When the fold's base is a tenant overlay (or a runtime-authored owner), `tenantRuleSettings` reads each rule's `message` and `active` by name, first copy wins. The packaged rule runs with those two keys and nothing else from the copy: - `withPackagedOwnerRules` replaces a copy of the packaged OWNER's rule with the owner's rule plus the copy's `message` / `active`, so a later package fix to that rule reaches the tenant. - An extension's rule is merged the same way through `mergeValidationsByName`. - `active: false` on the copy switches the rule off. - A rule the overlay leaves out stays out, as D9.2's replace has always meant. **Load path: report, never refuse (ruling B).** `reportChangedRuleCopies` compares each tenant copy with the packaged rule set (`packagedRules`). The comparison reads omitted keys at the schema defaults, so a parse that stamped `events` / `priority` / `severity` is not a change. A copy that changes anything beyond `message` and `active` is named once per registry at `error` (`validation_rule_copy_changed`), with its consequence and the ruling's prescription. The fold has already run the package's rule. Nothing throws, so a package upgrade never fails a boot on stored data. **Predicate for the save door.** `SchemaRegistry.tenantRuleCopyRefusal(name, body)` returns `ValidationRuleCopyRefusedError` (`INVALID_METADATA`, 422, `objectName`, `ruleName`, `changedKeys` with `type` first, the prescription in the message) for a body that changes a packaged rule's condition or type, and `null` otherwise. Nothing calls it yet. Wiring it into the metadata save door is the follow-up card. Under B, `registerObject` needs no build-time refusal, and this PR adds none. **Idempotence (#8027).** `subtractExtenderContributions` no longer subtracts `validations`. The by-name merge already replaces every base copy of an extender's rule name, so a folded base re-folds to itself. Subtracting first would also strip the tenant's `message` / `active` off a reworded copy before the fold reads them. `getPackagedObjectBase` serves the packaged rules merged by name the same way. **ADR-0029 D9.2a** gains a dated note recording both rulings: rules of different names add; a same-named rule merges by name with the condition owned by the package; the loud refusal sits at the save door; the load path only reports. **Changeset** `.changeset/27949-validation-rules-merge-by-name.md`: `@objectstack/objectql` `patch` (ruling A: `Metadata-protocol: none` grades every entry `patch`), carrying the BREAKING banner and the ADR-0087 `not-required` disposition. **Tests.** - New `registry-validation-rule-by-name.test.ts` has 14 cases in five blocks: a reworded copy is one rule; a changed condition or type is refused by the predicate and never runs at load; `active: false` deactivates; different names add; and re-folding is idempotent, including a legacy row stored while the fold still appended. - `engine-validation-tenant-rewrite.test.ts` changes one expectation. The extension rule is now served and refused once, with the tenant's sentence, on every header (before: the tenant's copy plus the translated original). ## Tests All on head `e5e62b28` (seat 4's `2a499b92` merged with `main` `630b4078`, then the ruling-B changeset and ADR alignment). - `pnpm --filter @objectstack/objectql exec vitest run --maxWorkers=2`: Test Files 507/507, Tests 9847/9847. - `pnpm --filter @objectstack/objectql typecheck`: exit 0 (`check:test-typecheck: OK`, debt held). <details><summary>12 one-time ablations (each through scripts/ablation-replace.mjs, restored to the HEAD blob, git diff HEAD empty after each)</summary> Run: `pnpm --filter @objectstack/objectql exec vitest run --maxWorkers=2 src/registry-validation-rule-by-name.test.ts src/engine-validation-tenant-rewrite.test.ts` (18 cases). The suite imports `./registry.js` from source, so no dist rebuild is involved. Every mutation went red: | # | mutation in `registry.ts` | red | |:--|:--|:--| | A01 | `mergeValidationsByName` concatenates again | 8 failed / 18 | | A02 | the tenant's `message` is not read | 8 failed | | A03 | the tenant's `active` is not read | 1 failed (`active: false` deactivates) | | A04 | `tenantRuleSettings` answers `undefined` | 7 failed | | A05 | `withPackagedOwnerRules` is a no-op (owner copy keeps its own condition) | 1 failed (a package fix reaches the tenant) | | A06 | the tenant copy's condition is carried into the fold | 2 failed (owner fix; changed condition never runs) | | A07 | `tenantRuleCopyRefusal` never refuses | 2 failed (condition, type) | | A08 | `packagedRules` skips extension rules | 5 failed | | A09 | schema defaults not applied before comparing | 1 failed (stamped defaults change nothing) | | A10 | the load report is not called | 1 failed (reported once) | | A11 | the report's once-per-registry guard removed | 1 failed (reported once) | | A12 | tenant settings take the last copy, not the first | 1 failed (legacy appended row) | The first runs of A05, A06 and A08 were refused by the tool as no-ops (the replacement text was already counted in the file). They were re-anchored with distinct replacement text and re-run, and the numbers above come from those re-runs. </details> ## Acceptance notes - `tenantRuleCopyRefusal` has no caller in this PR, on purpose: ruling B puts the refusal at the save door (follow-up card behind the `protocol.ts` serial queue on #6367). - A copy stored before a package upgrade changed the rule cannot be told apart from one the tenant changed. That is why the load path reports and runs the package's rule instead of refusing. - The predicate compares every key except `message`, `active` and `_`-prefixed loader stamps, so it is stricter than "condition or type": any package-owned key (for example `fields`, `events`, `severity`) counts as a change. That matches C′'s "everything else is the package's". - The commit subjects carry `!` from seat 4's commit. The changeset level follows `Metadata-protocol: none` (patch) under ruling A, and the BREAKING banner stays in its body. ## Verification <details><summary>Derived gates: 70 derived, 70 run, 70 exit 0</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` on `e5e62b28c3` derived 70 commands over 5 paths (759 changed lines). Each ran with stdin from `/dev/null`, its exit captured by redirect before any pipe. All 70 exit 0, after a full workspace build (`turbo run build`, dts on, excluding docs and `@object-ui/*`). `dispatch-gates --ran`: `70 derived famil(ies) accounted for — 70 run, 0 NOT-MEASURED`, exit 0. Scoped lint, using the root `lint` script's command over `packages/objectql`: exit 0. Full dogfood (owed by the `(narrowing)` arm) runs once on this head; its result is in the os-dev report on the card. </details> Tier H by path (`docs/adr/0029-…`). It stays a draft until the contract review and the governed approval are on record; the seat lands it. --- _Generated by [Claude Code](https://claude.ai/code/session_01L9qibx3A7AeHSnSr39oxaV)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 80a9f99 commit 50015d8

5 files changed

Lines changed: 705 additions & 54 deletions
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
'@objectstack/objectql': patch
3+
---
4+
5+
fix(objectql)!: a tenant's reworded copy of a packaged validation rule is one rule with the package's, run once with the tenant's sentence: the registry fold merges validation rules by name (#27949)
6+
7+
Clause-②: no (narrowing) — a tenant overlay's same-named copy of a packaged or extension-contributed rule no longer runs its own condition: the package's rule runs, with the copy's `message` and `active`. A write the copy's condition alone refused, or that only the package's rule refuses, is judged by the package's rule. Rules of different names are unchanged.
8+
Metadata-protocol: none
9+
10+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no stored row needs rewriting: the fold reads a stored overlay row as it is, taking a copied rule's message and active from it and the rest from the package. Nothing is tombstoned, and an author has no code to change. -->
11+
12+
**BREAKING** for a tenant overlay that copies a packaged rule (`@objectstack/objectql`, served by every object read and the write door through the registry fold). ADR-0029 D9.2a gains a dated note: "validations stay additive" means rules of different names add; a same-named rule merges by name, with the condition owned by the package.
13+
14+
- **Before.** The fold concatenated `validations`. A Studio GET, edit and PUT of an object stores a copy of every rule the read served, so a tenant who reworded an extension's rule held a copy beside the extension's original: both ran, and a refused write reported the rule twice, once in each sentence. A copy of the owner's rule ran as stored, so a later package fix to that rule never reached the tenant.
15+
- **Now.** A rule's identity within an object is its `name`. Two rules of one name are one rule. A tenant overlay's copy of a rule a code layer ships (the owner or an extension) runs as the package declares it, with the copy's `message` and `active`. `active: false` switches the rule off. A refused write reports it once, in the tenant's sentence, and a package fix to the rule reaches the tenant.
16+
- **A copy that changes more than `message` and `active`** (its `type`, its condition, or any other key the package owns) does not run its own version. The package's rule runs, and the registry names the copy once at `error` (`validation_rule_copy_changed`), with the prescription: to change the condition, add a rule under a new name, or change it in the package. Loading a stored copy only reports it and never fails the boot or an upgrade. `SchemaRegistry.tenantRuleCopyRefusal(name, body)` returns that refusal (`ValidationRuleCopyRefusedError`, `INVALID_METADATA`, 422) for a body before it is stored; refusing such a save at the metadata save door is a follow-up change.
17+
- **Unchanged.** A rule of a new name, the tenant's or an extension's, is added. A rule the overlay leaves out stays out. Between two code layers a later layer's same-named rule replaces the earlier one, as a field does. `getPackagedObjectBase` serves the packaged rules merged by name the same way.
18+
- **Who sees it.** A tenant whose overlay rewords or switches off a packaged rule: the rule now runs once. A tenant whose overlay changed a packaged rule's condition: the package's condition runs instead, and the boot log names the rule. To keep a different condition, add it as a rule under a new name.

‎docs/adr/0029-kernel-object-ownership-and-platform-objects-decomposition.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,42 @@ Binding consequences:
540540
were considered and **rejected**. Dropping scalars from the fold entirely
541541
(#8284's arm B) remains rejected and is not this clause.
542542

543+
> **Note (2026-10-30, #27949; ruling of record 6524229156, letter C′; where the
544+
> refusal sits: ruling of record 6545641964, letter B, 2026-10-31): "validations
545+
> stay additive" means rules of DIFFERENT names add. A same-named rule merges by
546+
> name, with the condition owned by the package.**
547+
>
548+
> A validation rule's identity within an object is its `name` (the schema's
549+
> "unique rule name"). The fold therefore merges `validations` by name across the
550+
> layers, the way `fields` merge by key, instead of concatenating them: two rules
551+
> of one name in one object are one rule. Measured before this note: a tenant
552+
> overlay that reworded an extension's rule (the Studio GET → edit → PUT of the
553+
> folded object stores a copy of every rule it served) held a copy beside the
554+
> extension's original, and both ran, so a refused write reported the rule twice.
555+
>
556+
> - **What the tenant owns.** A tenant overlay's copy of a packaged or
557+
> extension-contributed rule supplies the rule's `message` and `active`
558+
> (`active: false` is the explicit, visible deactivation). Everything else —
559+
> the `type`, the condition and every other key the evaluator reads — is the
560+
> package's: the fold enforces the code layer's rule with the tenant's
561+
> sentence and switch, so a later package fix to the rule reaches the tenant.
562+
> This is the opposite of whole-rule replacement, which would freeze the
563+
> enforced rule against package fixes.
564+
> - **A changed condition or type is refused, loudly, at the save door, with the
565+
> prescription "to change the condition, add a rule under a new name, or change
566+
> it in the package"** — never two rules running beside each other, never a
567+
> silent replacement. The overlay LOAD path never refuses: a copy stored before
568+
> the condition changed (a package upgrade) is indistinguishable from one the
569+
> tenant changed, so the fold never runs a copy's condition and names each such
570+
> copy once, at `error`, with that prescription; it never drops the tenant's
571+
> layer for it, so an upgrade never fails on stored data.
572+
> - **Different names stay additive**, as this clause has always protected: an
573+
> extender's or a tenant's rule of a new name is added. A rule the overlay
574+
> leaves out stays out, as D9.2's replace means. Between two code layers a
575+
> later layer's same-named rule replaces the earlier one, as a field does.
576+
> - **Idempotence (#8027) holds by the merge itself:** a folded base re-folds to
577+
> the same rules, so `validations` are no longer subtracted before the fold.
578+
543579
#### D9.3 — selection is by KIND; priority stays descriptive
544580

545581
`contributors.sort((a, b) => a.priority - b.priority)` (`#contributors`) totals the whole

‎packages/objectql/src/engine-validation-tenant-rewrite.test.ts‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@
1818
* #27559 — the same holds for a rule the second package contributes: when the
1919
* tenant's overlay carries that rule reworded (the Studio GET → edit → PUT of
2020
* the folded object), the packaged message to compare with is the EXTENSION
21-
* package's, so the tenant's sentence is served as written. The fold still
22-
* appends the extension's own copy beside it (validations stay additive,
23-
* ADR-0029 D9.2a), and that copy, unchanged, is still translated.
21+
* package's, so the tenant's sentence is served as written. Since the ADR-0029
22+
* D9.2a 2026-10-30 note the fold merges rules by name, so the tenant's copy and
23+
* the extension's rule are ONE rule: it runs once, with the tenant's sentence.
2424
*
2525
* Both readers are driven off ONE real registry: the refusal of a real write
2626
* (the engine's validator), and the served object as `/meta` translates it —
@@ -259,10 +259,11 @@ describe('ADR-0029 D9.2a a tenant-rewritten rule message, on the refusal and on
259259
.map((r: any) => r.message);
260260
}
261261

262-
it('serves and refuses with the rewrite as written, and still translates the extension copy beside it', async () => {
263-
// The fold is additive for validations: the overlay's reworded copy, then
264-
// the extension's own rule. Only the reworded one diverges from the
265-
// extension package's packaged message.
262+
it('serves and refuses the one rule with the rewrite as written, on every header', async () => {
263+
// [ADR-0029 D9.2a, 2026-10-30 note] The fold merges validations by name:
264+
// the overlay's reworded copy and the extension's rule are one rule, run
265+
// once, with the tenant's sentence — never translated, since it diverges
266+
// from the extension package's packaged message.
266267
const out: Record<string, unknown> = {};
267268
for (const header of ['zh-CN', 'zh', 'en']) {
268269
out[header] = {
@@ -271,12 +272,9 @@ describe('ADR-0029 D9.2a a tenant-rewritten rule message, on the refusal and on
271272
};
272273
}
273274
expect(out).toEqual({
274-
'zh-CN': { served: [EXT_REWRITE, ZH.ext_blocked_needs_reason], refusal: `${EXT_REWRITE} | ${ZH.ext_blocked_needs_reason}` },
275-
zh: { served: [EXT_REWRITE, ZH.ext_blocked_needs_reason], refusal: `${EXT_REWRITE} | ${ZH.ext_blocked_needs_reason}` },
276-
en: {
277-
served: [EXT_REWRITE, PACKAGED.ext_blocked_needs_reason],
278-
refusal: `${EXT_REWRITE} | ${PACKAGED.ext_blocked_needs_reason}`,
279-
},
275+
'zh-CN': { served: [EXT_REWRITE], refusal: EXT_REWRITE },
276+
zh: { served: [EXT_REWRITE], refusal: EXT_REWRITE },
277+
en: { served: [EXT_REWRITE], refusal: EXT_REWRITE },
280278
});
281279
});
282280

0 commit comments

Comments
 (0)