Repository navigation
Commit 545c1c7
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
- .changeset
- packages/metadata-protocol/src
| 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 | + | |
| 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 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
466 | 466 | | |
467 | 467 | | |
468 | 468 | | |
| 469 | + | |
| 470 | + | |
469 | 471 | | |
470 | 472 | | |
471 | 473 | | |
| |||
3139 | 3141 | | |
3140 | 3142 | | |
3141 | 3143 | | |
3142 | | - | |
| 3144 | + | |
| 3145 | + | |
3143 | 3146 | | |
3144 | 3147 | | |
3145 | 3148 | | |
| |||
3292 | 3295 | | |
3293 | 3296 | | |
3294 | 3297 | | |
3295 | | - | |
| 3298 | + | |
| 3299 | + | |
| 3300 | + | |
| 3301 | + | |
| 3302 | + | |
3296 | 3303 | | |
3297 | 3304 | | |
3298 | 3305 | | |
| |||
0 commit comments