@@ -701,7 +701,9 @@ export function resolveTenancyPostureOrFinding(reading: DotenvReading): TenancyP
 
 // ─── Config-Aware Checks ────────────────────────────────────────────
 
-function detectCircularDependencies(objects: any[]): string[] {
+// Exported for the pin on its carrier reading below; `doctor` itself is the
+// only caller.
+export function detectCircularDependencies(objects: any[]): string[] {
   const issues: string[] = [];
   const graph = new Map<string, string[]>();
 
 
@@ -0,0 +1,75 @@
+// Copyright (c) 2026 ObjectStack contributors. Apache-2.0 license.
+//
+// Two of `os doctor`'s config checks read a lookup field's target through a
+// truthiness gate — `if (field?.type === 'lookup' && field?.reference)` — and
+// then put the value straight into a graph node (`detectCircularDependencies`)
+// or a name set (`findUnusedObjects`). An object- or array-valued `reference`
+// passes truthiness, so a non-string entered both, where it matches no object
+// name and renders as `[object Object]` in a cycle message.
+//
+// `collectViewObjectRefs`, twenty lines away in the same file, already narrowed
+// its carrier with `typeof … === 'string'`; these two now read it through the
+// same arbiter the rest of the platform uses. Unreadability is REPORTED rather
+// than skipped, because both checks publish a positive verdict — "no circular
+// references detected", "defined but not referenced" — that an edge nobody
+// could read cannot support.
+
+import { describe, it, expect } from 'vitest';
+import { detectCircularDependencies, findUnusedObjects } from '../src/commands/doctor';
+
+/** An `ObjectSchema` literal where the target NAME belongs. */
+const UNREADABLE = { name: 'crm_account', fields: {} };
+
+const obj = (name: string, fields: Record<string, unknown>) => ({ name, label: name, fields });
+
+describe('doctor.detectCircularDependencies — an unreadable `reference` carrier', () => {
+  it('never puts a non-string into the dependency graph, and says so', () => {
+    const issues = detectCircularDependencies([
+      obj('crm_contact', { account: { type: 'lookup', reference: UNREADABLE } }),
+      obj('crm_account', {}),
+    ]);
+    expect(issues.join('\n')).not.toContain('[object Object]');
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toContain('crm_contact');
+    expect(issues[0]).toContain('account');
+    expect(issues[0]).toContain('doctor.detectCircularDependencies');
+  });
+
+  it('still detects a cycle built from readable targets', () => {
+    const issues = detectCircularDependencies([
+      obj('crm_contact', { account: { type: 'lookup', reference: 'crm_account' } }),
+      obj('crm_account', { primary_contact: { type: 'lookup', reference: 'crm_contact' } }),
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toContain('Circular dependency');
+  });
+
+  it('stays silent for a lookup that legitimately names no target', () => {
+    expect(detectCircularDependencies([obj('crm_contact', { account: { type: 'lookup' } })])).toEqual([]);
+  });
+});
+
+describe('doctor.findUnusedObjects — an unreadable `reference` carrier', () => {
+  const config = (reference: unknown) => ({
+    objects: [
+      obj('crm_contact', { account: { type: 'lookup', reference } }),
+      obj('crm_account', { title: { type: 'text' } }),
+    ],
+    views: [{ list: { type: 'grid', data: { provider: 'object', object: 'crm_contact' } } }],
+  });
+
+  it('reports the unreadable carrier rather than letting it distort the verdict', () => {
+    const found = findUnusedObjects(config(UNREADABLE));
+    expect(found.join('\n')).not.toContain('[object Object]');
+    // The carrier finding is present, and names the field that carries it.
+    expect(found.some(m => m.includes('crm_contact') && m.includes('account') && m.includes('unreadable')))
+      .toBe(true);
+    expect(found.some(m => m.includes('doctor.findUnusedObjects'))).toBe(true);
+  });
+
+  it('still counts a readable lookup target as a reference', () => {
+    // `crm_account` is referenced ONLY by the lookup, so this is the control
+    // that separates "narrowed" from "this path was closed".
+    expect(findUnusedObjects(config('crm_account'))).toEqual([]);
+  });
+});
@@ -0,0 +1,86 @@
+// Copyright (c) 2026 ObjectStack contributors. Apache-2.0 license.
+//
+// `resolveLookupFields` used to gate the carrier with a truthiness test and
+// then stringify it: `out.push({ key, reference: String(f.reference) })`. An
+// object-valued `reference` passes truthiness and `String()` renders it as the
+// literal target name `[object Object]` — a name that can never resolve, handed
+// on to `engine.find(<object name>)` by the inbox display enrichment and lost
+// inside that caller's own `catch`.
+//
+// `FieldSchema.reference` is declared an optional STRING, so the answer a
+// reader owes for an unreadable carrier is ABSENCE. These cases pin both
+// halves: the unreadable field is left out and reported, and a readable one is
+// still carried through unchanged — otherwise "fixed" and "this path is now
+// closed" would be indistinguishable.
+
+import { describe, it, expect, vi } from 'vitest';
+import { ApprovalService } from './approval-service.js';
+
+/** The one engine member `resolveLookupFields` reads. */
+const engineWithSchema = (fields: Record<string, unknown>) => ({
+  getSchema: (_object: string) => ({ fields }),
+}) as any;
+
+const makeService = () => {
+  const warn = vi.fn();
+  const service = new ApprovalService({
+    engine: engineWithSchema({
+      // Readable: the control that keeps this a narrowing rather than a shutdown.
+      account: { type: 'lookup', reference: 'crm_account' },
+      // Unreadable: an `ObjectSchema` literal where the target NAME belongs.
+      // `ObjectSchema.safeParse` refuses this at the contract door, so a value
+      // in this shape reached the reader without ever passing parse.
+      broken: { type: 'lookup', reference: { name: 'shop_invoice', fields: {} } },
+      // Unreadable in the other shape the arbiter names.
+      broken_array: { type: 'master_detail', reference: ['shop_invoice'] },
+      // Absence is legal and stays silent: `.optional()` admits it.
+      untargeted: { type: 'lookup' },
+      // Not a reference-typed field at all.
+      title: { type: 'text' },
+    }),
+    logger: { info() {}, warn, error() {}, debug() {} },
+  });
+  // `resolveLookupFields` is private and has no public seam: its sole consumer
+  // is the inbox display enrichment, which swallows every failure by design.
+  // Reading it directly is what makes the manufactured name assertable at all.
+  const resolve = (object: string) =>
+    (service as unknown as { resolveLookupFields(o: string): Array<{ key: string; reference: string }> })
+      .resolveLookupFields(object);
+  return { resolve, warn };
+};
+
+describe('ApprovalService.resolveLookupFields — an unreadable `reference` carrier', () => {
+  it('never manufactures the literal target name `[object Object]`', () => {
+    const { resolve } = makeService();
+    const references = resolve('deal').map(f => f.reference);
+    expect(references).not.toContain('[object Object]');
+    // The general form of the same claim: nothing a `String()` of a non-string
+    // could have produced survives into the result.
+    for (const reference of references) {
+      expect(typeof reference).toBe('string');
+      expect(reference).not.toMatch(/^\[object /);
+    }
+  });
+
+  it('leaves the unreadable fields out and still carries the readable one', () => {
+    const { resolve } = makeService();
+    expect(resolve('deal')).toEqual([{ key: 'account', reference: 'crm_account' }]);
+  });
+
+  it('reports each unreadable carrier instead of dropping it silently', () => {
+    const { resolve, warn } = makeService();
+    resolve('deal');
+    const messages = warn.mock.calls.map(args => String(args[0]));
+    expect(messages).toHaveLength(2);
+    expect(messages.some(m => m.includes('deal.broken'))).toBe(true);
+    expect(messages.some(m => m.includes('deal.broken_array'))).toBe(true);
+    // The refusal names the reader and says what to write instead.
+    expect(messages.every(m => m.includes('ApprovalService.resolveLookupFields'))).toBe(true);
+  });
+
+  it('stays silent for a field that legitimately names no target', () => {
+    const { resolve, warn } = makeService();
+    resolve('deal');
+    expect(warn.mock.calls.every(args => !String(args[0]).includes('untargeted'))).toBe(true);
+  });
+});
@@ -0,0 +1,77 @@
+// Copyright (c) 2026 ObjectStack contributors. Apache-2.0 license.
+//
+// ADR-0021's relationship → target-object resolver used to gate the carrier
+// with a truthiness test and return it: `if (… && field.reference) return
+// field.reference`. An object- or array-valued `reference` passes that gate, so
+// the JOINED TABLE for a dataset's `include` became a non-string — a value the
+// declared contract (`FieldSchema.reference`, an optional STRING) never admits.
+//
+// The resolver's answer for a carrier no reader can read is now ABSENCE, which
+// the resolver's own fallback turns into the compiler's "cannot resolve this
+// relationship" refusal, plus one warning naming the field. The readable case
+// is pinned alongside it, so a narrowing cannot be mistaken for a shutdown.
+
+import { describe, it, expect, vi } from 'vitest';
+import { AnalyticsServicePlugin } from '../plugin.js';
+
+type Resolver = (baseObject: string, relationshipName: string) => string | undefined;
+
+const OBJECTS: Record<string, { fields: Record<string, unknown> }> = {
+  shop_order: {
+    fields: {
+      // Readable — the control.
+      account: { type: 'lookup', reference: 'crm_account' },
+      // Unreadable: an object where the target NAME belongs. Refused by
+      // `ObjectSchema.safeParse`, so it only ever arrives unparsed.
+      broken: { type: 'lookup', reference: { name: 'shop_invoice', fields: {} } },
+      // Unreadable, array shape.
+      broken_array: { type: 'master_detail', reference: ['shop_invoice'] },
+      // Absence is legal and stays silent.
+      untargeted: { type: 'lookup' },
+    },
+  },
+};
+
+async function bootResolver() {
+  const warn = vi.fn();
+  const registered: Record<string, unknown> = {};
+  const ctx = {
+    getService: (name: string) =>
+      name === 'data'
+        ? { getObject: (o: string) => OBJECTS[o], aggregate: async () => [], execute: async () => ({ rows: [] }) }
+        : registered[name],
+    registerService: (name: string, svc: unknown) => { registered[name] = svc; },
+    replaceService: (name: string, svc: unknown) => { registered[name] = svc; },
+    logger: { info() {}, warn, error() {}, debug() {} },
+  };
+  await new AnalyticsServicePlugin().init(ctx as never);
+  // The resolver is a closure built inside `init` and handed to the service as
+  // config; the service's own field is the only handle on it. Driving a whole
+  // dataset compile would add scaffolding without changing what is measured —
+  // which value this function returns for an unreadable carrier.
+  const resolver = (registered.analytics as unknown as { relationshipResolver: Resolver }).relationshipResolver;
+  return { resolver, warn };
+}
+
+describe('analytics relationship resolver — an unreadable `reference` carrier', () => {
+  it('answers `undefined` instead of a non-string joined table', async () => {
+    const { resolver } = await bootResolver();
+    expect(resolver('shop_order', 'broken')).toBeUndefined();
+    expect(resolver('shop_order', 'broken_array')).toBeUndefined();
+  });
+
+  it('still resolves a readable target', async () => {
+    const { resolver } = await bootResolver();
+    expect(resolver('shop_order', 'account')).toBe('crm_account');
+  });
+
+  it('reports the unreadable carrier, and stays silent for a legal absence', async () => {
+    const { resolver, warn } = await bootResolver();
+    resolver('shop_order', 'untargeted');
+    expect(warn.mock.calls.filter(args => String(args[0]).includes('untargeted'))).toHaveLength(0);
+    resolver('shop_order', 'broken');
+    const messages = warn.mock.calls.map(args => String(args[0]));
+    expect(messages.some(m => m.includes('shop_order.broken'))).toBe(true);
+    expect(messages.some(m => m.includes('Analytics.relationshipResolver'))).toBe(true);
+  });
+});