Skip to content

Commit 26f5719

Browse files
feat(scripts): codemod-split-protocol --members moves the bodies E1 refuses, unedited, and retires nineteen protocol.ts facade rows (#30954)
<!-- claude-projects-attribution: {"github_login":"os-elon-musk"} --> _Requested by **Elon** · [project thread](https://claude.ai/code/project/chan_01WedDzV26nniwxv7jC88B9D?thread=cmsg_01WedDzV26nniwxv7jC88B9DKNzscdiyWjPUtwr9RQB2g1)_ Part of #30147 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`scripts/codemod-split-protocol.mjs --members` 新增三种不改写方法体的搬移形式(`.call(host)` 接收者、statics 转发器、无接收者的 plain 形式)外加静态表搬到叶子模块,并用它把 protocol.ts 上 19 个还留着方法体的成员搬进各自的 facet。 - 为什么改:这 19 个成员是 facade 门禁登记里引用 #30147 的例外行;E1 改写(`this.x` → `host.x`)搬不了它们,只能当例外留在类上。 - 风险与回滚:纯搬移,方法体逐字节不变(撤销证明重建 base 树);公开 `index.d.ts` 的表面不变,只有 14 个 private 成员的 docblock 随方法体搬走;回滚即 revert 本 PR。 - 先看:`packages/metadata-protocol/src/protocol.ts` 顶部新增的 `ObjectStackProtocolImplementationStatics` 与类尾的 static block;`scripts/codemod-split-protocol.mjs` 的 receiver forms 一节;`scripts/check-durability-degradation-log-level.mjs` 的 stub 解析。 - 两分钟验证:`node scripts/codemod-split-protocol.mjs --members --verify --base 616311c`,预期输出 `forms: e1 2, plain 5, statics 5, receiver 3, table 4` 与 `undoing the moves does rebuild … byte-for-byte`,退出码 0。 - 需要你做的:无,席位落地。 ## What changes **The tool.** The members pass (#30518) moved a member only when E1's rewrite could carry it, so it refused a local named `host`, a body that reads no member, and every private static that reads the class. It now ports the two mechanisms the sql-driver codemod grew (#30249, #30306), for those reasons only (`RECEIVER_SOLVES`), and moves the body unedited: - **receiver**: the facet member's `this` is typed as the `Pick` of `ProtocolHost` it reads, and the stub runs it on the host: `return FACET.x.call(protocolHost(this), …)`. - **statics**: `ObjectStackProtocolImplementationStatics`, declared ahead of the class and filled by a static block at its end, forwards each static a moved body reads. A facet module imports it AS the class name, so a body that names the class reads it unedited; a private static that reads `this` runs on it: `FACET.x.call(ObjectStackProtocolImplementationStatics, …)`. - **plain**: a body that reads nothing of the class: `return FACET.x(…)`. - **table**: a private static readonly field's initializer moves to its section's leaf, `protocol-write-gates-tables.ts`, which imports no relative module (an initializer runs while the class is evaluated). - A predicate a moved body reaches through the host gets a host entry typed as the predicate, so the narrowing survives the hop. The undo proof covers every form: from the head alone each stub, facet member, forwarder entry, host entry and leaf is undone and the result is the base tree byte for byte. **The moves.** Nineteen members, all in sections that already have a facet: `reconcileViewExpansions`, `packagelessOverlayWriteRefusal`, `namedBaseOverlayWriteRefusal`, `mergesOverlayAtRead`, `registryAllowsOverlay`, `isOverlayAllowed`, `isRuntimeCreateAllowed`, `codeOnlySourceHint`, `codeOnlyCreateError`, `codeOnlyOverrideError`, `refuseOrganizationScopedWrite`, `overlayPackageMismatchError`, `rethrowUnlessMetadataStoreUnprovisioned`, `objectExtensionItemRefusal`, `packagedBaseRefusal` and the four tables `OVERLAY_ALLOWED_TYPES`, `STATIC_REGISTRY_TYPES`, `RUNTIME_CREATE_ALLOWED_TYPES`, `OVERLAY_CAPABLE_TYPES`. Forms: e1 2, plain 5, statics 5, receiver 3, table 4. `protocol.ts` goes from 13,007 to 12,577 lines. **The registry.** The nineteen rows are deleted (46 to 27 exceptions). `triggerAutomation` stays, its reason rewritten as an accepted exception: its body is one `throw`, and its section has no facet module, which this pass never starts. `getDiscovery` (a hand move) and the engine.ts and sql-driver.ts rows are the later PRs of this card. **Followers of the moved bodies.** - `check-durability-degradation-log-level.mjs` resolved a stub only in the E1 and facade-host shapes, so three read seams whose catch delegates to the moved `rethrowUnlessMetadataStoreUnprovisioned` read as inventing an answer. Its resolver now follows the receiver, statics and plain stubs to the facet member, and a facet member's `this.x()` through the imported host or forwarder interface. Its output on this tree is byte-identical to the base's. - Three source-reading pins in `packages/metadata-protocol` follow the moved bodies: the bracketed-opener scan's producer floors, the `registerItem(` call site's file, and the view-expansion record's forwarder read. - One platform-checklist citation (`protocol.ts#refusal`) points at `protocol-write-gates.ts`. ## Why Ruling 6624345766 item 3 wants every facade-gate exception row to name the card that moves it, and #30147 phase 3 measured that one codemod port would retire about 19 of its 21 protocol.ts rows (comment 6653253380). The rows that stay are named in this card's report. ## Tests - `node scripts/codemod-split-protocol.mjs --self-test`: 112 cases in 13 batteries pass (85 in 10 before). The three new batteries generate each form on a fixture, fail ten mutations of the proof, and refuse seven inputs no form carries. - `check-durability-degradation-log-level.mjs --self-test`: 86 read-seam cases pass (81 before). Ablation: the five new cases against the base resolver fail the three positive ones; the two negative controls pass on both. - `@objectstack/metadata-protocol` vitest: base `4d56914aaa` 320 files passed, 4 skipped; 22,487 tests passed, 26 skipped. Head `ae519e3e99`: 320 files and 22,489 tests pass, 26 skipped (the two new producer rows of the bracketed-opener pin are the +2; one file first read a `spec` dist built before the rebase onto `616311c126` and passes, 18/18, once rebuilt). - `packages/rest` vitest at `7d49cfc21` (this branch before its rebase onto four unrelated `main` commits): 398 files, 7,752 tests passed, 354 skipped. At base the local worktree loaded 383 of 398 files (15 import a sibling package's `src` that the worktree had no `node_modules` for), all of them passing. `discovery-search-capability-agreement.test.ts` 4/4 at base and head. ## Acceptance notes - **The `.d.ts` bar.** The public surface of `dist/index.d.ts` and `dist/index.d.cts` is equal. The files are not byte-equal: 14 private members' docblocks changed, because a private member's docblock moves with its body (docblock ownership, as in #29985). Stripped of docblocks the two sides are identical (sha256 `5cf3216a10daa533…` base, `9cab7eb90040d456…` head). - **The one difference a body could see.** A static reached through the forwarder runs with the class as `this`, never a subclass; every static it forwards is private, so no subclass reaches one. - **Doc hover.** `{@link ObjectStackProtocolImplementation.x}` in a facet module that imports the forwarder now resolves to the forwarder. - No open pull request touches `packages/metadata-protocol/src/protocol*.ts` (checked against all open pulls at the time of writing). ## Verification <details><summary>Undo proof</summary> `node scripts/codemod-split-protocol.mjs --members --verify --base 616311c` at `ae519e3e99`: exit 0. ```text undo proof (#30518, #30147): 19 moved member(s) (objectExtensionItemRefusal, rethrowUnlessMetadataStoreUnprovisioned, mergesOverlayAtRead, registryAllowsOverlay, isOverlayAllowed, isRuntimeCreateAllowed, codeOnlySourceHint, codeOnlyCreateError, codeOnlyOverrideError, refuseOrganizationScopedWrite, packagedBaseRefusal, packagelessOverlayWriteRefusal, namedBaseOverlayWriteRefusal, overlayPackageMismatchError, reconcileViewExpansions, OVERLAY_ALLOWED_TYPES, STATIC_REGISTRY_TYPES, RUNTIME_CREATE_ALLOWED_TYPES, OVERLAY_CAPABLE_TYPES); forms: e1 2, plain 5, statics 5, receiver 3, table 4; host-split check: 2/2 E1 move(s) pass (the receiver forms move bodies unedited, proved byte-equal); protocol.ts 13007 -> 12577 lines; undoing the moves does rebuild the base protocol.ts, protocol-host.ts and section modules byte-for-byte once the 9 import binding(s) only moved bodies read are pruned from the base (OBJECT_EXTENSION_TYPE, ObjectExtensionRegistry, SINGULAR_TO_PLURAL, metadataReadFailureError, namedBaseCloseSubject, objectExtensionItemRefusal, packagedBaseRegimeRow, packagelessCloseSubject, packagelessOverlayWriteRefusal) ``` </details> <details><summary>Facade gate and companions</summary> `node scripts/check-facade-delegation-only.mjs`: exit 0, 27 named exceptions. `pnpm --filter @objectstack/metadata-protocol typecheck` exit 0, `build` exit 0. `pnpm check:platform-checklist` exit 0. `pnpm --filter @objectstack/spec check:liveness` exit 0. eslint on the changed files: clean. </details> <details><summary>dispatch-gates</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` at `ae519e3e99`: 86 families derived, all 86 run, all exit 0 (codes captured before any pipe). `--ran`: 86 derived, 86 run, 0 NOT-MEASURED, 0 UNRUN. Four gates first answered PREREQUISITE NOT MET or red on a partial build or a shallow clone (`check-plugin-teardown-shape --self-test`, `check:dual-build-cjs-loads`, `check:lean-entry-closure`) or before the durability resolver fix (`check:durability-log-level`); each exit 0 on the re-run after a full `pnpm build`. </details> <details><summary>Changed lines</summary> 2,459 changed lines (+1,720 / −739, 15 files, changeset included), under the 3,000 budget. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, 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. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016WV4cxm997Tr9c3JFQTKGj --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7569fb5 commit 26f5719

16 files changed

Lines changed: 1725 additions & 740 deletions
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
'@objectstack/metadata-protocol': patch
3+
---
4+
5+
refactor(metadata-protocol): nineteen more `protocol.ts` members hand their bodies to their facets
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
- Nineteen members of `ObjectStackProtocolImplementation` that the facade gate still let keep a body (the overlay and runtime-create write gates, the code-only refusals, the registry hydration's view-expansion reconcile and four static type tables) now keep their signatures on the class and delegate in one line to their section's facet, which holds the body, moved unchanged. Four static tables moved to a new leaf module, `protocol-write-gates-tables.ts`. No behaviour changes and nothing to do on upgrade.
11+
- The published `index.d.ts` and `index.d.cts` carry the same public surface; only docblocks of private members change, where a moved body took its docblock with it.

‎docs/qa/platform-checklist/areas/platform-core.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2068,7 +2068,7 @@
20682068
"examples/app-showcase/src/data/extensions/account.extension.ts#AccountExtension (AccountExtension — the shipped fixture, priority 210)",
20692069
"packages/objectql/src/registry.ts#mergeObjectDefinitions (mergeObjectDefinitions — additive fields fold, the spread) + vicinity via engine: packages/objectql/src/engine.ts#registerApp (the objectExtensions loop registering 'extend' contributors — re-pointed #18104: objectExtensions is read off the manifest here, a member access; the loop this item means runs inside registerApp, which this file declares)",
20702070
"packages/spec/src/data/object.zod.ts#ObjectExtensionSchema (ObjectExtensionSchema — what an extension may carry, the #4001 silently-dropped history, 'Fields to add/override', priority wins-on-conflict; defineObjectExtension)",
2071-
"packages/metadata-protocol/src/protocol.ts#refusal (the NOT_OVERRIDABLE refusal: a packaged item is sealed by its managed package, ADR-0131 D6)",
2071+
"packages/metadata-protocol/src/protocol-write-gates.ts#refusal (the NOT_OVERRIDABLE refusal: a packaged item is sealed by its managed package, ADR-0131 D6)",
20722072
"packages/plugins/plugin-auth/src/managed-extension-fields.ts + managed-extension-fields.test.ts (the build-time collision gate — better-auth-managed objects ONLY; adopted by ADR-0126 §3 as Regime E prior art, NOT a generic gate)",
20732073
"docs/adr/0126-packaged-metadata-customization-model.md §2-§3 (Regime E: additive contributions at package grain, base never edited, install-grain not per-org)",
20742074
"content/docs/capabilities/integrations.mdx + content/docs/build-without-code.mdx (the E1 docs claim this item grounds)",

‎packages/metadata-protocol/src/protocol-class-head.ts‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
* `resolveCascadeDeleteObjects`, `registerPublishMaterializer`,
88
* `registerUninstallCleanup`, `runUninstallCleanups`,
99
* `registerMutationProjector`, `registerAuthoringGate`,
10-
* `registerCredentialChannel`, `restoreWriteFor`,
10+
* `registerCredentialChannel`, `restoreWriteFor`, `objectExtensionItemRefusal`,
1111
* `registerStoredObjectExtension`, `resyncStoredObjectExtensions`,
1212
* `onMetadataMutation`, `emitMetadataMutation`, `attachMetadataMutationPubSub`,
1313
* `detachMetadataMutationPubSub`, `applyRemoteMetadataMutation`,
@@ -60,6 +60,7 @@ import type {
6060
MetadataMutationProjector,
6161
} from './protocol-mutation-events.js';
6262
import type { MetadataAuthoringGate, MetadataCredentialChannel } from './protocol-authoring-channel.js';
63+
import { objectExtensionItemRefusal } from './protocol-object-extension-item.js';
6364
import type { ProtocolHost } from './protocol-host.js';
6465

6566
export class ProtocolClassHeadFacet {
@@ -201,6 +202,27 @@ export class ProtocolClassHeadFacet {
201202
return { intent, deriveRestoredBody };
202203
}
203204

205+
/**
206+
* [#28574, ADR-0146 D10] The save, publish and restore doors' gate for an
207+
* `object_extension` body written into `binding` (the RESOLVED package of
208+
* the row): {@link objectExtensionItemRefusal}, asked with this engine's
209+
* registry and the package's dependency closure
210+
* ({@link resolveWritePackageScope}). Any other type answers `undefined`.
211+
*/
212+
static objectExtensionItemRefusal(host: Pick<ProtocolHost, 'engine' | 'resolveWritePackageScope'>, type: string,
213+
item: unknown,
214+
name: string,
215+
binding: string | null | undefined,): Error | undefined {
216+
if ((PLURAL_TO_SINGULAR[type] ?? type) !== OBJECT_EXTENSION_TYPE) return undefined;
217+
return objectExtensionItemRefusal(OBJECT_EXTENSION_TYPE, {
218+
item,
219+
name,
220+
binding,
221+
registry: host.engine?.registry as ObjectExtensionRegistry | undefined,
222+
scope: host.resolveWritePackageScope(binding),
223+
});
224+
}
225+
204226
/**
205227
* [#28574, ADR-0146 D10] Register a stored `object_extension` row as its
206228
* package's `'extend'` contributor of the object it names — the WHOLE

‎packages/metadata-protocol/src/protocol-discovery-and-bases.ts‎

Lines changed: 81 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
/**
44
* [#29985 codemod] The "Discovery, types, diagnostics, packaged bases,
55
* credential carry-forward" facet of `ObjectStackProtocolImplementation`: the
6-
* bodies of `getProjectId`, `getMetaTypes`, `getPackagedObjectBase`,
6+
* bodies of `getProjectId`, `getMetaTypes`,
7+
* `rethrowUnlessMetadataStoreUnprovisioned`, `getPackagedObjectBase`,
78
* `getPackagedDashboardBase`, `getPackagedViewBase`, `getPackagedReportBase`,
89
* `packagedArtifactBase`, `objectRegistrationRefusal`,
910
* `restoreTranslatedObjectEchoes`, `restoreInjectedColumnEchoes`,
@@ -55,6 +56,8 @@ import {
5556
toJsonSchemaSafe,
5657
} from './protocol-meta-type-schema.js';
5758
import type { SaveMetaItemRequest } from './protocol-door-requests.js';
59+
import { isMissingTableError } from '@objectstack/metadata/errors';
60+
import { metadataReadFailureError } from './protocol-client-failures.js';
5861
import type { ProtocolHost } from './protocol-host.js';
5962
import { servedOverrideBaseOf } from './served-override.js';
6063
import type { ObjectStackProtocolImplementation } from './protocol.js';
@@ -233,6 +236,83 @@ export class ProtocolDiscoveryAndBasesFacet {
233236
return listing;
234237
}
235238

239+
/**
240+
* [#5532] Decide what a failed READ against `sys_metadata` means, and
241+
* rethrow unless it is the ONE benign reason.
242+
*
243+
* ## The defect
244+
*
245+
* Every overlay read in `getMetaItems`/`getMetaItem` used to `catch {}` into
246+
* its own empty value — `items` left as-is, `item` left `undefined`, the
247+
* draft lookup falling through to the active read. That made a metadata
248+
* store the protocol cannot reach **indistinguishable** from an environment
249+
* where the item was never customised, and the emptiness then travelled
250+
* the whole read chain unremarked:
251+
*
252+
* - `getMetaItemCached` turned it into `not found` — an outage answered
253+
* as "that item does not exist", which is the opposite disposition
254+
* (retry the backend vs. create the item / fix the link);
255+
* - the `state='draft'` read turned it into `NO_DRAFT` / 404 — an outage
256+
* answered as "there is no pending edit", which a publish flow reads as
257+
* "nothing to publish";
258+
* - `getMetaItems` turned it into `items: []` — an outage answered as
259+
* "this environment declares none of these", the exact shape #5108 fixed
260+
* one layer down in `DatabaseLoader` and #5089 in `listForIndex`.
261+
*
262+
* ADR-0110 D3 is the rule: a miss and an outage are different facts with
263+
* opposite meanings, and a consumer must never read one as the other.
264+
*
265+
* ## The one benign reason
266+
*
267+
* `sys_metadata` has not been provisioned yet. There are then genuinely no
268+
* overlay rows, so falling through to the registry / MetadataService IS the
269+
* truth, and a first boot must not explode. Classification is by error TYPE
270+
* through {@link isMissingTableError} — the same predicate `DatabaseLoader`
271+
* (#5108) and this package's own `SysMetadataRepository` (#4867) ask, so a
272+
* driver quirk is taught to the platform once. Conservative in the same
273+
* direction: an unrecognised error is NOT benign, because a false "benign"
274+
* silently mis-answers "does this exist?" while a false "real" costs one
275+
* 503 the caller can retry.
276+
*
277+
* ## [#12536] Not benign is not the same as "the store is down"
278+
*
279+
* A non-benign failure is classified once more before it is wrapped, by
280+
* {@link metadataReadFailureError}: a metadata app's hook may have REFUSED
281+
* this read and marked its refusal with `userMessage` (commit 79c46da90), and that is
282+
* an application refusal, not a dependency outage. Handing it to the 503
283+
* below destroyed the mark at the producer — the two failures left this
284+
* guard as the same envelope with the same sentence. The classification
285+
* splits them; neither category's wording changes.
286+
*
287+
* @throws {@link markedApplicationRefusalError} — [#12536] FIRST, when the
288+
* failure carried a producer's `userMessage` mark (commit 79c46da90): the
289+
* author's text verbatim, in its own refusal category, with the
290+
* cause still carried for the operator and nothing else quoted.
291+
* @throws {@link metadataStoreUnavailableError} — a 503 carrying the driver
292+
* error as `cause`, for every UNMARKED non-benign failure. Not the
293+
* driver error itself: unwrapped, it has
294+
* no status, so the REST boundary would have to guess from the
295+
* message text — and `mapDataError` guesses `no such table` into
296+
* `404 OBJECT_NOT_FOUND`, i.e. straight back into a miss.
297+
* @returns normally ONLY for the benign case, licensing the caller to treat
298+
* the overlay as absent.
299+
*/
300+
static rethrowUnlessMetadataStoreUnprovisioned(error: unknown, readObject: string): void {
301+
// [commit 4cda78c9b] `readObject` is REQUIRED, deliberately. This helper serves
302+
// callers that read four different tables (`sys_metadata`,
303+
// `sys_metadata_audit`, `sys_metadata_commit`, `sys_metadata_history`),
304+
// so a default would silently answer about the wrong one for three of
305+
// them — measured, not hypothetical: the first draft of this repair
306+
// hardcoded `sys_metadata` and turned `diffMetaItem`'s genuinely
307+
// unprovisioned `sys_metadata_history` into a loud failure. A required
308+
// parameter makes the compiler ask the question at every new call site.
309+
if (isMissingTableError(error, readObject)) return;
310+
// [#12536] CLASSIFY, do not assume. A read can fail because the store
311+
// is unreachable OR because a metadata app's hook refused it in its
312+
// own words — see {@link metadataReadFailureError}.
313+
throw metadataReadFailureError(error);
314+
}
315+
236316
/** The body of `ObjectStackProtocolImplementation#getPackagedObjectBase`; the method's docblock there is its contract. */
237317
static getPackagedObjectBase(host: Pick<ProtocolHost, 'engine'>, name: string): unknown {
238318
if (typeof name !== 'string' || name === '') return undefined;

‎packages/metadata-protocol/src/protocol-host.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ export interface ProtocolHost {
137137
readonly isHostCodeDatasource: ObjectStackProtocolImplementation['isHostCodeDatasource'];
138138
readonly isNestedArtifactField: ObjectStackProtocolImplementation['isNestedArtifactField'];
139139
readonly isOverlayAllowed: (typeof ObjectStackProtocolImplementation)['isOverlayAllowed'];
140+
readonly isPackagedBaseRefusal: (typeof ObjectStackProtocolImplementation)['isPackagedBaseRefusal'];
140141
readonly isRuntimeCreateAllowed: (typeof ObjectStackProtocolImplementation)['isRuntimeCreateAllowed'];
141142
readonly isSealedManagedItem: ObjectStackProtocolImplementation['isSealedManagedItem'];
142143
readonly isStoredEntryOfDeclinedName: ObjectStackProtocolImplementation['isStoredEntryOfDeclinedName'];
@@ -163,6 +164,7 @@ export interface ProtocolHost {
163164
readonly organizationScopedWriteRefusal: (typeof ObjectStackProtocolImplementation)['organizationScopedWriteRefusal'];
164165
readonly originGatedRemovalRefusal: ObjectStackProtocolImplementation['originGatedRemovalRefusal'];
165166
readonly overlaidShippedContainerViewNames: ObjectStackProtocolImplementation['overlaidShippedContainerViewNames'];
167+
readonly overlayBaseShippers: ObjectStackProtocolImplementation['overlayBaseShippers'];
166168
readonly overlayLockLayerAt: ObjectStackProtocolImplementation['overlayLockLayerAt'];
167169
readonly overlayPackageMismatchError: (typeof ObjectStackProtocolImplementation)['overlayPackageMismatchError'];
168170
readonly overlayRepos: ObjectStackProtocolImplementation['overlayRepos'];

0 commit comments

Comments
 (0)