Repository navigation
feat(spec): no declarative filter for auto-derived related lists — add field-level relatedListFilter so soft-deleted child rows can be excluded without abandoning the auto record page #8704
Description
Reported from a downstream re-test batch of platform-capability gaps in Titanwind EHR (private repo: steedos-labs/os-project-titanwind-ehr#1071, gap ③). All facts below are from @objectstack/* 17.0.0 and are self-contained — the downstream links are for provenance only.
Current state (17.0.0)
The field-level related-list surface in @objectstack/spec consists of exactly three keys — relatedList, relatedListTitle, relatedListColumns (spec/src/data/field.zod.ts:788-792). There is no filter dimension at all.
Consequently, the related-list descriptors that RecordDetailView auto-derives for a record page carry only childObject / childLabel / referenceField / isOwned / isPrimary (plus the title/columns overrides above), and the list query is issued directly as { [referenceField]: parentId } — every child row pointing at the parent is shown, unconditionally.
Scenario that breaks
A child object implements soft deletion (e.g. status = 'deleted'). After a user "deletes" a child record:
- the parent's record page still shows the deleted row in the related list, unchanged;
- the related-list tab badge count does not decrease;
- the child object's own list-view filters do not apply to related lists, so there is no declarative way to hide the row anywhere on the auto-derived record page.
Current workaround and its cost
The only way to filter a related list today is to replace the entire page with a hand-written page using the record:related_list component, which does accept a filter input (wired up in objectstack-ai/objectui#3981, from #7118). That works, but the cost is giving up the auto-derived record page for that object — every other related list, layout, and future platform improvement on that page now has to be maintained by hand, to express one filter condition.
Note #7118 is the component-level read point; this issue is the missing declaration-level counterpart, so the auto-derived page can express the same thing.
Request
Add a field-level relatedListFilter key (or an equivalent related-list default-filter declaration) to the spec, and have the auto-derived related lists consume it:
- semantics: AND-composed with the parent-relationship condition
{ [referenceField]: parentId }— an authored constraint, not a user-editable suggestion; - the tab badge count should honor the same filter, so counts match the visible rows.
Naming/placement is the platform's call — the capability gap is "a declared filter that auto-derived related lists respect".
Activity
hotlong commentedon Aug 14, 2026
Triage: lands in
packages/spec(field-level related-list declaration) with a consuming half in objectui'sRecordDetailViewderivation. Routeddomain:spec, typeFeature,needs-user-decision.Why the decision box and not the queue: adding an authorable key widens the accept surface of the spec, which is the maintainer's floor (feature/contract-shape class) — not a triage-adjudicable card, however well-evidenced. Contract-first also means this cannot be one dispatch: the spec key lands here first, and the objectui consumption half follows as a
Blocked-by:-linked card once the shape is ruled.One thing the ruling should weigh, surfaced by the routing read. The motivating scenario is a child object that implements soft deletion in userland (
status = 'deleted'). The platform declares soft deletion and does not implement it: #3146 recordsenable.trash/softDeleteas spec-only with zero runtime readers (status:parked). So the measured pull here may be evidence for two different features, and they are not equivalent:relatedListFilteris the more general capability and serves cases soft delete never will — but it is also a general filter surface on a declaration, which is a permanent obligation with its own semantics to pin (AND-composition, badge-count parity, and what happens when the filter names a field the child object later drops).Neither displaces the other automatically; the point is that ruling this card without looking at #3146 risks paying for a general filter mechanism to work around a specific capability the platform already claims to have.
Four-facet card face
relatedList/relatedListTitle/relatedListColumnsatspec/src/data/field.zod.ts:788-792), which is a coherent place for it, and it closes a real asymmetry: therecord:related_listcomponent acceptsfilter(objectui#3981, from record:related_list.filter 声明了却无人读:RelatedList 的列表查询只按父关系过滤,作者写的 filter(以及 dataSource 合成出的 filter)整条丢弃 #7118) while the declaration that auto-derives that component cannot express the same thing. Against: a filter on a declaration needs its composition semantics pinned, or the two paths drift into a second dialect.@objectstack/*17.0.0, with the workaround's cost stated concretely (abandon the auto-derived record page — and with it every future platform improvement to that page — to express one filter condition). This is pull for the capability; it is not by itself pull for this particular spelling.PM recommendation (offered, not decided): rule the #3146 question first, since it may dissolve the motivating case at lower total cost; if
relatedListFilteris then still wanted, admit it in its narrowest form with badge-count parity written into the contract as a pin, not left to the consumer. Naming and placement are the platform's call, as the reporter notes.Not a claim. Dispatch tier when it is ruled and queued:
claude-fable-5(mandatory — this changes the contract's accept surface).Generated by Claude Code
os-zhuang commentedon Aug 15, 2026
Maintainer ruling (2026-08-15, verbatim: 「接受全部建议。」, item 3 of the five-item list posted in the live PM session) — the capability is accepted, under four conditions recorded as binding:
whereon a virtual formula field returns 0 rows silently, while sort and search refuse the same field with a 400 #8296/The FILTER-axis formula refusal (#8296) shipped without the ADR-0087 semantic entry its SORT-axis twin (#7095) carries — the upgrade guide will not mention it #8370) apply to it automatically.{ [referenceField]: parentId }, never a user-editable suggestion; the tab badge count honors the same filter.relatedListFilterkey joining the existing three-key family atpackages/spec/src/data/field.zod.ts:788(relatedList/relatedListTitle/relatedListColumns). The objectui consumption half (RecordDetailView's auto-derived descriptors + badge) is filed separately withBlocked-by:this card — companion card follows this comment.needs-user-decision→pm:queuein the same stroke. Queue position under SERIAL mode: third, after #8762 (Bug) and #8715 (retirement).Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
Claim: PM loop round 5 (spec seat; batch-3 posture)
Session:
session_01Fgvh1iEJfxetei7aNVdtJtBranch:
claude/issue-8704-related-list-filterWorktree:
objectstack-issue-8704Domain:
domain:specFile surface (region-level):
packages/spec/src/data/field.zod.ts(the three-key related-list family at ~:788 gainsrelatedListFilter), its tests, regenerated reference docs + authorable-surface/api-surface shards, changeset (stop on breach; explain in the report). ⛔ The objectui consumption half (RecordDetailView derivation + badge) is a separateBlocked-by:card — NOT this dispatch.Container & model: M,
mode:subagent,model: claude-fable-5— mandatory tier: widens the contract accept surfaceSerial constraints cleared: in-flight #8876 (
data/driver/common.zod.ts) — disjoint source files; #8936 in merge queue (filter-dotted-head+ doors) — disjoint; shared generated surfaces under the four waiver disciplines (mergemainbefore PR, re-merge after any sibling lands, os-regen relay if registry is somehow touched — not expected for a pure widening); no #8641 trigger-file intersection.Ruling being implemented (maintainer 2026-08-15 「接受全部建议。」 item 3, comment
5299772379, four binding conditions): ① reuse the existing declarative filter schema — ⛔ no new filter dialect, the declared filter flows through the same validation doors (the FILTER-axis refusals #8296/#8370/#8935/#8936 apply automatically); ② semantics: authored constraint AND-composed with{ [referenceField]: parentId }, never user-editable; badge-count parity written into the contract as a pin, not left to the consumer; ③ spec half only (contract-first); ④ 17.x minor, ordinary changeset, no BREAKING annotation.Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
{ "issue": 8704, "status": "done", "branch": "claude/issue-8704-related-list-filter", "pr": "https://github.com/objectstack-ai/objectstack/pull/8955", "premise_still_valid": true, "summary": "Spec half implemented per the four-condition ruling: `relatedListFilter: FilterConditionSchema.optional()` joins the three-key family at packages/spec/src/data/field.zod.ts, with the AND-composition (`{ [referenceField]: parentId }`), never-user-editable, and badge-count-parity clauses written as normative contract text and pinned. Dialect measured, not assumed: FilterConditionSchema chosen over the component's ViewFilterRuleSchema[] because the #8793/#8935 preset door lives in its superRefine (pinned at the new position with zero new wiring) and the in-file precedent summaryOperations.filter already carries identical AND-with-parent-FK semantics; #8296/#8371(#8936, landed and merged under this branch) are field-typed runtime doors the composed query reaches by construction — door placement pinned. The auto-derivation contract is measured wholly objectui-side (deriveRelatedLists/RecordDetailView), so badge parity lands as normative prose + contract-text pin here and behavioural enforcement in the companion card, said explicitly in the PR body. Lint: FILTER_KEYS gains relatedListFilter (the walk recognises filter positions by key and would miss the new one), extending tokens/empty-combinators/preset-comparands at once, with position pins. Liveness: `planned` + authorWarn (the #4848 shape — an author who sets it today IS misled), flip-to-live instruction cites objectui#4664. 17.x minor changeset (spec minor, lint minor), no BREAKING, no ADR-0087 entry (pure widening, registry untouched — verified absent from the diff). Companion objectui card FOUND: objectstack-ai/objectui#4664 (already filed, open) — PM can wire Blocked-by. Existing three keys measured NOT schema-gated to lookup/master_detail; fourth gated identically. skip-changeset label not applicable (real changesets present).", "tests": "Union at head 3bc19f0 (quoted from the run): spec 406 files / 10725 tests passed + typecheck green; lint 73 files / 2047 passed + typecheck green; check:generated all 13 artifact gates green (authorable-surface carries data/Field:relatedListFilter; docs regenerated). Consumer suites: metadata 603, metadata-protocol 1512, metadata-core 162, metadata-fs 51 — all passed; examples validate x3 exit 0. Gates re-derived via scripts/pm/dispatch-gates.mjs on the actual 9 changed paths: 15 path gates + convention gates (query-options-erasure, type-check-coverage, type-check-debt --re-measure on the built closure) + check:nul-bytes all PASS; derivation added only docs/changeset path gates beyond the prompt's named families, all green. No ablation in this card, so no dist-rebuild claim is applicable. CI at report time: in_progress (report-at-draft-time per contract).", "open_questions": [], "out_of_scope_findings": [] }Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
ACCEPT — PR #8955 (
Fixes #8704, spec half), reviewed by the spec seat (sessionsession_01Fgvh1iEJfxetei7aNVdtJt) against the diff and CI:FilterConditionSchemareused (decisive in-file precedent:summaryOperations.filteralready carries identical AND-with-parent-FK semantics; the Refuse the declared relative-date preset vocabulary as a bare temporal comparand at publish time — the ruled C half of #8690, carved out for the spec seat #8793/feat(spec,lint): refuse a bare date-range preset name in an ordering filter comparand at publish time (#8793) #8935 preset door comes free via itssuperRefineand is pinned AT the new position; the The FILTER axis has no unmaterializable verdict: awhereon a virtual formula field returns 0 rows silently, while sort and search refuse the same field with a 400 #8296/[finding] The FILTER axis has no DOTTED-path verdict —where: { project_id.name: 'x' }rides its head segment past both doors, where SORT refuses the same spelling (#4256) #8371 field-typed doors are runtime doors the composed query reaches by construction — door placement pinned so a blind schema-side refusal can't creep in); ② AND-composition + never-user-editable + badge-count parity written as normative contract text with a contract-text pin — and the honest boundary stated: the auto-derivation contract is wholly objectui-side, so behavioural parity enforcement lands with the companion card's acceptance criteria; ③ objectui untouched, companion objectui#4664 confirmed filed; ④ 17.x minor, no BREAKING, registry verified absent from the diff.planned+authorWarn(the [决策] SDUI 深链「导航即运行动作」（?runAction=<actionName>）要不要升格为 spec 声明的正式契约 #4848 shape — an author who sets the key today IS misled until the consumer lands; flip-to-live instruction cites objectui#4664), and the lintFILTER_KEYSaddition closes the walk gap class-wide (the first family member not spelledfilterwould otherwise be invisible to all three walking rules) with position pins.3bc19f0: all 29 check-run jobs green.Marking ready + auto-merge. Generated surfaces are disjoint from the in-queue #8956 (authorable-surface/field.mdx/liveness vs api-surface/export-origins) — no relay needed between them. On MERGE: unlock note to objectui#4664.
Generated by Claude Code
feat(spec): field-level relatedListFilter — declarative default filte…
docs(spec): pin the derived related-list sort-inheritance rule in rel…
docs(spec): pin the derived related-list sort-inheritance rule in rel…