objectstack-ai · os-musk · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/.changeset/master-detail-reference-alias-measured.md b/.changeset/master-detail-reference-alias-measured.md
@@ -0,0 +1,63 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): the fourth tolerant alias reader — `master-detail.ts`'s `referenceTo` tolerance recorded with its measurement, and loud where the alias answered (#13543)
+
+`resolveMasterDetailRelation` accepts the REJECTED alias `referenceTo` beside
+the canonical `reference`, and the type beside it stated a population for that
+tolerance in one line: *"`referenceTo` is the stored-row spelling."* Nothing in
+the tree measured it. This is that measurement, and the tolerance's disposition
+after it — the same shape #13541 gave the sibling `controlled_by_parent` reader
+in `plugin-security`, arrived at by the same route.
+
+**The census (whole tree, both spellings counted separately, positive controls
+run so no zero comes from a pathspec that matches nothing).** Authored object
+declarations: **zero**, both spellings — all 8 `Field.masterDetail(...)` and 132
+`Field.lookup(...)` declarations across `*.object.ts`, `examples/`,
+`packages/qa/` and the `create-objectstack` templates go through the
+`@objectstack/spec` builders, which emit the canonical key. Stored-metadata
+seeds, JSON/YAML fixtures and `metadata-fs` layouts: **zero**, both spellings.
+The nine in-tree files that put `referenceTo` on a field def are all reader
+pins. Metadata at rest in a live deployment is **NOT MEASURED** — no command in
+this repository reaches it, so the zeros are zeros for the tree, not the world.
+
+**The assertion was wrong, and the correction is the point.** ADR-0087's
+`fieldReferenceToAlias` records, in its own docblock, that camelCase
+`referenceTo` is deliberately not converted because it "is not the spelling the
+objectql runtime wrote into stored object rows" — the stored dialect is
+`reference_to`, which this reader does not read. So the line justifying the
+tolerance named the wrong spelling, and the docblock now carries the measured
+account instead of the assertion.
+
+**The tolerance still stays, for a reason that survived the census.** A raw
+`registerObject` skips Zod by design and every caller of this resolver reads
+that same `SchemaRegistry`, so an alias-spelled object reaches here verbatim —
+now pinned by a test that registers one and resolves it. And the conversion
+layer normalises `reference_to` on stored rehydration and `os migrate meta`
+while deliberately leaving `referenceTo` alone, which makes `referenceTo` the
+one spelling that is simultaneously unconverted upstream and read here. Two of
+this resolver's four callers fail **closed**: an unresolved relation leaves
+`parent` unbound and `rule-validator.ts` reads an unbound scope root as LOCKED,
+so narrowing would take a raw-registered, alias-spelled detail object from
+"lock enforced against its header" to "every `parent`-scoped field permanently
+unwritable, writes silently stripped". That is an availability defect, not a
+spelling correction.
+
+**Loud where the alias is what answered.** When the relation resolves from
+`referenceTo`, the resolver reports once per object+field+spelling through an
+optional `warn` sink defaulting to `console.warn` — the same caller-supplied
+callback shape and default as `warnFunctionalCompleteness` in the same package.
+Never a throw, no behaviour change: `referenceKeyOf` selects the key with the
+same `!= null` test `??` applies, so a present-but-empty `reference` still wins
+the read rather than falling through to the alias. The report is once per
+distinct defect rather than per write, because this resolver sits on the write
+path and a per-write line is a noise defect of its own. The text also corrects
+the registration-time `field/relationship-without-reference` diagnostic, which
+calls the same field "runtime-DEAD ... never-resolves" — false for this
+consumer, and two diagnostics disagreeing about one field is worse than one.
+
+⛔ Narrowing this reader is not done here and is not licensed by the zeros
+above: it is only honest behind a migration that sweeps stored and
+raw-registered metadata first. The live-deployment census neither this card nor
+its sibling could run is still the open prerequisite.
diff --git a/packages/objectql/src/master-detail-reference-alias.test.ts b/packages/objectql/src/master-detail-reference-alias.test.ts
@@ -0,0 +1,180 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The reference-spelling contract of `resolveMasterDetailRelation` — three
+ * spellings, three different answers, pinned so none of them can drift
+ * silently.
+ *
+ * The module accepts the canonical `reference` and the REJECTED alias
+ * `referenceTo`, and reads the OTHER rejected alias `reference_to` not at all.
+ * That asymmetry is deliberate and is the thing most likely to be "tidied" by
+ * someone who notices only that a sibling reader (`resolveCbpRelation` in
+ * `plugin-security`) accepts all three: the ADR-0087 conversion layer already
+ * normalises `reference_to` on stored rehydration and on `os migrate meta`,
+ * and deliberately does not normalise `referenceTo`. So the one spelling that
+ * can arrive here unconverted is exactly the one this reader accepts. Pinning
+ * the asymmetry as a RECORD is the point — a test that only checked the happy
+ * path would let either half move without a failure.
+ *
+ * The loud half is pinned the same way `plugin-security`'s is: the report must
+ * name the key that ACTUALLY answered, so the diagnostic and the resolution
+ * can never disagree about which spelling was read.
+ *
+ * Imported relatively (`./master-detail.js`), i.e. from source through vitest's
+ * own resolution — no `dist/` leg, so an ablation of the loud line shows up
+ * here without a rebuild.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveMasterDetailRelation } from './master-detail.js';
+import { SchemaRegistry } from './registry.js';
+
+/** An object shape with one `master_detail` field spelled however the case needs. */
+function detailObject(name: string, key: string, master = 'crm_account') {
+ return {
+ name,
+ label: name,
+ fields: {
+ id: { name: 'id', label: 'ID', type: 'text' as const, primaryKey: true },
+ account_id: { type: 'master_detail', label: 'Account', [key]: master },
+ },
+ } as never;
+}
+
+describe('resolveMasterDetailRelation — the reference spelling it reads, and what it says about it', () => {
+ it('canonical `reference` resolves, and says NOTHING — the quiet path stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('canon_detail', 'reference'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('`referenceTo` resolves TOO — the tolerance is real, not a leftover type key', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('alias_detail', 'referenceTo'), { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ });
+
+ it('...and it is LOUD when it does: the report names the spelling that answered', () => {
+ const warn = vi.fn();
+ resolveMasterDetailRelation(detailObject('loud_detail', 'referenceTo'), { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ const msg = String(warn.mock.calls[0]?.[0]);
+ // The key that answered, the field it sat on, and the object — the
+ // three facts an author needs to find and rename it.
+ expect(msg).toContain('`referenceTo`');
+ expect(msg).toContain('"loud_detail"');
+ expect(msg).toContain('"account_id"');
+ // ...and the half an operator needs so they do not go hunting an
+ // outage that did not happen.
+ expect(msg).toContain('UNAFFECTED');
+ });
+
+ it('⛔ snake_case `reference_to` is NOT read here — the asymmetry with plugin-security is a record, not an oversight', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation(detailObject('snake_detail', 'reference_to'), { warn });
+
+ // No relation at all: this reader never had a `reference_to` arm, and
+ // the conversion layer is what serves that spelling (to `reference`)
+ // before a stored row ever reaches here.
+ expect(rel).toBeNull();
+ // ...and nothing is reported, because nothing resolved from an alias.
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('an un-injected host still hears it — the default sink is `console.warn`', () => {
+ const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ resolveMasterDetailRelation(detailObject('default_sink_detail', 'referenceTo'));
+ expect(spy).toHaveBeenCalledTimes(1);
+ expect(String(spy.mock.calls[0]?.[0])).toContain('[objectql/reference-spelling]');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('reports ONCE per object+field+spelling — the write path must not become a noise channel', () => {
+ const warn = vi.fn();
+ const schema = detailObject('repeat_detail', 'referenceTo');
+ for (let i = 0; i < 5; i++) resolveMasterDetailRelation(schema, { warn });
+
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('canonical WINS over the alias when both are present, and stays quiet', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'both_detail',
+ fields: {
+ account_id: {
+ type: 'master_detail',
+ reference: 'crm_account',
+ referenceTo: 'crm_stale_legacy',
+ },
+ },
+ } as never, { warn });
+
+ expect(rel).toEqual({ fk: 'account_id', master: 'crm_account' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('a present-but-EMPTY `reference` does not fall through to the alias — the `??` semantics are unchanged', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'empty_canon_detail',
+ fields: {
+ account_id: { type: 'master_detail', reference: ' ', referenceTo: 'crm_account' },
+ },
+ } as never, { warn });
+
+ // `a ?? b` falls through on null/undefined ONLY, so the empty canonical
+ // key still wins the read and still yields no usable name.
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('two masters stay ambiguous, and report nothing — a relation that did not resolve has no spelling to name', () => {
+ const warn = vi.fn();
+ const rel = resolveMasterDetailRelation({
+ name: 'junction_detail',
+ fields: {
+ left_id: { type: 'master_detail', referenceTo: 'crm_account' },
+ right_id: { type: 'master_detail', referenceTo: 'crm_contact' },
+ },
+ } as never, { warn });
+
+ expect(rel).toBeNull();
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
+describe('the path that makes the tolerance reachable at all', () => {
+ it('a raw `registerObject` carries `referenceTo` verbatim into the registry, and this reader then resolves it', () => {
+ // The reachability claim the module doc records, measured rather than
+ // asserted: `registerObject` skips Zod by design, so the rejected alias
+ // survives registration, and every caller of this resolver reads the
+ // schema back out of this same registry.
+ const registry = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ try {
+ registry.registerObject(detailObject('raw_registered_detail', 'referenceTo'));
+ } finally {
+ consoleWarn.mockRestore();
+ }
+
+ const served = registry.getObject('raw_registered_detail') as
+ { fields?: Record<string, Record<string, unknown>> } | undefined;
+ expect(served?.fields?.account_id?.referenceTo).toBe('crm_account');
+ expect(served?.fields?.account_id?.reference).toBeUndefined();
+
+ const warn = vi.fn();
+ expect(resolveMasterDetailRelation(served as never, { warn })).toEqual({
+ fk: 'account_id',
+ master: 'crm_account',
+ });
+ expect(warn).toHaveBeenCalledTimes(1);
+ });
+});