Reference rail count badge ignores the FK's relatedListFilter, so it disagrees with the Related tab badge on the same page

[claude]

Split out of #4664 (PR #6946), which wired the FK's relatedListFilter into the
derived related list's query AND its tab badge. The reference rail is the third
count surface on the same page and it was left alone on purpose — it cannot be
fixed on the objectui side alone.

What happens

record:reference_rail summarizes the same auto-derived child collections as
the Related tab, and renders a total-count badge per card. Its query is
fixed (packages/plugin-detail/src/renderers/record-reference-rail.tsx):

dataSource.find(entry.objectName, {
 $filter: { [entry.relationshipField]: parentId },
 $top: entry.limit ?? 3,
 $count: true,
})

So on a record page whose FK declares e.g.
relatedListFilter: { status: { $ne: 'deleted' } }, the Related tab badge
and the rail card for the same child now disagree — the tab counts the
filtered set, the rail counts every child. The rail's own preview rows are
unfiltered too, so the rail is internally consistent; the inconsistency is
between the two surfaces the same page shows at once.

The page synthesizer emits both from ONE options.related array
(buildDefaultPageSchema.ts), so they are demonstrably summarizing the same
collections.

Why it was not fixed in #4664

It is not this repo's call. ReferenceRailEntrySchema is a strictObject with
five keys (objectName, relationshipField, title, limit, displayField)
and no filter, and the shape carries an explicit guidance entry FOR that key
(quoted from @objectstack/spec 17.2.0, dist/ui/index.mjs):

The rail honours no per-entry filter: it issues one fixed query per entry
({ [relationshipField]: parentId }, $top = limit) and reads nothing else
— before this shape existed the key parsed, shipped, and silently filtered
nothing (#8691). record:related_list is the component whose filter is
real; if the rail is ever granted one, this entry shape is where it gets
declared and enforced.

Emitting a filter on a rail entry today would be refused at save (the same
shape that removed icon from rail entries in objectui#5494). So the first
move is an upstream decision on objectstack-ai/objectstack: either grant
ReferenceRailEntrySchema a filter and make the rail honour it, or rule that
the rail is deliberately an unfiltered "everything under this parent" summary
and say so where a reader of the record page can see it.

Suggested resolution shape

Two directions, for whoever triages:

1. Grant the rail a filter. Upstream spec key on
   ReferenceRailEntrySchema, then the objectui consumption half is small and
   mirrors PR feat(detail): derived related lists consume the FK's relatedListFilter — AND-composed query, badge counts the same set #6946 exactly: carry filter from the derived descriptor into
   the rail entry, and compose it with the parent scope in the rail's own
   probe. Makes all three count surfaces answer one question.
2. Rule the rail deliberately unfiltered. Then the guidance text above is
   already the whole answer and this issue closes as documentation — but the
   two-badges-disagree behaviour should be stated somewhere a page author
   reads, because it is surprising once relatedListFilter exists.

Not urgent-looking is not the same as not real: the number a user reads off the
rail is wrong relative to what the same page shows them one tab over, and the
severity of a wrong count depends on what was filtered out (soft-deleted rows,
in the driving scenario).

Where

• packages/plugin-detail/src/renderers/record-reference-rail.tsx (the fixed query)
• packages/plugin-detail/src/synth/buildDefaultPageSchema.ts (record:reference_rail entries, same options.related source)
• upstream: ReferenceRailEntrySchema in @objectstack/spec

Filed unassigned by the #4664 execution seat. No dedupe hit: a targeted issue
search for the reference rail's filter/count badge returned 0 results, with a
control query in the same session returning #4664 itself.

---

Generated by Claude Code