From afcb857880125458154db2ea4191850431f1b74a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 3 Sep 2026 07:31:17 +0000
Subject: [PATCH] =?UTF-8?q?fix(types):=20object-map=20/=20object-gantt=20?=
 =?UTF-8?q?=E2=80=94=20objectName=20optional=20behind=20a=20record-source?=
 =?UTF-8?q?=20refinement=20(objectui#6939,=20group=206=20of=208)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both mirrors in packages/types/src/zod/objectql.zod.ts REQUIRED objectName, a key
both renderers read THIRD: getDataConfig in plugin-map/src/ObjectMap.tsx and
plugin-gantt/src/ObjectGantt.tsx resolve records from data, then staticData, then
objectName. A document authored on staticData alone drew correctly and was refused
by safeValidateSchema — six catalog entries, three per component.

- objectName becomes optional on both mirrors and both TS twins in the same stroke.
- Each member ends in requireRecordSource: a superRefine whose issue sits at the root
  path, carries params.code RECORD_SOURCE_REQUIRED and names data / staticData /
  objectName. Presence is `!== undefined` (the ruling's wording), so the accept set
  only widens: objectName alone, an empty one included, still parses.
- object-gantt additionally declares `data` (ViewDataSchema, the map's spelling): the
  resolver's FIRST read was undeclared on both faces, which would have left the
  refinement naming a key the validator had never heard of.
- Pins: validator contract in packages/types (six catalog entries validate; negative
  arm checked by path / params.code / message), and render identity in each
  renderer's own harness with BEFORE literals measured on d88e20f55.
- Docs: the two plugin pages' Schema API blocks say which of the three is required.

Maintainer ruling recorded 2026-09-02 (director seat, summon #8, decision batch #8).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EMrWaQw3XS5DxTHxp4yRyC
---
 .../6939-objectql-record-source-refinement.md |  33 ++++
 content/docs/plugins/plugin-gantt.mdx         |   7 +-
 content/docs/plugins/plugin-map.mdx           |   7 +-
 ...ecord-source-render-identity-6939.test.tsx | 174 ++++++++++++++++++
 ...bjectMap.catalogRecordSource-6939.test.tsx | 157 ++++++++++++++++
 packages/plugin-map/tsconfig.test.json        |   7 +-
 ...ctql-record-source-refinement-6939.test.ts | 151 +++++++++++++++
 packages/types/src/objectql.ts                |  47 ++++-
 packages/types/src/zod/objectql.zod.ts        |  82 ++++++++-
 9 files changed, 643 insertions(+), 22 deletions(-)
 create mode 100644 .changeset/6939-objectql-record-source-refinement.md
 create mode 100644 examples/schema-catalog/test/objectql-record-source-render-identity-6939.test.tsx
 create mode 100644 packages/plugin-map/src/ObjectMap.catalogRecordSource-6939.test.tsx
 create mode 100644 packages/types/src/__tests__/objectql-record-source-refinement-6939.test.ts

diff --git a/.changeset/6939-objectql-record-source-refinement.md b/.changeset/6939-objectql-record-source-refinement.md
new file mode 100644
index 0000000000..d1e5f5fe6a
--- /dev/null
+++ b/.changeset/6939-objectql-record-source-refinement.md
@@ -0,0 +1,33 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `object-map` and `object-gantt` mirrors: `objectName` is optional,
+and a refinement requires that at least one of `data`, `staticData`,
+`objectName` is present (objectui#6939, maintainer ruling recorded 2026-09-02 —
+this is one of the eight groups on that card, dispatched as its own PR per the
+ruling).
+
+Both renderers resolve their records from one of three keys, in this order —
+`getDataConfig` in `plugin-map/src/ObjectMap.tsx` and
+`plugin-gantt/src/ObjectGantt.tsx`: `data`, then `staticData`, then
+`objectName`. Both mirrors required `objectName` alone, so a document authored
+on `staticData` drew correctly and was refused by `safeValidateSchema` — six
+catalog entries, three per component.
+
+- **`object-map`** / **`object-gantt`**: `objectName` becomes optional on the
+  mirror and on the TypeScript twin in the same stroke, and each member ends in
+  `requireRecordSource`, whose issue sits at the root path, carries
+  `params.code = 'RECORD_SOURCE_REQUIRED'` and names the three keys an author
+  can supply.
+- **`object-gantt`** additionally declares `data` (as `ViewDataSchema`, the
+  spelling `object-map` already used): it is the FIRST key that resolver reads
+  and was undeclared on both faces, which would have left the refinement naming
+  a key the validator had never heard of.
+
+**patch, not minor: the accept set only widens toward what already renders.**
+Every document that validated before still validates — `objectName` alone,
+including an empty one, still parses, because presence is `!== undefined` and
+not the renderer's truthiness. The one shape the refinement refuses (none of
+the three) was refused before too, when `objectName` was required. Documents
+the renderers already draw start validating.
diff --git a/content/docs/plugins/plugin-gantt.mdx b/content/docs/plugins/plugin-gantt.mdx
index fe63288a4a..358c2d95ca 100644
--- a/content/docs/plugins/plugin-gantt.mdx
+++ b/content/docs/plugins/plugin-gantt.mdx
@@ -118,9 +118,10 @@ const schema = {
 ```plaintext
 {
   type: 'object-gantt',
-  objectName?: string,              // ObjectQL object name
-  staticData?: Array<any>,          // Static data array
-  data?: ViewData,                  // Advanced data configuration
+  objectName?: string,              // ObjectQL object name (read third)
+  staticData?: Array<any>,          // Static data array (read second)
+  data?: ViewData,                  // Advanced data configuration (read first)
+                                    // At least one of data / staticData / objectName is required
   gantt?: GanttConfig,              // Gantt-specific configuration
   viewMode?: 'day' | 'week' | 'month' | 'quarter' | 'year',
   readOnly?: boolean                // disable every edit path
diff --git a/content/docs/plugins/plugin-map.mdx b/content/docs/plugins/plugin-map.mdx
index 3adcddbdc1..4482a0f31b 100644
--- a/content/docs/plugins/plugin-map.mdx
+++ b/content/docs/plugins/plugin-map.mdx
@@ -102,9 +102,10 @@ const schema = {
 ```plaintext
 {
   type: 'object-map',
-  objectName: string,               // ObjectQL object name
-  staticData?: Array<any>,          // Static data array
-  data?: ViewData,                  // Advanced data configuration
+  objectName?: string,              // ObjectQL object name (read third)
+  staticData?: Array<any>,          // Static data array (read second)
+  data?: ViewData,                  // Advanced data configuration (read first)
+                                    // At least one of data / staticData / objectName is required
   filter?: Array<any>,              // Query filter, sent as $filter
   sort?: string | SortConfig[],     // Sort, sent as $orderby
   map?: ObjectMapConfig,            // Map-specific configuration
diff --git a/examples/schema-catalog/test/objectql-record-source-render-identity-6939.test.tsx b/examples/schema-catalog/test/objectql-record-source-render-identity-6939.test.tsx
new file mode 100644
index 0000000000..752954415d
--- /dev/null
+++ b/examples/schema-catalog/test/objectql-record-source-render-identity-6939.test.tsx
@@ -0,0 +1,174 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `object-map` + `object-gantt` group — the GANTT half of
+ * the render pin. `ObjectGanttSchema` used to require `objectName`, a key the
+ * renderer reads THIRD (`getDataConfig` in `plugin-gantt/src/ObjectGantt.tsx`:
+ * `data`, then `staticData`, then `objectName`), so the three `staticData`-only
+ * catalog entries below drew correctly and were refused by `safeValidateSchema`.
+ * The repair makes `objectName` optional behind a refinement; the validator-side
+ * contract is pinned in `packages/types/src/__tests__/objectql-record-source-
+ * refinement-6939.test.ts`, and the `object-map` tiles are pinned in
+ * `packages/plugin-map/src/ObjectMap.catalogRecordSource-6939.test.tsx`.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So the repair has to clear the mirror
+ * image of that bar — the validator's verdict must change and the renderer's
+ * output must NOT. The numbers in `PRE_REPAIR` were measured on `origin/main`
+ * at `d88e20f55`, BEFORE the mirror was touched, through THIS file's harness.
+ *
+ * ## The harness, and why it is named
+ *
+ * A bare `SchemaRenderer` is not enough here: `ObjectGantt` calls
+ * `useSchemaContext`, so without a `SchemaRendererProvider` the tile is the
+ * error boundary — 4 elements reading `Component "object-gantt" failed to
+ * render` — and an identity pin over THAT is the vacuous pin this file must
+ * not be. Measured through the provider-wrapped bare renderer below, the three
+ * tiles draw 407 / 354 / 436 elements. The docs-gallery harness
+ * (`catalog-gallery-render.test.tsx`, provider + `SidebarProvider` + a padded
+ * wrapper) gives different absolute counts for the same tile; identity within
+ * ONE harness is the claim that discriminates. `Date` is frozen because the
+ * chart carries a Today marker and a date-stamped export name — the pin must
+ * not move with the calendar.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text — the visible
+ * text as a literal (the chart's own `<style>` block is part of `textContent`
+ * and is folded into the hash instead, at ~2.7 KB it is not a readable pin),
+ * plus a SHA-256 of the full `textContent`, style block included.
+ */
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { render, waitFor } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import '@object-ui/plugin-gantt';
+import { SchemaRenderer, SchemaRendererProvider, toRenderableSchema } from '@object-ui/react';
+import { safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+  'plugin-gantt/construction-project-phases',
+  'plugin-gantt/project-timeline-with-dependencies',
+  'plugin-gantt/sprint-development-timeline',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `d88e20f55` through `measure()` below, mirror
+ * untouched. `sha256` is over the full `textContent`; `visibleText` is the
+ * same string with the chart's `<style>` element's text removed.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+  elements: number;
+  tags: Record<string, number>;
+  sha256: string;
+  visibleText: string;
+}> = {
+  'plugin-gantt/construction-project-phases': {
+    elements: 407,
+    tags: { DIV: 185, STYLE: 1, BUTTON: 26, svg: 19, path: 52, SPAN: 112, circle: 2, line: 5, rect: 1, defs: 1, marker: 3 },
+    sha256: '19a41af45950a5c6be4b440dfb09c154826f049be3b87e75931348a21b1746cb',
+    visibleText:
+      'January 2024DayWeekMonthQuarterYearTodayThis weekThis monthTask NameJan 2024Feb 2024Mar 2024' +
+      '25T26F27S28S29M30T31W1T2F3S4S5M6T7W8T9F10S11S12M13T14W15T16F17S18S19M20T21W22T23F24S25S26M27T28W29T1F2S3S' +
+      'Site Preparation2/1 → 2/14Foundation2/15 → 3/15Framing3/16 → 4/30Electrical & Plumbing5/1 → 5/31Interior Finishing6/1 → 7/15' +
+      'Site Preparation100%Foundation75%Framing30%Electrical & Plumbing0%Interior Finishing0%',
+  },
+  'plugin-gantt/project-timeline-with-dependencies': {
+    elements: 354,
+    tags: { DIV: 156, STYLE: 1, BUTTON: 24, svg: 17, path: 44, SPAN: 100, circle: 2, line: 5, rect: 1, defs: 1, marker: 3 },
+    sha256: '3294ccbe33d159b947d01ea52f367b26ce7b4084a1ae89f0ed54661cf36002f8',
+    visibleText:
+      'December 2023DayWeekMonthQuarterYearTodayThis weekThis monthTask NameDec 2023Jan 2024Feb 2024' +
+      '25M26T27W28T29F30S31S1M2T3W4T5F6S7S8M9T10W11T12F13S14S15M16T17W18T19F20S21S22M23T24W25T26F27S28S29M30T31W1T' +
+      'Design Phase1/1 → 1/15Development1/16 → 2/28Testing3/1 → 3/15' +
+      'Design Phase100%Development60%Testing0%',
+  },
+  'plugin-gantt/sprint-development-timeline': {
+    elements: 436,
+    tags: { DIV: 200, STYLE: 1, BUTTON: 27, svg: 20, path: 58, SPAN: 118, circle: 2, line: 5, rect: 1, defs: 1, marker: 3 },
+    sha256: 'af064c159287029592b508f22314336603aafacaf33bfdc67325e2212c6350d4',
+    visibleText:
+      'December 2023DayWeekMonthQuarterYearTodayThis weekThis monthTask NameDec 2023Jan 2024Feb 2024' +
+      '25M26T27W28T29F30S31S1M2T3W4T5F6S7S8M9T10W11T12F13S14S15M16T17W18T19F20S21S22M23T24W25T26F27S28S29M30T31W1T' +
+      'Sprint Planning1/1 → 1/3User Authentication1/4 → 1/10Dashboard UI1/4 → 1/12API Integration1/11 → 1/18Testing & QA1/19 → 1/25Deployment1/26 → 1/28' +
+      'Sprint Planning100%User Authentication100%Dashboard UI85%API Integration40%Testing & QA0%Deployment0%',
+  },
+};
+
+beforeAll(() => {
+  vi.useFakeTimers({ toFake: ['Date'] });
+  vi.setSystemTime(new Date('2026-09-03T12:00:00Z'));
+});
+afterAll(() => vi.useRealTimers());
+
+/** Render one entry through the provider-wrapped bare renderer and measure what it drew. */
+async function measure(schema: unknown) {
+  const { container, unmount } = render(
+    // No host DataSource: every entry authors `staticData`, which the
+    // renderer wraps into its own in-memory ValueDataSource. The provider
+    // itself is load-bearing (`useSchemaContext`).
+    <SchemaRendererProvider dataSource={undefined}>
+      <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />
+    </SchemaRendererProvider>,
+  );
+  // The chart loads its inline rows through a ValueDataSource, so its first
+  // paint is the loading placeholder; measure only once that is gone.
+  await waitFor(() => expect(container.textContent ?? '').not.toContain('Loading Gantt chart...'));
+  const nodes = Array.from(container.querySelectorAll('*'));
+  const text = container.textContent ?? '';
+  const styleText = Array.from(container.querySelectorAll('style')).map((el) => el.textContent ?? '');
+  const tags = nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {});
+  const out = {
+    elements: nodes.length,
+    tags,
+    sha256: createHash('sha256').update(text).digest('hex'),
+    visibleText: styleText.reduce((t, s) => t.replace(s, ''), text),
+    text,
+  };
+  unmount();
+  return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+  const r = safeValidateSchema(schema);
+  return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+describe('objectui#6939 — the three gantt entries the mirror refused now validate', () => {
+  it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+    // Each reported `: Invalid input` (the union's own top-level issue)
+    // before this card, for a key the renderer reads third.
+    expect(reasons(getExample(id).schema)).toEqual([]);
+  });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+  it.each(IDS)('%s renders exactly what it rendered before', async (id) => {
+    const after = await measure(getExample(id).schema);
+    const before = PRE_REPAIR[id];
+    expect(after.elements).toBe(before.elements);
+    expect(after.tags).toEqual(before.tags);
+    expect(after.visibleText).toBe(before.visibleText);
+    expect(after.sha256).toBe(before.sha256);
+  });
+
+  it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tasks, not an error box', async (id) => {
+    // An entry that renders nothing — or the error boundary — satisfies
+    // "identical" trivially. The authored titles on screen prove the rows
+    // reached the chart through `staticData`, the source the mirror ignored.
+    const schema = getExample(id).schema as { staticData: Record<string, string>[]; gantt: { titleField: string } };
+    const m = await measure(schema);
+    expect(m.elements).toBeGreaterThan(100);
+    expect(m.text).not.toContain('failed to render');
+    for (const row of schema.staticData) {
+      expect(m.visibleText).toContain(row[schema.gantt.titleField]);
+    }
+  });
+});
diff --git a/packages/plugin-map/src/ObjectMap.catalogRecordSource-6939.test.tsx b/packages/plugin-map/src/ObjectMap.catalogRecordSource-6939.test.tsx
new file mode 100644
index 0000000000..67447a7248
--- /dev/null
+++ b/packages/plugin-map/src/ObjectMap.catalogRecordSource-6939.test.tsx
@@ -0,0 +1,157 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * objectui#6939, the `object-map` + `object-gantt` group — the MAP half of the
+ * render pin. `ObjectMapSchema` used to require `objectName`, a key this
+ * renderer reads THIRD (`getDataConfig` below in `ObjectMap.tsx`: `data`, then
+ * `staticData`, then `objectName`), so the three `staticData`-only catalog
+ * entries drew correctly and were refused by `safeValidateSchema`. The repair
+ * makes `objectName` optional behind a refinement; the validator-side contract
+ * is pinned in `packages/types/src/__tests__/objectql-record-source-
+ * refinement-6939.test.ts`, and the gantt tiles in `examples/schema-catalog/
+ * test/objectql-record-source-render-identity-6939.test.tsx`.
+ *
+ * ## Why this half lives HERE and not beside the catalog
+ *
+ * `object-map` mounts maplibre, which wants WebGL2 and a live tile host; the
+ * gallery pin excludes these three tiles for that reason and every test in
+ * this package stands `react-map-gl/maplibre` in. That stand-in only takes
+ * effect from a package that RESOLVES the specifier: measured from
+ * `examples/schema-catalog`, the identical `vi.mock` is inert — the real
+ * maplibre mounts and the tile is the error boundary (`Cannot read properties
+ * of undefined (reading 'destroy')`). The `aria-label="Map"` control below is
+ * what proves the stand-in is live for every reading in this file.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So the repair has to clear the mirror
+ * image of that bar — the validator's verdict must change and the renderer's
+ * output must NOT. `PRE_REPAIR` was measured on `origin/main` at `d88e20f55`,
+ * BEFORE the mirror was touched, through THIS file's harness: a
+ * `SchemaRendererProvider`-wrapped bare `SchemaRenderer` (the provider is
+ * load-bearing — `ObjectMap` calls `useSchemaContext`), `Date` frozen. The
+ * docs-gallery harness gives different absolute counts for the same tile;
+ * identity within ONE harness is the claim that discriminates.
+ */
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { render, waitFor } from '@testing-library/react';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SchemaRenderer, SchemaRendererProvider, toRenderableSchema } from '@object-ui/react';
+import { safeValidateSchema } from '@object-ui/types/zod';
+import './index';
+
+vi.mock('react-map-gl/maplibre', () => ({
+  default: (props: any) => <div aria-label="Map">{props.children}</div>,
+  Map: ({ children }: any) => <div aria-label="Map">{children}</div>,
+  NavigationControl: () => <div data-testid="nav-control" />,
+  Marker: ({ children, longitude, latitude }: any) => (
+    <div data-testid="map-marker" data-lat={latitude} data-lng={longitude}>
+      {children}
+    </div>
+  ),
+  Popup: ({ children }: any) => <div data-testid="map-popup">{children}</div>,
+}));
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+const NAMES = ['event-venue-finder', 'real-time-delivery-tracking', 'store-locator-map'] as const;
+
+function catalogEntry(name: string): { staticData: Record<string, unknown>[]; map: { titleField: string } } {
+  const file = path.join(REPO_ROOT, 'examples/schema-catalog/src/schemas/plugin-map', `${name}.json`);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/**
+ * Measured on `origin/main` @ `d88e20f55` through `measure()` below, mirror
+ * untouched. The text is the geolocate control's glyph followed by one marker
+ * glyph per authored row; the tag list is the DOM in document order.
+ */
+const PIN = '\u{1F4CD}'; // the marker glyph ObjectMap draws per record
+const COMPASS = '\u{1F9ED}'; // the geolocate control's glyph
+const SHELL = ['DIV', 'DIV', 'INPUT', 'DIV', 'DIV', 'DIV', 'BUTTON', 'SPAN', 'DIV', 'DIV', 'DIV'];
+const PRE_REPAIR: Record<(typeof NAMES)[number], { elements: number; text: string; tags: string[]; markers: number }> = {
+  'event-venue-finder': { elements: 16, text: COMPASS + PIN.repeat(4), tags: [...SHELL, 'DIV', 'DIV', 'DIV', 'DIV', 'DIV'], markers: 4 },
+  'real-time-delivery-tracking': { elements: 14, text: COMPASS + PIN.repeat(3), tags: [...SHELL, 'DIV', 'DIV', 'DIV'], markers: 3 },
+  'store-locator-map': { elements: 14, text: COMPASS + PIN.repeat(3), tags: [...SHELL, 'DIV', 'DIV', 'DIV'], markers: 3 },
+};
+
+beforeAll(() => {
+  vi.useFakeTimers({ toFake: ['Date'] });
+  vi.setSystemTime(new Date('2026-09-03T12:00:00Z'));
+});
+afterAll(() => vi.useRealTimers());
+
+/** Render one entry through the provider-wrapped bare renderer and measure what it drew. */
+async function measure(schema: unknown) {
+  const { container, unmount } = render(
+    // No host DataSource: every entry authors `staticData`, which the
+    // renderer wraps into its own in-memory ValueDataSource. The provider
+    // itself is load-bearing (`useSchemaContext`).
+    <SchemaRendererProvider dataSource={undefined}>
+      <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />
+    </SchemaRendererProvider>,
+  );
+  await waitFor(() => expect(container.textContent ?? '').not.toContain('Loading map...'));
+  const nodes = Array.from(container.querySelectorAll('*'));
+  const out = {
+    elements: nodes.length,
+    text: container.textContent ?? '',
+    tags: nodes.map((el) => el.tagName),
+    markers: container.querySelectorAll('[data-testid="map-marker"]').length,
+    standInLive: Boolean(container.querySelector('[aria-label="Map"]')),
+  };
+  unmount();
+  return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+  const r = safeValidateSchema(schema);
+  return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+describe('objectui#6939 — the three map entries the mirror refused now validate', () => {
+  it.each(NAMES)('%s validates under safeValidateSchema', (name) => {
+    const doc = catalogEntry(name);
+    // The control that makes the case discriminating: the entry authors NO
+    // `objectName` and DOES author `staticData`. Each reported `: Invalid
+    // input` (the union's own top-level issue) before this card.
+    expect('objectName' in doc).toBe(false);
+    expect(Array.isArray(doc.staticData)).toBe(true);
+    expect(reasons(doc)).toEqual([]);
+  });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+  it.each(NAMES)('%s renders exactly what it rendered before', async (name) => {
+    const after = await measure(catalogEntry(name));
+    const before = PRE_REPAIR[name];
+    expect(after.elements).toBe(before.elements);
+    expect(after.text).toBe(before.text);
+    expect(after.tags).toEqual(before.tags);
+    expect(after.markers).toBe(before.markers);
+  });
+
+  it.each(NAMES)('%s anti-vacuity: one marker per AUTHORED row, drawn on the live stand-in', async (name) => {
+    // An entry that renders nothing — or the error boundary — satisfies
+    // "identical" trivially. One marker per `staticData` row proves the rows
+    // reached the map through the source the mirror ignored, and the
+    // stand-in's own label proves the reading is of `ObjectMap`, not of
+    // maplibre failing to mount.
+    const doc = catalogEntry(name);
+    const m = await measure(doc);
+    expect(m.standInLive).toBe(true);
+    expect(m.text).not.toContain('failed to render');
+    expect(m.markers).toBe(doc.staticData.length);
+    expect(m.markers).toBeGreaterThan(0);
+  });
+});
diff --git a/packages/plugin-map/tsconfig.test.json b/packages/plugin-map/tsconfig.test.json
index d694d96f8d..6b26d1d2ba 100644
--- a/packages/plugin-map/tsconfig.test.json
+++ b/packages/plugin-map/tsconfig.test.json
@@ -13,8 +13,11 @@
     // a global augmentation, not an import, and `@testing-library/jest-dom` does
     // not live under `@types/` — so it is never picked up automatically and has
     // to be named here. Naming `types` at all switches off automatic `@types/*`
-    // inclusion, which is fine: nothing in these tests touches Node globals.
-    "types": ["@testing-library/jest-dom"],
+    // inclusion.
+    // `node` is named too (the shape `plugin-calendar` and `plugin-chatbot` use):
+    // `ObjectMap.catalogRecordSource-6939.test.tsx` reads the schema-catalog
+    // fixtures off disk with `node:fs`.
+    "types": ["@testing-library/jest-dom", "node"],
     // Drop the root tsconfig's source-tree `paths` so `@object-ui/*` and
     // `@objectstack/spec` resolve through the workspace dependency's built
     // `.d.ts` instead of pulling sibling sources in as program inputs (TS6059).
diff --git a/packages/types/src/__tests__/objectql-record-source-refinement-6939.test.ts b/packages/types/src/__tests__/objectql-record-source-refinement-6939.test.ts
new file mode 100644
index 0000000000..464a6a5a75
--- /dev/null
+++ b/packages/types/src/__tests__/objectql-record-source-refinement-6939.test.ts
@@ -0,0 +1,151 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * objectui#6939, the `object-map` + `object-gantt` group — one of the eight the
+ * card measured, dispatched as its own PR per the maintainer ruling recorded
+ * 2026-09-02 (director seat, summon #8, decision batch #8):
+ *
+ *   > `object-map` + `object-gantt`: `objectName` becomes optional with a
+ *   > refinement that at least one of `data`, `staticData`, `objectName` is
+ *   > present.
+ *
+ * ## The defect
+ *
+ * Both mirrors REQUIRED `objectName`. Both renderers resolve their records from
+ * one of THREE keys, in this order — `getDataConfig` in
+ * `plugin-map/src/ObjectMap.tsx` (`schema.data`, `schema.staticData`,
+ * `schema.objectName`) and `plugin-gantt/src/ObjectGantt.tsx` (the same three,
+ * the same order). A document authored on `staticData` alone draws correctly
+ * and was refused by `safeValidateSchema`: six catalog entries, three per
+ * component, every one of them `staticData`-only.
+ *
+ * ## What this file pins — the VALIDATOR half
+ *
+ * The render half ("byte-identical in element count and text before and after")
+ * lives beside each renderer, where the tile can actually be drawn:
+ * `examples/schema-catalog/test/objectql-record-source-render-identity-6939.test.tsx`
+ * (gantt) and `packages/plugin-map/src/ObjectMap.catalogRecordSource-6939.test.tsx`
+ * (map — maplibre has to be stood in for, and the stand-in only takes effect
+ * from the package that resolves `react-map-gl/maplibre`).
+ *
+ * The negative arm asserts the ISSUE, not merely that the parse failed: a
+ * document refused for an unrelated reason would otherwise read as a passing
+ * pin. The refinement's issue is checked by `path`, `params.code` and the three
+ * key names in its message.
+ */
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ObjectGanttSchema, ObjectMapSchema, safeValidateSchema } from '../zod/index.zod';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+
+/** The six catalog entries the card counts behind these two rows. */
+const CATALOG_ENTRIES = [
+  'plugin-map/event-venue-finder',
+  'plugin-map/real-time-delivery-tracking',
+  'plugin-map/store-locator-map',
+  'plugin-gantt/construction-project-phases',
+  'plugin-gantt/project-timeline-with-dependencies',
+  'plugin-gantt/sprint-development-timeline',
+] as const;
+
+function catalogEntry(id: string): Record<string, unknown> {
+  const file = path.join(REPO_ROOT, 'examples/schema-catalog/src/schemas', `${id}.json`);
+  return JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+  const r = safeValidateSchema(schema);
+  return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+const MEMBERS = [
+  ['object-map', ObjectMapSchema],
+  ['object-gantt', ObjectGanttSchema],
+] as const;
+
+describe('objectui#6939 — the six catalog entries the mirrors refused now validate', () => {
+  it.each(CATALOG_ENTRIES)('%s validates under safeValidateSchema', (id) => {
+    const doc = catalogEntry(id);
+    // The control that makes the case discriminating: every one of these
+    // authors NO `objectName` and DOES author `staticData`. Before this card
+    // each reported `: Invalid input` (the union's own top-level issue).
+    expect('objectName' in doc).toBe(false);
+    expect(Array.isArray(doc.staticData)).toBe(true);
+    expect(reasons(doc)).toEqual([]);
+  });
+});
+
+describe('objectui#6939 — any ONE of the three record sources satisfies the refinement', () => {
+  it.each(MEMBERS)('%s accepts `data` alone, `staticData` alone and `objectName` alone', (type, member) => {
+    expect(member.safeParse({ type, data: { provider: 'object', object: 'tasks' } }).success).toBe(true);
+    expect(member.safeParse({ type, staticData: [] }).success).toBe(true);
+    expect(member.safeParse({ type, objectName: 'tasks' }).success).toBe(true);
+    // …and the same three through the published entry point.
+    expect(reasons({ type, staticData: [{ id: 1 }] })).toEqual([]);
+    expect(reasons({ type, objectName: 'tasks' })).toEqual([]);
+  });
+
+  it.each(MEMBERS)('%s: the accept set only WIDENED — `objectName` alone still parses, an empty one included', (type, member) => {
+    // Presence is `!== undefined`, not the renderer's truthiness: `objectName:
+    // ''` validated before this card (a required `z.string()` accepts '') and
+    // must still validate, or the change would narrow something.
+    expect(member.safeParse({ type, objectName: '' }).success).toBe(true);
+  });
+});
+
+describe('objectui#6939 — a document with NONE of the three is refused ON THE REFINEMENT', () => {
+  it.each(MEMBERS)('%s: one root-level issue, keyed RECORD_SOURCE_REQUIRED, naming all three keys', (type, member) => {
+    const result = member.safeParse({ type, label: 'no source at all' });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    // Exactly one issue, and it is the refinement's — not a stray key-level
+    // failure that would make this case green for the wrong reason.
+    expect(result.error.issues).toHaveLength(1);
+    const issue = result.error.issues[0];
+    expect(issue.code).toBe('custom');
+    expect(issue.path).toEqual([]);
+    expect((issue as { params?: { code?: string } }).params?.code).toBe('RECORD_SOURCE_REQUIRED');
+    for (const key of ['data', 'staticData', 'objectName']) {
+      expect(issue.message).toContain(`\`${key}\``);
+    }
+    expect(issue.message).toContain(`\`${type}\``);
+  });
+
+  it.each(MEMBERS)('%s: …and the published entry point refuses it too', (type) => {
+    expect(safeValidateSchema({ type }).success).toBe(false);
+  });
+});
+
+describe('objectui#6939 — the refinement sits on declared keys, and the objects stayed objects', () => {
+  it.each(MEMBERS)('%s still exposes `.shape`, with `objectName` optional in it', (_type, member) => {
+    // zod 4 attaches a refinement to the object in place; had it wrapped the
+    // object, `.shape` would be gone and the parity census in
+    // `zod-mirror-parity.test.ts` would read the pair as vacuous.
+    const shape = (member as unknown as { shape: Record<string, { safeParse: (v: unknown) => { success: boolean } }> }).shape;
+    expect(Object.keys(shape)).toEqual(expect.arrayContaining(['objectName', 'data', 'staticData']));
+    expect(shape.objectName.safeParse(undefined).success).toBe(true);
+    expect(shape.objectName.safeParse(5).success).toBe(false);
+  });
+
+  it('object-gantt: `data` is DECLARED, not a passthrough hole', () => {
+    // Counter-probe. `data` was undeclared on the gantt mirror until this
+    // card, so a malformed value rode through `.passthrough()` unvalidated —
+    // and the refinement would have accepted a document on the strength of a
+    // key the validator had never heard of. `objectName` is supplied so the
+    // only thing under test is the value of `data`.
+    expect(ObjectGanttSchema.safeParse({ type: 'object-gantt', objectName: 'tasks', data: 'nope' }).success).toBe(false);
+    expect(ObjectGanttSchema.safeParse({ type: 'object-gantt', objectName: 'tasks', data: { provider: 'object', object: 'tasks' } }).success).toBe(true);
+    // Same shape as the map's, so the two record sources cannot fork.
+    expect(ObjectMapSchema.safeParse({ type: 'object-map', objectName: 'stores', data: 'nope' }).success).toBe(false);
+  });
+});
diff --git a/packages/types/src/objectql.ts b/packages/types/src/objectql.ts
index 9c33501f15..651c8a9016 100644
--- a/packages/types/src/objectql.ts
+++ b/packages/types/src/objectql.ts
@@ -2255,14 +2255,25 @@ export interface ObjectMapConfig {
  */
 export interface ObjectMapSchema extends BaseSchema {
   type: 'object-map';
-  /** ObjectQL object name */
-  objectName: string;
   /**
-   * Data source configuration. Preferred over `staticData` / `objectName`
-   * (`getDataConfig`).
+   * ObjectQL object name — the THIRD record source `getDataConfig` resolves,
+   * after {@link ObjectMapSchema.data} and {@link ObjectMapSchema.staticData}
+   * (`plugin-map/src/ObjectMap.tsx`).
+   *
+   * Optional since objectui#6939: a map authored on inline rows never reads
+   * this key, and requiring it refused three catalog entries that draw
+   * correctly. The requirement the renderer really has — at least one of
+   * `data`, `staticData`, `objectName` present — lives on the mirror as a
+   * refinement (`requireRecordSource` in `zod/objectql.zod.ts`), so the
+   * published declaration and the published validator say the same thing.
+   */
+  objectName?: string;
+  /**
+   * Data source configuration. Read FIRST by `getDataConfig`, ahead of
+   * `staticData` / `objectName`.
    */
   data?: ViewData;
-  /** Inline records, wrapped into a `{ provider: 'value' }` data config */
+  /** Inline records, wrapped into a `{ provider: 'value' }` data config; read SECOND */
   staticData?: any[];
   /** Query filter, forwarded verbatim as `$filter` */
   filter?: any[];
@@ -2342,8 +2353,30 @@ export interface ObjectTreeSchema extends BaseSchema {
  */
 export interface ObjectGanttSchema extends BaseSchema {
   type: 'object-gantt';
-  /** ObjectQL object name */
-  objectName: string;
+  /**
+   * ObjectQL object name — the THIRD record source `getDataConfig` resolves,
+   * after {@link ObjectGanttSchema.data} and {@link ObjectGanttSchema.staticData}
+   * (`plugin-gantt/src/ObjectGantt.tsx`).
+   *
+   * Optional since objectui#6939: a gantt authored on inline rows never reads
+   * this key, and requiring it refused three catalog entries that draw
+   * correctly. The requirement the renderer really has — at least one of
+   * `data`, `staticData`, `objectName` present — lives on the mirror as a
+   * refinement (`requireRecordSource` in `zod/objectql.zod.ts`), so the
+   * published declaration and the published validator say the same thing.
+   */
+  objectName?: string;
+  /**
+   * Data source configuration. Read FIRST by `getDataConfig` — `if
+   * (schema.data) return schema.data;` — ahead of `staticData` / `objectName`.
+   *
+   * Declared by objectui#6939, in the same stroke as the mirror's `data`: until
+   * then the read landed on `BaseSchema`'s index signature on this side and
+   * on `.passthrough()` on the mirror's, so the record source the resolver
+   * prefers was the one neither face named. Same type as
+   * {@link ObjectMapSchema.data}.
+   */
+  data?: ViewData;
   /** Field for task start date */
   startDateField?: string;
   /** Field for task end date */
diff --git a/packages/types/src/zod/objectql.zod.ts b/packages/types/src/zod/objectql.zod.ts
index fc9b5e4136..507b8d66e3 100644
--- a/packages/types/src/zod/objectql.zod.ts
+++ b/packages/types/src/zod/objectql.zod.ts
@@ -569,6 +569,56 @@ export const ObjectMapConfigSchema = z.object({
   style: z.string().optional().describe('MapLibre style URL/spec (overrides the public demo default)'),
 });
 
+/**
+ * objectui#6939 — the record-source refinement `ObjectMapSchema` and
+ * `ObjectGanttSchema` below share.
+ *
+ * Both renderers resolve their records from ONE of three keys, in this order:
+ * `data` (a spec `ViewData` config), `staticData` (inline rows, wrapped into a
+ * `{ provider: 'value' }` config) or `objectName` (the bound object) —
+ * `getDataConfig` in `plugin-map/src/ObjectMap.tsx` and
+ * `plugin-gantt/src/ObjectGantt.tsx`, each `if (schema.data) … if
+ * (schema.staticData) … if (schema.objectName) … return null`. Both mirrors
+ * used to REQUIRE `objectName` alone, so a document authored on `staticData`
+ * (6 of the 20 catalog entries objectui#6939 measured) drew correctly and was
+ * refused by `safeValidateSchema` — `declared !== enforced`, with the corpus
+ * on the right side. `objectName` is optional on both members now, and this
+ * refinement carries the requirement the renderers actually have: with none of
+ * the three present `getDataConfig` returns `null` and nothing is drawn.
+ *
+ * Presence is `!== undefined` — the ruling's wording ("at least one of `data`,
+ * `staticData`, `objectName` is present"), NOT the renderers' truthiness: an
+ * empty `objectName: ''` validated before this card and still does, so the
+ * accept set only WIDENS. The one document shape refused here (none of the
+ * three) was refused before too, when `objectName` was required. Maintainer
+ * ruling recorded 2026-09-02 (director seat, summon #8, decision batch #8).
+ *
+ * The issue carries `params.code` so a consumer can key off the finding rather
+ * than string-match the message — the shape `FormFieldSchema`'s refinement in
+ * `form.zod.ts` uses; zod's own `code` is `custom` for every refinement. The
+ * path is the ROOT (`[]`): no single key is at fault when all three are absent,
+ * and blaming `objectName` would re-teach the requiredness this card removes.
+ *
+ * Deliberately a `function`, not an `export const`: the parity census in
+ * `__tests__/zod-mirror-parity.test.ts` reads `^export const` out of this
+ * directory and would demand a registered TS counterpart for it.
+ */
+const RECORD_SOURCE_KEYS = ['data', 'staticData', 'objectName'] as const;
+function requireRecordSource(type: 'object-map' | 'object-gantt') {
+  return (
+    schema: Partial<Record<(typeof RECORD_SOURCE_KEYS)[number], unknown>>,
+    ctx: z.core.$RefinementCtx,
+  ): void => {
+    if (RECORD_SOURCE_KEYS.some((key) => schema[key] !== undefined)) return;
+    ctx.addIssue({
+      code: 'custom',
+      path: [],
+      params: { code: 'RECORD_SOURCE_REQUIRED' },
+      message: `\`${type}\` has no record source: declare one of \`data\`, \`staticData\` or \`objectName\``,
+    });
+  };
+}
+
 /**
  * ObjectMap Schema
  *
@@ -578,12 +628,18 @@ export const ObjectMapConfigSchema = z.object({
  * out of this declaration (maintainer ruling on objectui#5018, 2026-08-17) —
  * except `locationField` / `titleField`, which were published before the
  * ruling and stay for compatibility.
+ *
+ * `objectName` is OPTIONAL and the member ends in `requireRecordSource`
+ * (objectui#6939): `getDataConfig` reads `data`, then `staticData`, then
+ * `objectName`, so a map authored on inline rows never reads the object name —
+ * three catalog entries drew correctly and were refused here. Requiredness
+ * moved to the refinement above, which is where the renderer actually has it.
  */
 export const ObjectMapSchema = BaseSchema.extend({
   type: z.literal('object-map'),
-  objectName: z.string().describe('ObjectQL object name'),
-  data: ViewDataSchema.optional().describe('Data source configuration'),
-  staticData: z.array(z.any()).optional().describe('Inline records'),
+  objectName: z.string().optional().describe('ObjectQL object name — the THIRD record source getDataConfig resolves, after data and staticData; one of the three must be present (objectui#6939)'),
+  data: ViewDataSchema.optional().describe('Data source configuration — read FIRST by getDataConfig'),
+  staticData: z.array(z.any()).optional().describe('Inline records — read SECOND by getDataConfig, wrapped into a { provider: value } config'),
   filter: z.array(z.any()).optional().describe('Query filter, forwarded as $filter'),
   sort: z.union([z.string(), z.array(SortConfigSchema)]).optional().describe('Sort configuration, forwarded as $orderby'),
   map: ObjectMapConfigSchema.optional().describe('Map configuration (the author face)'),
@@ -592,7 +648,7 @@ export const ObjectMapSchema = BaseSchema.extend({
   locationField: z.string().optional().describe('Location field (internal flat form; prefer map.locationField)'),
   titleField: z.string().optional().describe('Title field (internal flat form; prefer map.titleField)'),
   mapStyle: z.string().optional().describe('MapLibre style URL/spec (overrides the public demo default)'),
-});
+}).superRefine(requireRecordSource('object-map'));
 
 /**
  * ObjectTree (tree-grid) Schema
@@ -664,10 +720,22 @@ const GanttConfigExtensionFields = {
 
 /**
  * ObjectGantt Schema
+ *
+ * `objectName` is OPTIONAL and the member ends in `requireRecordSource`
+ * (objectui#6939): `getDataConfig` (`plugin-gantt/src/ObjectGantt.tsx`) reads
+ * `data`, then `staticData`, then `objectName`, so a gantt authored on inline
+ * rows never reads the object name — three catalog entries drew correctly and
+ * were refused here. `data` is declared for the first time in the same stroke:
+ * it is the FIRST read of that resolver and was undeclared on both faces
+ * (surviving on `BaseSchema`'s index signature), which would have left the
+ * refinement naming a key this mirror had never heard of. It is spelled exactly
+ * as `ObjectMapSchema.data` above, so the two members' record sources cannot
+ * fork.
  */
 export const ObjectGanttSchema = BaseSchema.extend({
   type: z.literal('object-gantt'),
-  objectName: z.string().describe('ObjectQL object name'),
+  objectName: z.string().optional().describe('ObjectQL object name — the THIRD record source getDataConfig resolves, after data and staticData; one of the three must be present (objectui#6939)'),
+  data: ViewDataSchema.optional().describe('Data source configuration — read FIRST by getDataConfig; undeclared on either face until objectui#6939'),
   startDateField: z.string().optional().describe('Start date field'),
   endDateField: z.string().optional().describe('End date field'),
   titleField: z.string().optional().describe('Title field'),
@@ -766,10 +834,10 @@ export const ObjectGanttSchema = BaseSchema.extend({
   // The query/data keys the fetch path reads. They were declared on
   // `ObjectGridSchema` — what `ObjectGanttProps.schema` used to be typed as before
   // objectui#5903 retyped it to `ObjectGanttSchema` — so they need declaring here.
-  staticData: z.array(z.any()).optional().describe('Inline records, wrapped into a { provider: value } data config'),
+  staticData: z.array(z.any()).optional().describe('Inline records, wrapped into a { provider: value } data config — read SECOND by getDataConfig'),
   filter: z.array(z.any()).optional().describe('Query filter, forwarded verbatim as $filter'),
   sort: z.union([z.string(), z.array(SortConfigSchema)]).optional().describe('Sort configuration, forwarded as $orderby'),
-});
+}).superRefine(requireRecordSource('object-gantt'));
 
 /**
  * ObjectCalendar Schema