Skip to content

Commit 545c1c7

Browse files
refactor(metadata-protocol): getMetaTypes() declares a named return type, pinned equal to the type it returned (#29730)
<!-- claude-projects-attribution: {"github_login":"os-warren"} --> _Requested by **Warren** · [project thread](https://claude.ai/code/project/chan_01U5RdnAAmkSQmZbqh6FtqZ8?thread=cmsg_01U5RdnAAmkSQmZbqh6FtqZ8RqNbmRd8gSUxXNtggBEwUr)_ Fixes #29510 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`getMetaTypes()` 现在声明具名返回类型 `Promise<MetaTypesListing>`,由 spec 已导出的类型组合而成;方法体内一行编译期 `Equal` 断言把它钉成与方法体推断出的类型完全相等。 - 为什么改:原来是推断类型,`index.d.ts` 内联展开 793 行,#25467 每一刀都要人工读这一块原始 diff。现在 d.ts 只印别名,类型一旦漂移 `tsc` 直接报错。 - 风险与回滚:无运行时改动,公开类型不变(已对 main 构建出的 d.ts 做过一次类型相等证明);`MetaTypesListing` 不从包导出,不新增公开名。回滚即 revert。 - 先看:`packages/metadata-protocol/src/protocol-meta-types-listing.ts`(类型定义,注意 `actions` 的两臂);`protocol.ts` 中 `getMetaTypes()` 的签名与结尾 `exact` 一行。 - 两分钟验证:`pnpm --filter @objectstack/metadata-protocol typecheck`,预期 exit 0;把类型里 `schemaId: string;` 改成 `schemaId?: string;` 再跑,预期只在 `exact` 那一行报 TS2322。 - 需要你做的:无,席位落地。 ## What changes - `packages/metadata-protocol/src/protocol-meta-types-listing.ts` (new, 68 lines): `MetaTypesListingEntry`, `MetaTypesListing` and a strict `Equal` type. The entry is `MetadataTypeRegistryEntryParsed` (minus `type`, `allowEnvironmentOverlay`, `actions`) plus the fields the listing adds or overrides: `type: string`, `schemaId`, `allowEnvironmentOverlay: boolean`, `overrideSource`, `schema: Record<string, unknown>`, `form: FormView`, `createSeed?: {} | null`, and `actions?: Action[] | NonNullable<MetadataTypeRegistryEntryParsed['actions']>`. The second `actions` arm is in main's type because the row spreads the registry entry before it overrides `actions`; leaving it out fails the pin. A mapped `Flatten` turns the intersection into one object type, which the strict `Equal` needs to compare equal to an inferred object literal. Nothing new is exported from the package index. - `packages/metadata-protocol/src/protocol.ts`: `getMetaTypes()` declares `Promise<MetaTypesListing>`. The body is unchanged up to its last line, which now builds `const listing = { types: allTypes, entries }`, holds `const exact: Equal<typeof listing, MetaTypesListing> = true`, and returns `listing`. One type-only import. 11 lines, +9/-2. - `.changeset/29510-meta-types-named-return.md`: `@objectstack/metadata-protocol` patch, both declaration lines. ## Why The #25467 E1 seat ruling (PR #29488) kept `getMetaTypes()` inferred so E1's `index.d.ts` stayed byte-identical, and moved the explicit return type to its own step, option B of the E1 report: a named composed type with a type-equality pin. Triage audit 6592554479 kept it p3, `domain:server`. ### What retires the per-cut raw-diff reading of `getMetaTypes()` The `exact` line. `typeof listing` is the type the body infers, which is the type `main` emitted. If a cut or any later edit changes what the body builds, or changes the declared name, `tsc` fails at that line in `typecheck` and in the tsup declaration build. The `.d.ts` now prints `getMetaTypes(): Promise<MetaTypesListing>` and an alias, so there is no 793-line inline block left for a cut to read, and no inferred block a stray class comment can surface inside. What this does not retire: ruling 6348891160's whole-`index.d.ts` reading still applies to each cut, because other public members of the class stay inferred (`getDiscovery`, `getMetaItems`, `getMetaItem`, `findData`, … as listed in 6385903828). The module comment above the `protocol-meta-type-schema.js` import in `protocol.ts` ("read its raw diff after any edit here") is still true for them, so it is left as it is. ## Tests Measured on `main` 1c1a5d4 before the edit: the dependency closure built under the lock (`pnpm --filter '@objectstack/metadata-protocol...' build`, VERDICT command-exit 0). `dist/index.d.ts` lines 3057–3849 hold `getMetaTypes()`: 793 lines, sha256 `b0f7f61a…c85bf`, starting `getMetaTypes(): Promise<{` and ending `}>;`. No comment sits inside that block on this tree. <details><summary>Type equality against main's emitted type (one-time proof, not committed)</summary> A scratch probe beside the package imported `ObjectStackProtocolImplementation` from a copy of main's `dist/index.d.ts` and from this branch's rebuilt `dist/index.d.ts`, and compiled `Equal<Before, After>` and `Equal<Before['entries'][number], After['entries'][number]>` with `true`: `tsc` exit 0. Negative control, same probe plus `Equal<Before['entries'][number], Omit<After['entries'][number], 'schemaId'>> = true`: exit 2, `TS2322: Type 'true' is not assignable to type 'false'`. The probe was deleted afterwards. The `.d.ts` text diff, main vs this branch: the 793-line block becomes `getMetaTypes(): Promise<MetaTypesListing>;`, 39 lines of alias declarations are added (not exported), and two import lines change (`FormFieldInput` was only used inside the old inline block; `FormView`, `Action` and `MetadataTypeRegistryEntryParsed` are now imported). Nothing else in the file moves. </details> <details><summary>Ablation: the pin fails on a member drift</summary> Committed first (6525242), then `node scripts/ablation-replace.mjs --file …/protocol-meta-types-listing.ts --anchor "schemaId: string;" --replacement "schemaId?: string;" -- pnpm --filter @objectstack/metadata-protocol typecheck`, with an `EXIT INT TERM` trap restoring from `HEAD`: - mutation landed: anchor 1 → 0, replacement 0 → 1, blob `81483bc18bca` → `b5392c1a893c`; - `tsc --noEmit`: one error, `src/protocol.ts(3297,15): error TS2322: Type 'true' is not assignable to type 'false'` (the `exact` line), exit 2; - restored: blob == HEAD (`81483bc18bca`), `git diff HEAD` empty. Making a member optional is assignable to the declared type, so `return` alone would not catch it. Only the pin did. </details> <details><summary>Gates on 94b9d02 (final head, after merging main c9636f1)</summary> - Builds under the lock: `pnpm turbo run build --concurrency=2 --filter=@objectstack/metadata-protocol... --filter=@objectstack/objectql` (VERDICT command-exit 0). - `pnpm --filter @objectstack/metadata-protocol test` under the lock: Test Files 308 passed, 4 skipped (312); Tests 22264 passed, 26 skipped (22290); VERDICT command-exit 0. (On 6525242, before the merge: 22262 passed, VERDICT 0.) - `pnpm --filter @objectstack/metadata-protocol typecheck`: exit 0 (the pin holds on the merged tree). - `pnpm lint`: exit 0. - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack`: 54 families (3 paths vs merge base, +87/-2), the same list before and after the merge. Each run once, exit captured before any pipe: 53 exit 0. - `pnpm check:dual-build-cjs-loads`: exit 3, PREREQUISITE NOT MET (about 70 workspace packages unbuilt in this container). NOT MEASURED locally; CI runs it on a full build. - `dispatch-gates --ran`: 54 derived, 53 run, 1 NOT-MEASURED (dual-build, from its recorded exit 3), 0 UNRUN. - Prerequisites met on the first round: `check-plugin-teardown-shape --self-test` needed its pinned fixture commit fetched (shallow clone), `check:lean-entry-closure` needed objectql built; both then exit 0. </details> ## Acceptance notes - The `.d.ts` text changes and the type does not; that is the card's stated bar, measured above. - `MetaTypesListing` and `MetaTypesListingEntry` are not exported from `@objectstack/metadata-protocol`, so no new public name. ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (not touched) - [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. (not touched) - [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 维护者速读 section is the repo's required Chinese brief) - [x] The *Before Submitting* list in CONTRIBUTING.md is done. domain:server#3 · os-warren · session_01JQwxbWaMuBU5CquKAT7ZmH 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01JQwxbWaMuBU5CquKAT7ZmH --- _Generated by [Claude Code](https://claude.ai/code/session_01JQwxbWaMuBU5CquKAT7ZmH)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 51a12c0 commit 545c1c7

3 files changed

Lines changed: 87 additions & 2 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/metadata-protocol': patch
3+
---
4+
5+
refactor(metadata-protocol): `getMetaTypes()` declares a named return type, held equal to the type it returned before
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
No behaviour change and no type change. `ObjectStackProtocolImplementation.getMetaTypes()` now declares `Promise<MetaTypesListing>`, composed from `@objectstack/spec`'s `MetadataTypeRegistryEntryParsed`, `Action` and `FormView`, in place of an inferred type that the published `index.d.ts` printed inline over 793 lines. A compile-time equality check in the method holds the name equal to what the body builds, so the two cannot drift. The `.d.ts` text is shorter; the type a consumer reads is the same one, checked equal against the declaration file `main` built before this change. `MetaTypesListing` is not exported from the package. Nothing to migrate.
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
// [#29510] The NAMED return type of `ObjectStackProtocolImplementation.getMetaTypes()`
4+
// (`GET /meta/types`), composed from types `@objectstack/spec` already exports.
5+
//
6+
// Why a name: inferred, that return type rolled up into ~790 lines of inline
7+
// `.d.ts`, and every `protocol.ts` cut of #25467 had to read that raw block by
8+
// hand, because a byte shift in `protocol.ts` can surface a class comment
9+
// inside an inferred type. Named, the `.d.ts` prints these aliases instead.
10+
//
11+
// What holds it to the implementation: `getMetaTypes()` builds its answer with
12+
// an inferred type, and a `const` typed `Equal<inferred, MetaTypesListing>`
13+
// is initialised with `true` there: it only compiles when the inferred type is
14+
// EQUAL (not merely assignable) to the one declared here. A member added,
15+
// dropped or retyped on either side fails `tsc` at that line. The type is the
16+
// one `main` emitted before the name existed; only its `.d.ts` spelling changed.
17+
//
18+
// Not exported from the package index: no new public name.
19+
20+
import type { MetadataTypeRegistryEntryParsed } from '@objectstack/spec/kernel';
21+
import type { Action, FormView } from '@objectstack/spec/ui';
22+
23+
/** Flattens an intersection into one object type, so it compares EQUAL to an inferred object literal. */
24+
type Flatten<T> = { [K in keyof T]: T[K] };
25+
26+
/**
27+
* One `entries` row: the registry entry for the type, with the per-type
28+
* fields the listing adds or overrides. A type with no registry entry gets a
29+
* synthesised descriptor that is a subtype of this row.
30+
*/
31+
export type MetaTypesListingEntry = Flatten<
32+
Omit<MetadataTypeRegistryEntryParsed, 'type' | 'allowEnvironmentOverlay' | 'actions'> & {
33+
/** Singular spelling, as `PLURAL_TO_SINGULAR` resolves it; plugin types are not in the registry enum. */
34+
type: string;
35+
/** Same value as `type`; the API client reads this field. */
36+
schemaId: string;
37+
/** The registry value, raised by the `OS_METADATA_WRITABLE` env hatch. */
38+
allowEnvironmentOverlay: boolean;
39+
/** `'env'` when only the env hatch opened the overlay. */
40+
overrideSource: 'registry' | 'env';
41+
/** JSON Schema of the type, for the generic admin form. */
42+
schema: Record<string, unknown>;
43+
/** Form layout of the type's editor. */
44+
form: FormView;
45+
/** The minimal create seed, when the spec declares one. */
46+
createSeed?: {} | null;
47+
/**
48+
* Declarative plus plugin-registered type actions (`Action[]`); absent
49+
* when there are none. The registry entry's own parsed `actions` stay
50+
* in the type because the row spreads the entry before overriding.
51+
*/
52+
actions?: Action[] | NonNullable<MetadataTypeRegistryEntryParsed['actions']>;
53+
}
54+
>;
55+
56+
/** What `getMetaTypes()` answers. */
57+
export type MetaTypesListing = {
58+
/** Every live type name, spelled as its source stores it. */
59+
types: string[];
60+
/** One row per live type, sorted by `domain`, then `type`. */
61+
entries: MetaTypesListingEntry[];
62+
};
63+
64+
/**
65+
* Strict type equality: no `any` leak, no one-sided assignability. `true`
66+
* only when `A` and `B` are the same type.
67+
*/
68+
export type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,8 @@ import { datasourceCredentialsRefSaveRefusal } from './protocol-datasource-crede
466466
import { withRefusalAudit } from './protocol-refusal-audit.js';
467467
// [#28665] The null-master rows a `controlled_by_parent` detail stops serving, counted into the finding that makes its master required.
468468
import { withNullMasterRowCounts } from './protocol-destructive-null-master.js';
469+
// [#29510] `getMetaTypes()`'s named return type and the equality its pin reads.
470+
import type { Equal, MetaTypesListing } from './protocol-meta-types-listing.js';
469471
// [#25467 E0] The module preamble that stood here moved, verbatim, into the themed
470472
// `protocol-*.ts` modules below. What this file exported from it, it still exports;
471473
// the module order below is the order the rolled-up `.d.ts` keeps their declarations in.
@@ -3139,7 +3141,8 @@ export class ObjectStackProtocolImplementation implements
31393141
return listLiveMetadataTypes.call(host);
31403142
}
31413143

3142-
async getMetaTypes() {
3144+
// [#29510] Named return type; the `exact` pin below holds it EQUAL to what this body infers.
3145+
async getMetaTypes(): Promise<MetaTypesListing> {
31433146
const allTypes = await this.listLiveMetadataTypes();
31443147

31453148
// Phase 3a-1: enrich response with per-type registry metadata so admin
@@ -3292,7 +3295,11 @@ export class ObjectStackProtocolImplementation implements
32923295
return a.type.localeCompare(b.type);
32933296
});
32943297

3295-
return { types: allTypes, entries };
3298+
const listing = { types: allTypes, entries };
3299+
// [#29510] Compile-time pin: `false` (a type error) the moment the body and the name drift apart.
3300+
const exact: Equal<typeof listing, MetaTypesListing> = true;
3301+
void exact;
3302+
return listing;
32963303
}
32973304

32983305
/**

0 commit comments

Comments
 (0)