feat(spec): declare record:reference_rail in ComponentPropsMap — undeclared rail keys refused (#8691) (#8745)

* feat(spec): declare record:reference_rail in ComponentPropsMap — undeclared rail keys refused (#8691)

- ui/component.zod.ts: strict RecordReferenceRailProps + ReferenceRailEntrySchema,
  key set measured from the renderer's read points at the .objectui-sha pin
  (entries[]{objectName, relationshipField, title?, limit?, displayField?} +
  component-level hideEmpty); the interface's icon is read by nothing and is a
  guidance refusal, not a declared key; title is a literal string (raw React
  child), not I18nLabelSchema
- pins: spec-side (component-reference-rail.test.ts) + lint-side dispatch pin
  (validate-component-props.test.ts) reproducing the card's planted filter in
  both directions
- semantic migration entry under protocol-18 + regenerated registry
- changeset: minor + BREAKING + ADR-0087 disposition (the #8666/#8695 precedent)
- regenerated: api-surface, export-origins, docs references, strictness ledger,
  authorable-surface, json-schema.manifest

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E5tUwGM3LQoqErTfkvRW7W

* test(spec): ADR-0122 isomorphic pins for the rail schemas (Iso845/Iso846)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E5tUwGM3LQoqErTfkvRW7W

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/ui-reference-rail-unknown-keys-refused.md

@@ -0,0 +1,74 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): declare `record:reference_rail` in `ComponentPropsMap` — undeclared rail keys are refused (#8691)
+
+**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the migration prescription is
+registered under protocol major 18, where `os migrate meta` users will look).
+
+`record:reference_rail` had a registered renderer, a `PageComponentType` entry
+and a console palette slot, but no row in `ComponentPropsMap` — so the #5068
+component-props gate's dispatch skipped it as unregistered and every authored
+key rode through. Measured on 17.0.0 GA end to end: a planted entry `filter`
+passed tsc, `objectstack validate` and `objectstack build`, shipped verbatim in
+`dist/objectstack.json`, and the rendered rail kept counting and listing
+unfiltered rows — while the very same build loudly reported
+`record:related_list` keys in the same file.
+
+The new row is strict and declares exactly the shape the renderer reads
+(measured from its read points at the objectui pin, not from its TS
+interface): `entries[]` of `{ objectName, relationshipField, title?, limit?,
+displayField? }` plus a component-level `hideEmpty`.
+
+**What is refused:** any key the shape does not declare, with a prescriptive
+message — the planted `filter` (the rail issues one fixed query per entry;
+`record:related_list` is where `filter` is real), the interface's `icon` (read
+by no render path — declaring it would be declared-but-unenforced surface),
+entry-level `hideEmpty` (a component-level key), and the neighbouring-surface
+spellings `items`/`related` → `entries`, `object` → `objectName`, `label` →
+`title`. `title` is a literal `z.string()` — the renderer paints it as a raw
+React child, so an inline locale map is refused rather than shipped as
+`[object Object]`.
+
+**What stays accepted:** every declared key byte-identically. `limit` and
+`hideEmpty` carry no schema default (the renderer's `3` / `true` fallbacks stay
+the renderer's), so a minimal entry round-trips unchanged.
+
+## FROM → TO
+
+```ts
+// before — parsed green everywhere; the badge kept counting everything
+{
+  type: 'record:reference_rail',
+  properties: {
+    entries: [{
+      objectName: 'task', relationshipField: 'project_id',
+      filter: [{ field: 'status', op: 'neq', value: 'completed' }], // silent no-op
+      icon: 'CheckSquare',                                          // read by nothing
+    }],
+  },
+}
+
+// after — both keys are publish-time refusals with prescriptions; write only
+// what the renderer reads
+{
+  type: 'record:reference_rail',
+  properties: {
+    entries: [{ objectName: 'task', relationshipField: 'project_id', limit: 3 }],
+    hideEmpty: false,
+  },
+}
+```
+
+There is deliberately no automatic rewrite: an undeclared key is either a
+spelling of a declared one (the rejection names the rename) or names a
+capability the rail does not deliver — a per-entry `filter` and an inline
+`title` locale map are open capability questions for the console seat, and
+blessing either spelling now would be declared-but-unenforced surface
+(ADR-0078). `os migrate meta` surfaces the change as a structured TODO
+(semantic entry `ui-reference-rail-unknown-keys-refused`, protocol major 18 —
+this refusal is not part of the v17.0.0 cut).
+
+<!-- adr-0087: registered ui-reference-rail-unknown-keys-refused -->

content/docs/references/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Protocol Reference
-description: Every schema published by @objectstack/spec — 1577 schemas across 14 protocol modules
+description: Every schema published by @objectstack/spec — 1579 schemas across 14 protocol modules
 ---
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -32,8 +32,8 @@ counts are sums of the rows they head. Regenerate with
 | [Shared Protocol](/docs/references/shared) | 8 | 31 | Primitives used across every protocol — identifiers, HTTP, expressions, error maps, enums. |
 | [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
 | [System Protocol](/docs/references/system) | 36 | 287 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
-| [UI Protocol](/docs/references/ui) | 16 | 154 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
-| **Total** | **198** | **1577** | 14 protocol modules |
+| [UI Protocol](/docs/references/ui) | 16 | 156 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
+| **Total** | **198** | **1579** | 14 protocol modules |
 
 ---
 
@@ -364,7 +364,7 @@ The runtime environment — logging, jobs, cache, metrics, notifications, i18n a
 
 ## UI Protocol
 
-**Source:** `packages/spec/src/ui/` · **Import:** `@objectstack/spec/ui` · **16 pages, 154 schemas**
+**Source:** `packages/spec/src/ui/` · **Import:** `@objectstack/spec/ui` · **16 pages, 156 schemas**
 
 Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer.
 
@@ -375,7 +375,7 @@ Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI lay
 | [`app.zod.ts`](/docs/references/ui/app) | `ActionNavItem`, `App`, `AppBranding`, `AppContextSelector`, `ComponentNavItem`, `DashboardNavItem`, `GroupNavItem`, `NavigationArea`, `NavigationContribution`, `NavigationItem`, `ObjectNavItem`, `PageNavItem`, `ReportNavItem`, `UrlNavItem` |
 | [`bulk-action.zod.ts`](/docs/references/ui/bulk-action) | `BulkActionDef`, `BulkActionExecution`, `BulkActionOperation`, `BulkActionParam` |
 | [`chart.zod.ts`](/docs/references/ui/chart) | `ChartAggregate`, `ChartAggregateFunction`, `ChartAnnotation`, `ChartAxis`, `ChartConfig`, `ChartDrillDown`, `ChartGroupBy`, `ChartInteraction`, `ChartSeries`, `ChartType` |
-| [`component.zod.ts`](/docs/references/ui/component) | `AIChatWindowProps`, `ElementButtonProps`, `ElementFilterProps`, `ElementFormProps`, `ElementImageProps`, `ElementMetadataViewerProps`, `ElementNumberProps`, `ElementRecordPickerProps`, `ElementTextInputProps`, `ElementTextProps`, `ObjectCalendarProps`, `ObjectFormProps`, `ObjectGridProps`, `ObjectKanbanProps`, `ObjectMasterDetailFormProps`, `ObjectMetricProps`, `PageAccordionProps`, `PageCardProps`, `PageContainerProps`, `PageHeaderProps`, `PageTabsProps`, `RecordActivityProps`, `RecordChatterProps`, `RecordDetailsProps`, `RecordHighlightsField`, `RecordHighlightsProps`, `RecordPathProps`, `RecordRelatedListProps` |
+| [`component.zod.ts`](/docs/references/ui/component) | `AIChatWindowProps`, `ElementButtonProps`, `ElementFilterProps`, `ElementFormProps`, `ElementImageProps`, `ElementMetadataViewerProps`, `ElementNumberProps`, `ElementRecordPickerProps`, `ElementTextInputProps`, `ElementTextProps`, `ObjectCalendarProps`, `ObjectFormProps`, `ObjectGridProps`, `ObjectKanbanProps`, `ObjectMasterDetailFormProps`, `ObjectMetricProps`, `PageAccordionProps`, `PageCardProps`, `PageContainerProps`, `PageHeaderProps`, `PageTabsProps`, `RecordActivityProps`, `RecordChatterProps`, `RecordDetailsProps`, `RecordHighlightsField`, `RecordHighlightsProps`, `RecordPathProps`, `RecordReferenceRailProps`, `RecordRelatedListProps`, `ReferenceRailEntry` |
 | [`dashboard.zod.ts`](/docs/references/ui/dashboard) | `Dashboard`, `DashboardHeader`, `DashboardHeaderAction`, `DashboardWidget`, `DashboardWidgetOptions`, `GlobalFilter`, `GlobalFilterOptionsFrom`, `WidgetActionType`, `WidgetColorVariant` |
 | [`dataset.zod.ts`](/docs/references/ui/dataset) | `Dataset`, `DatasetDimension`, `DatasetMeasure`, `DerivedMeasureOp` |
 | [`i18n.zod.ts`](/docs/references/ui/i18n) | `AriaProps`, `I18nLabel`, `InlineLocaleMap` |

content/docs/references/ui/component.mdx

@@ -14,8 +14,8 @@ Empty Properties Schema
 ## TypeScript Usage
 
 ```typescript
-import { AIChatWindowProps, ElementButtonPropsSchema, ElementFilterPropsSchema, ElementFormPropsSchema, ElementImagePropsSchema, ElementMetadataViewerPropsSchema, ElementNumberPropsSchema, ElementRecordPickerPropsSchema, ElementTextInputPropsSchema, ElementTextPropsSchema, ObjectCalendarPropsSchema, ObjectFormPropsSchema, ObjectGridPropsSchema, ObjectKanbanPropsSchema, ObjectMasterDetailFormPropsSchema, ObjectMetricPropsSchema, PageAccordionProps, PageCardProps, PageContainerProps, PageHeaderProps, PageTabsProps, RecordActivityProps, RecordChatterProps, RecordDetailsProps, RecordHighlightsField, RecordHighlightsProps, RecordPathProps, RecordRelatedListProps } from '@objectstack/spec/ui';
-import type { ElementNumberProps, ElementRecordPickerProps, ObjectCalendarProps, ObjectFormProps, ObjectGridProps, ObjectKanbanProps, ObjectMasterDetailFormProps, ObjectMetricProps, PageContainerProps, RecordHighlightsField, RecordPathProps } from '@objectstack/spec/ui';
+import { AIChatWindowProps, ElementButtonPropsSchema, ElementFilterPropsSchema, ElementFormPropsSchema, ElementImagePropsSchema, ElementMetadataViewerPropsSchema, ElementNumberPropsSchema, ElementRecordPickerPropsSchema, ElementTextInputPropsSchema, ElementTextPropsSchema, ObjectCalendarPropsSchema, ObjectFormPropsSchema, ObjectGridPropsSchema, ObjectKanbanPropsSchema, ObjectMasterDetailFormPropsSchema, ObjectMetricPropsSchema, PageAccordionProps, PageCardProps, PageContainerProps, PageHeaderProps, PageTabsProps, RecordActivityProps, RecordChatterProps, RecordDetailsProps, RecordHighlightsField, RecordHighlightsProps, RecordPathProps, RecordReferenceRailProps, RecordRelatedListProps, ReferenceRailEntrySchema } from '@objectstack/spec/ui';
+import type { ElementNumberProps, ElementRecordPickerProps, ObjectCalendarProps, ObjectFormProps, ObjectGridProps, ObjectKanbanProps, ObjectMasterDetailFormProps, ObjectMetricProps, PageContainerProps, RecordHighlightsField, RecordPathProps, RecordReferenceRailProps, ReferenceRailEntry } from '@objectstack/spec/ui';
 
 // Validate data
 const result = AIChatWindowProps.parse(data);
@@ -573,6 +573,18 @@ Type: `string`
 | **aria** | `{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes |
 
 
+---
+
+## RecordReferenceRailProps
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **entries** | `{ objectName: string; relationshipField: string; title?: string; limit?: integer; … }[]` | ✅ | Related collections to summarize — one compact card per entry (icon-less title, total-count badge, top-N preview rows). An empty rail renders nothing, so at least one entry is required. |
+| **hideEmpty** | `boolean` | optional | Fold entries whose related count is 0 into a single "+ N empty" expander chip (renderer default: on; set `false` to always render every card). |
+
+
 ---
 
 ## RecordRelatedListProps
@@ -597,3 +609,18 @@ Type: `string`
 
 ---
 
+## ReferenceRailEntry
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **objectName** | `string` | ✅ | Related object name whose records this card summarizes (e.g. "task", "opportunity_quote") |
+| **relationshipField** | `string` | ✅ | Field on the related object that points back to this record (e.g. "account_id") |
+| **title** | `string` | optional | Literal card title. Rendered as-is in EVERY locale (no inline locale map — the rail renders it as a raw React child); omit to use the related object's localized label. |
+| **limit** | `integer` | optional | Preview rows per card, and the `$top` of the one query this entry issues (renderer default: 3). |
+| **displayField** | `string` | optional | Field of the related record rendered in each preview row (renderer fallback when omitted: name / title / subject / label / … / id). |
+
+
+---
+

docs/audits/2026-07-unknown-key-strictness-ledger.counts.md

@@ -21,7 +21,7 @@ regenerate.
 | Measure | Value |
 |---|---|
 | Triaged directories | 5 |
-| Object sites in them | 433 |
+| Object sites in them | 435 |
 | Still-open (strip) sites | 124 |
 | Files carrying at least one | 23 |
 
@@ -44,12 +44,12 @@ The `strict` column is the one the campaign schedules against; it counts both th
 
 | Dir | Sites | strict | passthrough | catchall | strip |
 |---|---|---|---|---|---|
-| `ui/` | 168 | 157 | 5 | 0 | 6 |
+| `ui/` | 170 | 159 | 5 | 0 | 6 |
 | `data/` | 153 | 70 | 1 | 0 | 82 |
 | `automation/` | 65 | 42 | 0 | 0 | 23 |
 | `security/` | 20 | 7 | 0 | 0 | 13 |
 | `studio/` | 27 | 27 | 0 | 0 | 0 |
-| **total** | **433** | **303** | **6** | **0** | **124** |
+| **total** | **435** | **305** | **6** | **0** | **124** |
 
 ## File-level triage — site counts
 
@@ -66,7 +66,7 @@ classify and is not listed (it becomes reportable the day it grows its first sit
 | `app.zod.ts` | 18 |
 | `bulk-action.zod.ts` | 3 |
 | `chart.zod.ts` | 8 |
-| `component.zod.ts` | 37 |
+| `component.zod.ts` | 39 |
 | `dashboard.zod.ts` | 11 |
 | `dataset.zod.ts` | 4 |
 | `i18n.zod.ts` | 1 |
@@ -77,7 +77,7 @@ classify and is not listed (it becomes reportable the day it grows its first sit
 | `theme.zod.ts` | 6 |
 | `view.zod.ts` | 55 |
 | `widget.zod.ts` | 1 |
-| **total** | **168** |
+| **total** | **170** |
 
 ### `data/` — sites
 
@@ -156,15 +156,15 @@ over it is here.
 
 ### `ui/` — open
 
-**6 strip of 168**, in 4 file(s).
+**6 strip of 170**, in 4 file(s).
 
 | File | Strip | Sites |
 |---|---|---|
 | `action-params.zod.ts` | 1 | 1 |
 | `app.zod.ts` | 1 | 18 |
 | `view.zod.ts` | 3 | 55 |
 | `widget.zod.ts` | 1 | 1 |
-| **total** | **6** | **168** |
+| **total** | **6** | **170** |
 
 | Bucket | Sites |
 |---|---|

packages/lint/src/validate-component-props.test.ts

@@ -616,3 +616,52 @@ describe('validateComponentProps — a STRICT union arm reports as an unknown ke
     expect(highlights([{ name: 'status', label: 'Status', readonly: true }])).toEqual([]);
   });
 });
+
+/**
+ * #8691 — the rail's row exists, so the gate's dispatch reaches it.
+ *
+ * The pre-fix state this pins against: `record:reference_rail` had no
+ * `ComponentPropsMap` row, so the walker's unregistered-type skip swallowed the
+ * whole props bag — the issue's planted `filter` produced ZERO findings from
+ * validate/build while `record:related_list` keys in the same file were loudly
+ * reported. Remove the map row and every assertion in the first test here goes
+ * back to that silence (the reverse verification the issue ran on a real app).
+ */
+describe('validateComponentProps — record:reference_rail is dispatched (#8691)', () => {
+  it('reports the issue\'s planted entry `filter`, loudly, through the same rule as its siblings', () => {
+    const findings = validateComponentProps(
+      stackWith([{
+        type: 'record:reference_rail',
+        properties: {
+          entries: [{
+            objectName: 'task',
+            relationshipField: 'project_id',
+            filter: [{ field: 'status', op: 'neq', value: 'completed' }],
+          }],
+        },
+      }]),
+    );
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(COMPONENT_PROPS_UNKNOWN_KEY);
+    expect(findings[0].where).toBe('page "probe_page" · record:reference_rail');
+    expect(findings[0].message).toContain('`filter`');
+    // The prescription names where `filter` IS real, so the author is routed
+    // to the component that delivers it rather than left with a bare refusal.
+    expect(findings[0].message).toContain('record:related_list');
+  });
+
+  it('stays silent on the shape the renderer actually reads', () => {
+    const findings = validateComponentProps(
+      stackWith([{
+        type: 'record:reference_rail',
+        properties: {
+          entries: [
+            { objectName: 'task', relationshipField: 'project_id', title: 'Tasks', limit: 3, displayField: 'subject' },
+          ],
+          hideEmpty: false,
+        },
+      }]),
+    );
+    expect(findings).toEqual([]);
+  });
+});

packages/spec/api-surface/ui.json

@@ -290,7 +290,10 @@
     "RecordHighlightsField (type)",
     "RecordHighlightsProps (const)",
     "RecordPathProps (type)",
+    "RecordReferenceRailProps (type)",
     "RecordRelatedListProps (const)",
+    "ReferenceRailEntry (type)",
+    "ReferenceRailEntrySchema (const)",
     "Report (type)",
     "ReportChart (type)",
     "ReportChartParsed (type)",

packages/spec/authorable-surface/ui.json

@@ -1007,6 +1007,8 @@
     "ui/RecordPathProps:aria",
     "ui/RecordPathProps:stages",
     "ui/RecordPathProps:statusField",
+    "ui/RecordReferenceRailProps:entries",
+    "ui/RecordReferenceRailProps:hideEmpty",
     "ui/RecordRelatedListProps:actions",
     "ui/RecordRelatedListProps:add",
     "ui/RecordRelatedListProps:aria",
@@ -1019,6 +1021,11 @@
     "ui/RecordRelatedListProps:showViewAll",
     "ui/RecordRelatedListProps:sort",
     "ui/RecordRelatedListProps:title",
+    "ui/ReferenceRailEntry:displayField",
+    "ui/ReferenceRailEntry:limit",
+    "ui/ReferenceRailEntry:objectName",
+    "ui/ReferenceRailEntry:relationshipField",
+    "ui/ReferenceRailEntry:title",
     "ui/Report:_lock",
     "ui/Report:_lockDocsUrl",
     "ui/Report:_lockReason",

packages/spec/export-origins/ui.json

@@ -290,7 +290,10 @@
     "RecordHighlightsField": "src/ui/component.zod.ts#RecordHighlightsField (type)",
     "RecordHighlightsProps": "src/ui/component.zod.ts#RecordHighlightsProps (const)",
     "RecordPathProps": "src/ui/component.zod.ts#RecordPathProps (type)",
+    "RecordReferenceRailProps": "src/ui/component.zod.ts#RecordReferenceRailProps (type)",
     "RecordRelatedListProps": "src/ui/component.zod.ts#RecordRelatedListProps (const)",
+    "ReferenceRailEntry": "src/ui/component.zod.ts#ReferenceRailEntry (type)",
+    "ReferenceRailEntrySchema": "src/ui/component.zod.ts#ReferenceRailEntrySchema (const)",
     "Report": "src/ui/report.zod.ts#Report (type)",
     "ReportChart": "src/ui/report.zod.ts#ReportChart (type)",
     "ReportChartParsed": "src/ui/report.zod.ts#ReportChartParsed (type)",

packages/spec/json-schema.manifest/ui.json

@@ -120,7 +120,9 @@
     "ui/RecordHighlightsField",
     "ui/RecordHighlightsProps",
     "ui/RecordPathProps",
+    "ui/RecordReferenceRailProps",
     "ui/RecordRelatedListProps",
+    "ui/ReferenceRailEntry",
     "ui/Report",
     "ui/ReportChart",
     "ui/ReportNavItem",