test(metadata-protocol): pin the THIRD union-branch policy copy against @objectstack/spec (#8660)

[hotlong]

Fixes#8660

The union-branch selection policy has three implementations. #8318 (PR #8659) consolidated the two inside packages/spec and pinned them against each other. The third — zodIssuesToMetadataIssues in packages/metadata-protocol/src/protocol.ts, whose own header calls itself "the THIRD copy" — was structurally out of that consolidation's reach, because the shared module is deliberately not a public export (#4001). This adds the mechanical parity enforcement it was missing.

Option 1 exactly as ruled: one new test file plus a changeset. No production line changes, no new export, and protocol.ts is not touched.

What it does

packages/metadata-protocol/src/union-branch-policy.cross-package-parity.test.ts drives both sides through their public surfaces over one shared fixture corpus:

side	surface	reached via
spec, prose walk	formatZodIssue	@objectstack/spec (root barrel)
spec, wire walk	zodIssuesToFields	@objectstack/spec/api
this package	zodIssuesToMetadataIssues	the walk behind saveMetaItem's 422 (#5364) and the read path's diagnostics (#5598)

One safeParse per fixture feeds all three, and their outputs are compared as ordered (path, message) pairs after a normalisation that removes exactly three formatting facts — the renderer's indent, its glyph, and its (root) spelling of the empty path — and nothing else.

The two halves are genuinely independent, and §1 proves it structurally

A parity test whose halves share a code path proves nothing. §1 asserts that not one of the seven policy symbols is reachable from any public entry point of @objectstack/spec (root, /api, /shared), so protocol.ts cannot be importing the shared module even if a future author wanted it to — its own copy is the only thing it can run. Measured on the built artifact: all three entry points export none of them.

§1 is also the tripwire for the other outcome. If the policy is ever promoted to a public export — the option this card ruled out of scope — §1 goes red and says the next move is to rewire this package onto the shared module, not to leave a third copy behind a green parity test.

A companion case asserts all three imports are really functions, so the comparison cannot be green because both walks emitted nothing.

The corpus

One fixture per element of the policy the card names, each carrying a hand-authored expectedPaths — a third statement of the rule, so both sides drifting the same way still fails, and so each fixture's name is checkable rather than decorative:

rule	how the fixture forces it
kind-mismatch drop	the string member of a mixed union complains only about the kind
all branches kind-mismatch	z.union([z.string(), z.number()]) handed an object: nothing selected
fewest issues wins	branches producing 1 vs 3 issues, neither carrying unknown keys
unrecognized_keys tie-break	both branches produce exactly 2 issues, only one carries the unknown key — verified, so the tie-break is what decides rather than the count
declaration order	three branches, 1 issue each, no unknown keys: a full tie, all emitted
branch cap 3	five tied branches, three kept
depth limit 3	four nested unions; the descent stops before the leaf that is actually wrong
relative path resolution	a union one level down, paths resolved against the union above it

§3 guards against vacuity: every fixture must really produce an invalid_union, six must reach below the top-level issue, and every named policy element must appear in some fixture's rule string.

Reverse verification — the test fails when the copies diverge

Predictions stated before each run; both ablations were made on the spec side, which is the direction the card describes (a spec-side tweak reaching two consumers and silently not the third). metadata-protocol resolves @objectstack/spec through exports to dist/, so each ablation was rebuilt and proved present in the artifact with scripts/ablation-dist-preflight.mjs before the run was allowed to mean anything.

A — invert the unrecognized_keys tie-break. Predicted: exactly one fixture reddens, the tie-break one; the others are decided by count, by there being one informative branch, or by a uniform rank. Measured: 1 failed, 16 passed, and the one failure is the predicted case, with the spec side selecting the loose branch and this package the strict one.

B — cap at 2 instead of 3. Predicted: the two fixtures that select three branches, plus §4's omission-line assertion (its count moves from 2 to 3). Measured: 3 failed, 14 passed, exactly those three.

Restored both times with git checkout HEAD -- packages/spec/src/shared/union-branch-policy.ts, proven byte-identical (git hash-object = 53fc1a1164 = the HEAD blob), rebuilt, and the marker proven absent from all 181 built files with --absent before re-running green.

What is deliberately NOT compared, and why

• Container descent (invalid_key / invalid_element, 休眠:invalid_key / invalid_element 把真实 issue 挂在 issue.issues 上,union 家族的三个消费者一个都不下降 #5389). The spec walks descend those; this package's copy expands invalid_union only. That is a difference in reach, not in the ranking, and it is not what union 分支里的 unknown-key 处方永远到不了作者:zodIssuesToFields 只映射顶层 issue,失败的 union 只剩 Invalid input #5014 bound together — so the corpus stays where all three make the same claim. Measured and filed separately as metadata-protocol's 422 issues[] does not descend invalid_key / invalid_element containers, so a record-key rejection arrives as the bare "Invalid key in record" while the CLI and the wire both show the prescription #8783; it is not addressed here.
• The code vocabulary. Raw zod codes here, the ADR-0114 catalog on the wire (元数据保存的 422 也丢掉 union 分支处方:一个 view 保存失败只回一条 path:"" message:"Invalid input"，Studio 无字段可高亮 #5364 records why they are not aligned). §4 asserts the divergence in place rather than normalising it away, so it stays a decision instead of decaying into an accident.
• The prose renderer's trailing omission line. §4 pins it present on the prose side and absent from both machine-readable walks, in both directions.

The dist caveat, stated in the file itself

@objectstack/metadata-protocol is one of the 61 packages registered as still resolving a workspace dep through dist/ in scripts/check-test-source-alias.mjs, so the spec half of every assertion is the built artifact. That is the honest reading for a cross-package pin — it is what this consumer links against, and turbo.json has test dependsOn ^build — but it means perturbing packages/spec/src alone will not redden this file. The module header says so explicitly, so the next person to attempt an ablation does not lose the lap.

Changeset

patch, deliberately not a skipped changeset, on the same reasoning as legacy-unique-guard-attribution (merged earlier today for a test-only PR): the 422 envelope this pins is a published contract of @objectstack/metadata-protocol, and a CHANGELOG reader should be able to see when its verdict acquired mechanical protection against drifting from the spec's. No production line changes and every assertion is green on main before this lands, so the floor is right rather than absent.

Verification

All at d8f950e3e, the first round's head; the gate union was run after that round's final commit, on the fully rebuilt workspace. The patch round below re-ran everything at the current head — read that table for the state of this PR as it stands.

@objectstack/metadata-protocol suite	91 files / 1368 tests passed
the new file alone	17 tests passed
derived gate union (scripts/pm/dispatch-gates.mjs against the real changed paths)	check:nul-bytes, check:cross-package-test-inputs, check:durability-log-level, check:objectui-changeset, check:changeset-gate-self-tests, check:empty-changeset, check:query-options-erasure, check:type-check-coverage, check-adr-0087-registration, check-changeset-no-major — all green
check:test-source-alias (added by me, not in the derived list: this diff adds cross-package imports to a test)	green, 72 packages scanned, registry unchanged
check:type-check-debt (the ratchet half, --re-measure on the built workspace)	green — 33 entries re-measured, none above its recorded number

On the type-check question specifically:packages/metadata-protocol/tsconfig.json does not exclude **/*.test.ts — its include is src/**/*, so the new file is inside the program. What the package lacks is a typecheck script at all: it sits in the DEBT ledger at 63 frozen raw errors, and check:type-check-debt --re-measure is what actually runs tsc over it. Re-measured with this file present: exactly 63, zero of them naming it, and no surplus recorded against this package — so the file type-checks clean rather than hiding inside an allowance.

Synced with origin/main at 84cb121eb (clean merge; the merge brought new packages/spec commits, so the closure was rebuilt before the final test run rather than reporting on the pre-merge artifact).

Patch round — §1 kept its claim, the restricted import went

The first push tripped the repo's no-restricted-imports rule: §1 read the root barrel as import * as SpecRoot from '@objectstack/spec', and a static namespace binding on the root keeps all fifteen domain namespaces reachable — the ~1.2GB RSS regression that rule exists to prevent. eslint . --no-inline-config means there is no per-site opt-out, by design.

§1 was not weakened. It still asserts that none of the seven policy symbols is reachable from any public entry point, root included. What changed is how the export surface is read: the three entry points are now loaded through await import(...) inside the case, and a helper reduces each namespace to the handful of names §1 asks about and lets the object go. Verified against the real linter rather than assumed — the rule's paths/importNames form does not match an ImportExpression, and the dynamic spelling lints clean.

That is not an evasion dressed up as a fix. The file already loads the root module for formatZodIssue, so nothing extra is pulled in; what the dynamic form drops is precisely the long-lived namespace binding the rule targets, which makes the new spelling strictly less retentive than the one it replaces while making the identical claim about the identical surface.

Proof that §1 can still fail (prediction first, as before): adding export { selectUnionBranches } from './union-branch-policy'; to packages/spec/src/shared/index.ts should make the symbol reachable from @objectstack/spec/sharedonly — the root barrel does not re-export that barrel — so exactly one of §1's three cases should redden.

Measured, after rebuilding @objectstack/spec and confirming reachability on the built artifact directly ('selectUnionBranches' in mod: root false, /apifalse, /sharedtrue):

• 1 failed, 16 passed — the /shared case, failing with expected [ 'selectUnionBranches' ] to deeply equal []. Direction as predicted.
• Restored with git checkout HEAD -- packages/spec/src/shared/index.ts, proven byte-identical (git hash-object = f400f4b514 = the HEAD blob), rebuilt, and reachability re-probed as false before re-running green.

Note on the ablation marker: grepping dist for selectUnionBranches proves nothing here — the symbol is bundled as an internal either way. Reachability had to be probed through the module namespace, which is the thing §1 actually asserts.

Verification (patch round)

All at b4706c135, the head this pushes; every gate below was re-run after the final commit, ratchets included.

pnpm lint (eslint . --no-inline-config, repo-wide)	zero problems
@objectstack/metadata-protocol suite	91 files / 1368 tests passed
the new file alone	17 tests passed
check:type-check-debt (ratchet, --re-measure)	green — 33 entries, none above its recorded number
tsc --noEmit over the package	exactly 63, the ledger ceiling; zero naming this file
check:nul-bytes, check:cross-package-test-inputs, check:test-source-alias, check:query-options-erasure, check:type-check-coverage, check:empty-changeset	all green

origin/main re-checked at push time: still 84cb121eb, already merged — the merge is current, not stale.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 15, 2026 1:49am

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅