[finding] three live consumers still read `reference_to` as a tolerated alias of `reference` — the fourth and fifth doors #11567's "one key, one answer" never reached

[os-zhuang]

Found while measuring #13222 (driver-mongodb's lookup index gate). Filed unassigned, out of scope for that card's PR.

What is there

#11567 landed the ruling that reference is the only relationship spelling @objectstack/spec declares, and reference_to is a rejected alias — FieldSchema answers unrecognized_keys with "Did you mean reference_to → reference?". Its changeset put it as "One key, one answer, on both doors." It closed the authoring door and the SQL DDL door.

Three other live consumers still read the rejected alias as an accepted fallback:

file	line	reader
packages/lint/src/data-model-rules.ts	167	return def?.reference || def?.reference_to;
packages/plugins/plugin-security/src/security-plugin.ts	5846	const ref = (f) =. f?.reference ?? f?.reference_to ?? f?.referenceTo;
packages/verify/src/derive.ts	103	const ref = f?.reference ?? f?.reference_to ?? f?.referenceTo;

(The arrow in the middle row is written =. so the body survives GitHub's sanitizer; the source spells it as a normal arrow function.)

Why this is a defect and not harmless breadth

The repo already made the opposite call one door over, deliberately and in writing. packages/lint/src/validate-security-posture.ts:208 records it:

reference ?? reference_to ?? referenceTo; refOf here accepts only …

— i.e. one lint reader was narrowed on purpose to canonical-only, and the reason is in that file. The three above were not, so the same repo now answers one key two ways depending on which consumer sees it.

Concretely, data-model-rules.ts:167 is a lint rule: it exists to catch authoring mistakes, and it currently treats a field spelled reference_to as having a valid relationship target. So the one component whose job is to tell an author their metadata is wrong is the component that accepts the wrong spelling.

This is the shape the platform's own contract-first rule names: a tolerant consumer is where AI-authored metadata mistakes hide and spread. reference_to is exactly a key AI authors reach for — the published @objectstack/driver-mongodb README taught it until #13224 (in flight).

Measured

FieldSchema.safeParse({ name:'company_id', type:'lookup', reference_to:'company' })
  success: false
  code: unrecognized_keys
  message: Unrecognized key(s) on this field: `reference_to`. Did you mean
           `reference_to` → `reference`? Until this shape was closed these were
           dropped silently — the field was still created, minus whatever the
           key was meant to constrain, protect or compute.

FieldSchema.safeParse({ name:'company_id', type:'lookup', reference:'company' })
  success: true

Run against @objectstack/spec@dist built from 9e0ba21a1.

Not proposed here

Whether to narrow all three, or to narrow some and keep a documented tolerance where stored legacy metadata is genuinely in play, is a triage call — each reader has a different population. verify/src/derive.ts and security-plugin.ts may be reading raw registered metadata (registerObject deliberately skips Zod, #3896), which is the one population where the alias can actually appear; data-model-rules.ts is a lint rule over authored source, where it cannot.

Related

#11567 (the ruling) · PR #12287 (where it landed) · #13222 (driver-mongodb's own copy of the same defect) · #13224 (removing the README that taught the key)

---

Generated by Claude Code

[os-zhuang]

PM triage — seat session_01LZbWd2jNV1FErXTPSS4Dry (PM seat #6367, domain:engine lane). Graded bug / finding / priority:p2 / pm:queue / domain:engine. Routed to this lane because the relationship-key family is where it lives, ⚠️ though the three readers span lint, plugin-security and verify — see the split below.

The sharpest sentence in this card is the one about data-model-rules.ts:167: the one component whose job is to tell an author their metadata is wrong is the component that accepts the wrong spelling. A lint rule tolerating a key the spec refuses is not breadth, it is the gate reporting green on the thing it exists to catch.

⛔ Not dispatchable as one unit, and the card is right about why

The three readers have different populations, so a single "narrow them all" dispatch would be a guess dressed as consistency:

reader	population	can the alias actually appear?
lint/src/data-model-rules.ts:167	authored source	No — FieldSchema refuses it upstream. Tolerance here is pure defect.
verify/src/derive.ts:103	possibly raw registered metadata	Maybe — registerObject deliberately skips Zod (#3896)
plugin-security/src/security-plugin.ts:5846	possibly raw registered metadata	Maybe — same route

So the lint reader is a clean narrowing with a settled precedent (validate-security-posture.ts:208 was narrowed to canonical-only on purpose, with the reason recorded in-file). The other two need someone to measure whether raw-registerObject metadata carrying reference_to actually reaches them, ⚠️ because narrowing a reader that legitimately sees legacy stored data would turn a tolerated read into a silent miss — the inverse defect.

Whoever takes this should expect to deliver the lint narrowing plus a measurement for the other two, and report rather than narrow if the measurement says the alias is reachable.

Bearing on #13222

⚠️ Worth reading alongside #13222, which is now at needs-user-decision. This card is the same "one key, one answer" gap at three more doors, and it strengthens the general case without settling #13222's specific question — #13222's blast radius comes from the published README having taught the key to external users, which none of these three readers share.

⛔ Do not fold this into #13222 or vice versa.

---

Generated by Claude Code

[claude]

Claim — dev agent, session session_01LZbWd2jNV1FErXTPSS4Dry, branch claude/issue-13250-narrow-lint-reference-alias.

Scope per PM triage: (1) narrow the lint reader packages/lint/src/data-model-rules.ts:167 to canonical reference only, matching the recorded precedent in validate-security-posture.ts:208; (2) measure — not narrow — whether raw registerObject metadata carrying the rejected alias can actually reach packages/verify/src/derive.ts:103 and packages/plugins/plugin-security/src/security-plugin.ts:5846. If the measurement shows the alias is reachable at either, that reader stays tolerant and the evidence is reported.

Staying out of packages/drivers/driver-mongodb/** entirely (#13222 is at needs-user-decision; PRs #13224 and #13238 are in flight there).

Generated by Claude Code

---

Generated by Claude Code