finding(plugin-list): ListViewProps.onSortChange / onFilterChange are declared any, so a documented callback example compiles without either parameter being checked

Found while paying down packages/plugin-list/README.md for objectui#5174 (batch 24). Filed, not fixed: the fix touches packages/** source and moves a public type, which that batch's licence excludes.

Notation: this body spells generic and JSX shapes out in words rather than in their angle-bracket form, because this repository has measured that GitHub's body sanitizer deletes tag-shaped fragments even inside backticks.

What was measured

packages/plugin-list/dist/ListView.d.ts declares the four callbacks the README's "With Callbacks" example passes:

onViewChange?: (view: ViewType) => void;
onFilterChange?: (filters: any) => void;
onSortChange?: (sort: any) => void;
onSearchChange?: (search: string) => void;

Before batch 24 the README block raised TS7006 (implicit any) on all four parameters, because the block never imported ListView and so had no contextual type at all. Adding a real self-import binds the element to ListViewProps and all four TS7006 go away — but they go away for two different reasons, and only two of them become real checks.

Measured directly, by assigning each parameter to a number inside the block and running pnpm check:doc-snippets:

parameter	contextual type	assigning it to a number
`view`	`ViewType`	TS2322 — checked
`search`	`string`	TS2322 — checked
`sort`	`any`	no diagnostic — not checked
`filters`	`any`	no diagnostic — not checked

So for onSortChange and onFilterChange the doc gate now reports green on a block whose parameters nothing constrains. That is honest about the gate (it compiles) and misleading as coverage (two of the four documented callbacks are unverifiable by construction).

Why this looks like an oversight rather than a decision

The ListViewProps doc comment in the same file is unusually explicit about exactly this hazard — it records objectui#4528, where a string index signature erased the whole interface and typed onRowClick as any while the interface went on declaring a real signature. The sweep that followed named each prop "at the type each one actually lands on". dataSource?: any carries its own written justification right there. onSortChange and onFilterChange carry none.

There is a plausible real type for each within the package: parseSortConfig returns SortItem[] (imported from @object-ui/components), and the filter side already has FilterGroup and the array/triplet filter AST that normalizeFilters and buildEffectiveFilter speak.

Why it is not decided here

Narrowing either one is a public-type change with a consumer sweep (ObjectView, StudioDesignSurface and the app-shell hosts pass these), so it wants its own card and its own triage. Two questions for whoever takes it:

Which shipped type is the right one for each — for sort, SortItem[] as parseSortConfig returns, or the raw declaration shape the schema carries; for filters, FilterGroup or the filter AST.
Whether the callbacks fire with the normalized value or the raw one — the answer decides question 1 and is a read of ListView's call sites, not of the declaration.

Related: objectui#4528 (the index-signature erasure this interface's comment documents), objectui#5174 (the ungated-docs burn-down this was found under).

Triage: lands in domain:ui with needs:contract-review; rationale: class (b) on the over-claim — the doc gate reports green on a block where two of the four documented callbacks are unverifiable by construction. Bug.

⭐ The measurement is a four-way discrimination on one instrument, which is why it needs no re-running: assign each parameter to a number inside the block and run check:doc-snippets —

parameter	contextual type	verdict
`view`	`ViewType`	TS2322 — checked
`search`	`string`	TS2322 — checked
`sort`	`any`	no diagnostic — not checked
`filters`	`any`	no diagnostic — not checked

⇒ Two positives beside two negatives. ⛔ Not "the gate is broken" — it compiles, honestly. The defect is that the green reads as coverage of four documented callbacks and is coverage of two.

⚠️ Worth noting because it is counter-intuitive: batch 24's self-import improved the block (four TS7006 went away) while creating this reading — two of the four TS7006 disappeared because a real type arrived, two because any arrived. ⇒ Same visible outcome, opposite meanings. ⛔ A future batch should not read "TS7006 cleared" as "parameters checked".

⭐ The "oversight, not decision" argument is strong and is what admits this under (b) rather than closing it as a missing narrowing: the ListViewProps doc comment in the same file is unusually explicit about exactly this hazard — it records objectui#4528, where a string index signature erased the interface and typed onRowClick as any while the interface went on declaring a real signature — and the sweep that followed named each prop "at the type each one actually lands on". ⇒ dataSource?: any carries its own written justification right there. onSortChange and onFilterChange carry none. The file's own convention is that an any here needs a stated reason; two lack one.

priority:p3: ⛔ nothing is broken — real consumers pass real values and the callbacks work. The cost is two published callbacks nothing constrains and a doc block that cannot fail on them.

⛔ needs:contract-review, deliberately no pm:queue: narrowing either is a public-type change with a consumer sweep — ObjectView, StudioDesignSurface and the app-shell hosts all pass these.

⚠️ But the first work item is a measurement, not a decision, and it is dispatchable now: whether the callbacks fire with the normalized value or the raw one — that is a read of ListView's call sites, ⛔ not of the declaration, and the card is right that it decides the type question. ⇒ Answer it first and the review becomes a one-line ratification instead of an open design conversation. Candidates already named: SortItem[] (what parseSortConfig returns, imported from @object-ui/components) or the raw declaration shape the schema carries; FilterGroup or the array/triplet filter AST that normalizeFilters and buildEffectiveFilter speak.

⛔ Correctly not fixed in batch 24 — that licence excludes packages/** source and moving a public type.

⛔ This seat grades and routes only: not claimed, not dispatched, no code, and ⛔ it does not pick the types.

Generated by Claude Code

分诊 —— `pm:queue`,并摘掉预挂的 `needs:contract-review`

分诊席,session session_01SwJQDFKe8tVit3BXQ9EfR5。本卡不在总监席 pm:retriage 的那十一张里,但是同一个缺陷:载体被当路由态挂上,而卡没有任何 pm:* 态 ⇒ 今天在没有任何队列里。类发现见 objectstack#16625。一并归位。

为什么可以今天就派

卡自己写了「不在这里决定」,但它列的两个问题都不是裁定,是读取——它自己就说了:「问题 2 的答案决定问题 1,而那是读 ListView 的调用点,不是读声明」。⇒ 承接者去读调用点就能收敛,不需要任何人先拍板。

承接者拿到的边界

✅ 工序是硬的:先答问题 2,再答问题 1。 先读 ListView 的调用点,确定两个回调发的是归一化后的值还是原始值;这个答案直接决定 sort 该是 SortItem[](parseSortConfig 的返回)还是 schema 携带的原始声明形状,filters 该是 FilterGroup 还是 normalizeFilters / buildEffectiveFilter 说的那套 filter AST。⛔ 不要从声明侧猜。
⚠️ 这是公开类型收紧,且卡点名了消费者面:ObjectView、StudioDesignSurface、app-shell 宿主都在传这两个回调。认领同笔记 Clause-②: yes,PR 挂载体走达档复核;消费者扫一遍是交付物的一部分,不是可选项。
⚠️ 验收判据是可执行的,照卡的量法复现:在文档块里把参数赋给 number,跑 pnpm check:doc-snippets。修好之后 sort / filters 必须像今天的 view / search 一样报 TS2322。⛔ 「编译通过」不是验收——今天它就已经通过了,而这正是本卡的内容。
⚠️ 同文件的 dataSource?: any 带着它自己写下的理由,⛔ 不要顺手一起收。本卡只动 onSortChange / onFilterChange 两个。收紧后请照该接口的既有惯例,给每个新类型补一句「为什么落在这个类型上」——finding(plugin-dashboard, plugin-list): the two packages #4422 left unswept still erase every declared prop — and the #4438 guard cannot see them #4528 的教训就写在同一个 doc comment 里。
⛔ 不要碰 finding(plugin-dashboard, plugin-list): the two packages #4422 left unswept still erase every declared prop — and the #4438 guard cannot see them #4528(索引签名擦除)与 check-doc-snippet-types.mjs collects only .mdx under content/docs — 40 .md guides are uncovered with no UNGATED_DOCS entry, contradicting its own "covered by default" rule #5174(文档欠账扫尾)的范围。

bug / plugin / priority:p3 / domain:ui / type: Bug 五项维持不变——文档门对两个回调报绿,而它约束不了它们,两个面对同一份示例给出不一致的答案,落 Bug。

⛔ 分诊席边界照旧:不认领、不派发、不写码、不合并;本笔只做状态归位。

Generated by Claude Code

Tier notice — the contract-review-tier requirement on this issue is lifted (skills seat, session session_01MoTv7pn338AZ71owsp19gQ, 2026-09-10T03:13Z; record and rule-text change in flight: objectstack-ai/objectstack#17285).

Maintainer ruling, verbatim: 「现有的卡片如果写了要求fable的，也要让相关的项目经理知道，opus就够了。」 Under the same ruling set (quoted in full on objectstack-ai/objectstack#17285), the contract-review tier is reserved for the skills seat (protocol files + the published skills/**), the spec seat's clause-② review, and the maintainer-summoned director; triage and every other seat run the default tier.

For this card: its Clause-②: yes declaration no longer calls for a contract-review-tier review. The lane seat's own default-tier review, plus the gates (widening tells, pin tests, dispatch-gates --tier), is the review of record, and the build stays at the default tier. Unchanged: the Clause-② declaration itself, the manual floor for widenings under 代裁, and the routing rule that a diff touching packages/spec goes to the spec seat, where the contract-review-tier review still applies. This comment changes no label, assignee or claim.

Generated by Claude Code

Claim: PM loop round 1
Session: session_01MPaVWWMuWeT5LgB1qoXjVB
Branch: claude/issue-8106-listview-callback-param-types
Worktree: objectui-issue-8106
Domain: domain:ui
File surface: packages/plugin-list/src/ListView.tsx (the ListViewProps declaration + the two callbacks' call sites) · packages/plugin-list/src/__tests__/ · packages/plugin-list/README.md (only if the callback example needs it) · .changeset/ (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: TIER_DEFAULT. ⚠️ dispatch-gates.mjs does not exist in objectui — gate families derived by hand and declared as such.
Clause-②: no — reported by mechanism, and the reasoning is in the ruling below rather than asserted.
Thread-read: <newest comment at claim time; the dev re-reads and reports it>
Serial constraints cleared: measured this fire — no in-flight branch touches packages/plugin-list. PR #8959 = 0 hits, lit control 3 total changed files on that branch. The two sibling cards dispatched in this wave (#8187, #8166) both land in packages/app-shell — disjoint package.

裁定 —— 收窄到回调实际触发的那个值的已发布类型

授权,逐字引用,⛔ 不译

你应该自主派发，并发保持3

⇒ 本卡此前由本席攒批呈报,现按该指令由本席裁定并派发,置于维护者的否决窗口下。

裁定内容

ListViewProps.onSortChange / onFilterChange 的参数由 any 收窄到已在本包内出货的真实类型。⛔ 不新铸类型、⛔ 不本地近似复制。

卡片提的两个问题,本席给的是判据而不是答案 —— 因为答案是读出来的,不是裁出来的:

卡片问题 2 决定问题 1。 回调触发时携带的是规范化后的值还是原始值,是对 ListView 调用点的一次读,不是对声明的读。⇒ 交付席先测调用点实际传出什么,再让声明等于那个东西。

若传出的是 parseSortConfig 的返回,则 sort 是 SortItem[](自 @object-ui/components 导入);
若传出的是 schema 携带的原始声明形状,则声明为那个形状;
filters 同理,在 FilterGroup 与 normalizeFilters / buildEffectiveFilter 所说的过滤 AST 之间,按调用点实测决定。

⛔ 两个回调各自独立判,⛔ 不假设它们对称。

理由,以及为什么这是 `Clause-②: no`

契约方向:any 不是一份「已声明的契约」,而是契约的缺席。把它换成实际流经的类型是拉回已声明契约(实现早已只发这一种值),⛔ 不是扩大接受集、⛔ 不是扩大公开面。按〈派发〉的机械边界测试,「拉回已声明契约 ⇒ 代裁车道」,不是人工地板。

该文件自己的判例:同一个接口的 doc comment 异常明确地记着这个危害 —— objectui#4528,一个字符串索引签名抹掉了整个接口、把 onRowClick 变成 any,而接口还在声明一个真实签名。随后那轮 sweep 把每个 prop 都「at the type each one actually lands on」点名过。dataSource?: any 就在那里带着自己的书面理由。onSortChange 与 onFilterChange 一条理由都没有 ⇒ 这看起来是遗漏而非决定,卡片也是这么写的。

防错轴:今天的状态是「文档示例编译通过、门禁报绿,而两个参数不受任何约束」—— 一个在门禁上看不见的空洞。四个被记录的回调里两个不可验证,而绿是按构造得到的。

⚠️ 交付席必须先证伪的三件事

消费方 sweep 是硬前提,不是收尾。 卡片点名 ObjectView、StudioDesignSurface 与 app-shell 宿主都传这两个回调。⇒ 先枚举全部消费方并逐个编译,再改声明。若任一消费方在收窄后不再编译,停手回报 —— 那说明实际流经的值与本席的判据不符,是本席的裁定错了,不是消费方错了。
回调参数的收窄是逆变的。 现有写成 (sort: any) => … 的处理函数仍然编译;会红的是在参数上做了 any 才允许的事的处理函数。这是本次收窄的真实成本,⛔ 请测量它有多大再落地,并写进 changeset 正文。
行号按默认已陈旧(卡片写于 2026-09-06),按锚点重新定位。卡片读的是 dist/ListView.d.ts,⛔ 请对源核实,并说明源与 dist 是否一致。

验收

卡片自己给了判据,照用:把每个参数赋给一个 number,跑 pnpm check:doc-snippets。收窄前 sort / filters 无诊断,收窄后必须是 TS2322 —— 而 view(ViewType)与 search(string)是同一次运行里的正控,它们现在就报 TS2322,收窄后仍应报。⇒ 这是一条能双向失败的判据,⛔ 不是「套件还是绿的」。

changeset:@object-ui/plugin-list 是已发布包且这动的是已发布类型面 ⇒ 欠一份真 changeset(⛔ 非空 frontmatter),本仓禁 major,按约定发 minor 并把收窄成本写进正文。

Generated by Claude Code

os-dev-report

{
"issue": 8106,
"status": "done",
"branch": "claude/issue-8106-listview-callback-param-types",
"pr": "#8965",
"premise_still_valid": true,
"summary": "ListViewProps.onSortChange now takes an array of SortItem and onFilterChange takes FilterGroup, both already exported by @object-ui/components and already imported by ListView.tsx; nothing new was minted. Question 2 was answered by reading the call sites, and the two are asymmetric: every sort emit crosses one boundary (emitSortChange) whose two legs are the array handed in and filterPlatformSortableSort's return, which is generic in the element and so preserves it, meaning normalized-vs-raw does not move the sort TYPE at all; filters is the toolbar FilterBuilder's own onChange value passed straight through beside a setCurrentFilters that is React state of that type, so it is the raw builder group and deliberately NOT the later query-path AST that normalizeFilters / buildEffectiveFilter speak. Two card premises were corrected, both shrinking the sweep rather than contradicting the ruling: StudioDesignSurface renders ListView but passes NEITHER callback, and ObjectDataPage carries an explicit comment that it deliberately has no such hooks. Source and dist agreed exactly before the change, so the card's dist read was faithful; line numbers had moved and everything was re-located by anchor. dataSource was not touched.",
"consumer_sweep": {
"method": "enumerated every in-repo importer of ListView from @object-ui/plugin-list, then type-checked every package containing one, BEFORE finalising the declaration",
"passes_the_callbacks": [
"packages/app-shell/src/views/ObjectView.tsx (onSortChange at 2436 and 2713, onFilterChange at 2716)",
"packages/app-shell/src/views/InterfaceListPage.tsx (onSortChange at 576)"
],
"imports_listview_but_passes_neither": [
"packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx (card named it as a consumer; it is not)",
"packages/app-shell/src/views/ObjectDataPage.tsx (explicit comment: deliberately no such hooks)",
"packages/app-shell/src/views/objectListApiDisabled-4408.test.tsx",
"packages/plugin-map/src/ObjectMap.listViewMapConfigReach.test.tsx",
"apps/console/src/tests/timelineAxisRefusalReach-7070.test.tsx"
],
"result": "4 of 4 packages type-check at exit 0: @object-ui/plugin-list, @object-ui/app-shell, @object-ui/plugin-map, @object-ui/console. No consumer stopped compiling, so the ruling's criterion held.",
"contravariance_cost": "ZERO in-repo. Every passing handler annotates its parameter explicitly as any, which stays assignable to the narrowed signature and keeps any semantics in the body. No in-repo handler was contextually typed. Cost is written into the changeset body."
},
"acceptance_probe": {
"instrument": "assign each parameter to a number inside the README 'With Callbacks' block, run pnpm check:doc-snippets; all four probes in ONE run so controls and targets are measured together",
"before": "2 diagnostics only: README:154 view TS2322 and README:155 search TS2322. sort and filters produced NO diagnostic. Measured on this branch, not quoted from the card.",
"after": "4 diagnostics: README:154 view TS2322 and README:155 search TS2322 (both controls UNCHANGED), README:156 TS2322 Type 'SortItem[]' is not assignable to type 'number', README:157 TS2322 Type 'FilterGroup' is not assignable to type 'number'.",
"mutation_proof": "README mutated under a trap with absolute paths; 4 injected markers counted by grep, blob 902c058 to 6873bb1 verified before any result was read; restored by state (blob back to 902c058, git diff HEAD empty, 0 lines). README is UNMODIFIED by this PR."
},
"two_way_mutation": {
"green": "pnpm --filter @object-ui/plugin-list type-check exit 0 with the narrowing in place",
"red": "reverting ONLY the two declarations back to any fails all four new assertions, TS2344 Type 'false' does not satisfy the constraint 'true' at ListView.propsResolution.test.ts lines 106, 109, 112, 115; exit 2",
"proof": "mutation proved on disk before reading any result: narrowed anchor count 1 to 0, any anchor count 0 to 1, blob 8f48a25 to 0435754. Restore proved BY STATE: blob back to 8f48a25, git diff HEAD empty. Both legs ran from the committed implementation (HEAD e4afc5f) under a trap using absolute paths."
},
"gates": {
"note": "scripts/pm/dispatch-gates.mjs does NOT exist in objectui, confirmed; families derived BY HAND and declared as such in the PR body.",
"build_closure_for_doc_snippets_35_pkgs_turbo": 0,
"check:doc-snippets": 0,
"check:doc-types": 0,
"check:control-bytes": 0,
"type-check @object-ui/plugin-list": 0,
"type-check @object-ui/app-shell": 0,
"type-check @object-ui/plugin-map": 0,
"type-check @object-ui/console": 0,
"vitest run packages/plugin-list/ from repo ROOT": "0 (73 files, 895 tests passed)",
"lint @object-ui/plugin-list": "0 (0 errors, 499 pre-existing warnings)",
"check-changeset-fixed": 0,
"check-changeset-no-major": 0,
"check-changeset-overwrite": 0,
"check-changeset-presence": 0,
"check-governed-queue-guard --test on changed paths": "0 - NOT GOVERNED, ordinary PR route",
"exit_code_discipline": "every exit code redirected to a file and captured before being read, never through a pipe",
"prerequisite_not_met": "@object-ui/console type-check first returned non-zero with three @object-ui/plugin-tree module-resolution errors - that package is outside the doc-gate build closure and was simply unbuilt. Labelled PREREQUISITE NOT MET, re-run after building it gives exit 0. No diagnostic in that run mentioned ListView, SortItem or FilterGroup.",
"all_gates_re_run_at_final_head": "e4afc5f95 - doc-snippets, doc-types, control-bytes re-run at the final commit, all 0"
},
"files_changed": [
"packages/plugin-list/src/ListView.tsx",
"packages/plugin-list/src/tests/ListView.propsResolution.test.ts",
".changeset/8106-listview-callback-param-types.md"
],
"changeset": "@object-ui/plugin-list minor, real frontmatter (not empty), no major; narrowing cost spelled out in the body",
"serial_constraint_rederived": "AGED. Re-measured all 8 open PRs, each with a lit control (total changed files): PR #8941 and PR #7058 now each touch packages/plugin-list, but the single hit in both is packages/plugin-list/package.json (+1/-1, a lucide-react dependency bump), disjoint from ListView.tsx. PR #8959, the one the claim measured, is still 0 hits with its lit control of 3.",
"claim_verified": "newest Claim comment is 5617510768 by os-steve, names this exact branch; Clause-2 declared 'no' by mechanism, so no needs:contract-review label was applied. Comment 5612086380 had separately lifted the contract-review tier for this card. Card body checked and NOT sanitizer-truncated. No claim of my own was left.",
"mcp_calls": "0 - all GitHub reads and writes went through repo-scoped REST on the public repo",
"deviations": [
"gate families derived by hand because scripts/pm/dispatch-gates.mjs does not exist in objectui (instructed, and declared in the PR body)",
"@object-ui/plugin-tree had to be built to get a real reading out of apps/console type-check; it is not part of the doc-gate build closure",
"PR body: on create the platform appended its own session-URL attribution footer beside the one I sent, giving two. One PATCH removed my duplicate; the platform then re-stamped the BARE footer form on that edit. Left at exactly one footer, no further edits - the footer was not re-posted in a loop. Body read back after every write: pure append, nothing deleted, all anchors intact."
],
"open_questions": [],
"out_of_scope_findings": [
"noted, not filed: the four in-repo handler sites still annotate their parameter as any ((sort: any), (filter: any)), which now shadows the contextual type this PR supplies; dropping those annotations would let the real types flow into the handler bodies. packages/app-shell source, outside this card's declared file surface, and nothing is wrong today. Successor: whoever next edits ObjectView's persistence handlers.",
"noted, not filed: the card named StudioDesignSurface as a consumer passing these callbacks; it renders ListView and passes neither. Recorded here rather than filed because it is a fact about the card's prose, not a defect in any shipped file."
]
}

Generated by Claude Code

REWORK(补丁轮已续派)— CI 红在位置轴,不在收窄本身;⛔ 未放行

派发席 domain:ui @ objectui,session_01MPaVWWMuWeT5LgB1qoXjVB,2026-09-10T11:2xZ,对 PR #8965。

红的读数,逐字

UNDECLARED FAILURE  packages/plugin-list/src/ListView.tsx:830 ListViewHandle
  [semantic]  :830:17  TS2686: 'React' refers to a UMD global, but the current file is a module.
  [semantic]  :831:2   TS2304: Cannot find name 'ListView'.
  [semantic]  :831:33  TS2304: Cannot find name 'schema'.
STALE LEDGER ROW  packages/plugin-list/src/ListView.tsx:808 ListViewHandle
  no such example in the scan set
Examples: 124 block(s) — 35 compile, 89 fail, 88 of those declared in the ledger (89 row(s)).

诊断:行号键的台账行漂了,⛔ 不是收窄写错了

ListViewHandle 上的 @example 块本来就是一个已知、已被接受的失败,而它的台账键内嵌行号。本 PR 在其上方净增约 24 行 ⇒ 块从 :808 移到 :830:台账行不再匹配任何块(stale),块本身又以未声明身份重新出现。89 行、88 匹配 ⇒ 恰好一行漂了,这与"一处位移"完全自洽。那三条诊断就是 :808 时已被接受的同三条。

⇒ 补丁轮只做一件事:按锚点把那一个键的行号改对,⛔ 不新增行、⛔ 不删行、⛔ 不动该行的 card/codes/reason、⛔ 不去"修好"那个例子(它是刻意被记为失败的)。

⚠️ 这道门没跑,而我的派发令也没点它

交付席手工推导的门族里有 check:doc-snippets 与 check:doc-types,没有 @example 块那道门(check-doc-example-types.mjs)。而本席的派发令同样没有点名它 —— 我列了 doc-snippets 与 doc-types,漏了正是"改动源文件导致 docblock 例子位移"这一类唯一能抓到的那道门。⇒ 这一半是本席的门族推导不全,记在这里而不是记成交付席的失误。

⭐ 更该记的是:同一类今天已经咬过一次 —— objectui#8885 / PR #8895 的 UNGATED_EXAMPLES 键同样内嵌行号,而跨文件行号引用普查看不见它,唯一能抓的就是那道门本身。⇒ 这是复发,不是新奇事,应当进车道事实。

⛔ 本轮不放行,且⛔ 不重投

红的是真缺陷(本 PR 造成的位置漂移),⛔ 不是 flake、⛔ 不是"按设计而红" ⇒ 三条带红入队的条件一条都不成立。重投毫无意义:同一棵树会同样红。

⚠️ 门禁尚未收敛(Type Check、Lint、四个 shard 仍 in_progress),补丁推上去后整轮重跑,届时按每一个 check 全绿复核。

✅ 本轮其余部分已验收,⛔ 不必重做

消费方 sweep 作为前提执行:枚举全部 in-repo 引用方,4/4 包 type-check exit 0,无一因收窄而编译失败 ⇒ 裁定的判据成立。
两条卡片前提被更正,且都是让 sweep 变小:StudioDesignSurface 渲染 ListView 但两个回调都不传(卡片把它列为消费方,错了);ObjectDataPage 带明确注释说它刻意没有这些钩子。
问题 2 由读调用点作答,且两者不对称(正是派发令要求的"各自独立判"):sort 每次发射都过 emitSortChange,其两条腿是传入的数组与 filterPlatformSortableSort 的返回,而后者在元素上是泛型、保留元素类型 ⇒ 规范化与否根本不移动 sort 的类型;filters 是工具栏 FilterBuilder 自己的 onChange 值直传,旁边就是同类型的 React state ⇒ 是原始 builder group,刻意不是后段查询路径的 AST。
逆变成本 in-repo 为零:四个传参处都显式标注 any,仍可赋给收窄后的签名。成本已写进 changeset 正文。
验收探针四条一次跑完:改前只有 2 条诊断(两个正控),改后 4 条,两个正控逐字不变 ⇒ 双向可失败。

声明面读数本席已自核:main 上 onFilterChange?: (filters: any) / onSortChange?: (sort: any),分支上 (filters: FilterGroup) / (sort: SortItem[]);dataSource 未被触碰。

Generated by Claude Code

@example

os-dev-report

{
"issue": 8106,
"status": "done",
"round": "patch round 1 - CI red on Doc Snippet Type Check, position axis",
"branch": "claude/issue-8106-listview-callback-param-types",
"pr": "#8965",
"head": "14f809720",
"premise_still_valid": true,
"summary": "The red was positional, not a defect in the narrowing, and is now fixed by re-keying exactly one ledger row. UNGATED_EXAMPLES in scripts/check-doc-example-types.mjs keys each accepted @example failure by a string embedding the line number of the block. The @example on ListViewHandle was already an accepted failure at 808; the declaration change added lines above it, moving the tag to 830, so the row went stale and the block re-appeared as undeclared with the same three diagnostics [2304, 2686] already accepted at 808. Reproduced locally first, fixed by anchor, verified by positive control and by a base-vs-branch key-list diff. Round 1 findings were not redone or altered.",
"root_cause_class": "line-number-embedding ledger key. Confirmed a repeat, not a novelty: same class as objectui#8885 / PR #8895. The cross-file citation census cannot see these keys; only the gate itself catches them.",
"fix": {
"file": "scripts/check-doc-example-types.mjs",
"change": "one line: the ledger key 'packages/plugin-list/src/ListView.tsx:808 ListViewHandle' becomes '...:830 ListViewHandle'",
"untouched": "that row's card, codes and reason; no row added, none deleted; the @example itself left deliberately failing",
"located_by": "ANCHOR - the @example tag on the ListViewHandle doc comment - not by arithmetic and not by trusting the :830 the gate printed. Confirmed by content on branch (tag at 830) and against base 72bcd77 (same tag at 808), which also establishes that the gate keys the @example tag line rather than the fence or the declaration.",
"arithmetic_would_have_been_wrong": "the file gained 24 net lines while the block moved 22"
},
"before_state_reproduced_locally": {
"exit": 1,
"undeclared": "packages/plugin-list/src/ListView.tsx:830 ListViewHandle, codes [2304, 2686]",
"stale": "packages/plugin-list/src/ListView.tsx:808 ListViewHandle",
"census": "Examples: 124 block(s) - 35 compile, 89 fail, 88 of those declared in the ledger (89 row(s))"
},
"positive_control_after_fix": {
"exit": 0,
"stale_rows": 0,
"undeclared_failures": 0,
"row_count": 89,
"row_count_unchanged": true,
"census": "Examples: 124 block(s) - 35 compile, 89 fail, 89 of those declared in the ledger (89 row(s))",
"verdict_line": "Every covered @example compiles, or fails exactly as its ledger row declares."
},
"key_list_diff_base_vs_branch": {
"method": "extracted every ledger key from scripts/check-doc-example-types.mjs at base 72bcd77 and at branch HEAD, then diffed the two lists",
"rows_base": 89,
"rows_branch": 89,
"diff": "51c51\n< packages/plugin-list/src/ListView.tsx:808 ListViewHandle\n---\n> packages/plugin-list/src/ListView.tsx:830 ListViewHandle",
"lines_differing": 1,
"result": "EXACTLY ONE row differs, and only in its line number - no row added, removed or otherwise re-keyed"
},
"gates": {
"check:doc-examples (the gate my hand-derived family OMITTED)": "0 - added to the family; first run exited 2 on an unbuilt dist, labelled PREREQUISITE NOT MET, re-run to a real 0 after building the closure the gate itself names",
"check:doc-examples (before the fix, built tree)": "1 - the CI failure, reproduced locally",
"scripts/tests/check-doc-example-types.test.ts + check-doc-example-shared-reader.test.ts": "0 - 2 files, 80 tests; owed because the diff now edits a gate script",
"check:doc-snippets": 0,
"check:doc-types": 0,
"check:control-bytes": 0,
"check-changeset-presence": "0 - scripts/ is not published source, so the existing single changeset still satisfies it (4 files changed, 2 of them published source, 1 changeset)",
"check-governed-queue-guard --test scripts/check-doc-example-types.mjs": "0 - NOT GOVERNED, ordinary PR route",
"build closure (35 packages, turbo)": 0,
"exit_code_discipline": "every exit code redirected to a file and captured before being read, never through a pipe",
"round_1_gates": "not re-run and not altered; all were green at e4afc5f and that commit is unchanged"
},
"files_changed": [
"packages/plugin-list/src/ListView.tsx",
"packages/plugin-list/src/tests/ListView.propsResolution.test.ts",
".changeset/8106-listview-callback-param-types.md",
"scripts/check-doc-example-types.mjs"
],
"serial_constraint_rederived_again": {
"open_prs_now": 12,
"note": "4 PRs opened since round 1; #8959 and #8947 are gone from the open set",
"packages/plugin-list": "only #8941 and #7058, and in both the single hit is the same one line of packages/plugin-list/package.json (lucide-react dependency bump), disjoint from ListView.tsx",
"scripts/check-doc-example-types.mjs": "0 hits across all 11 other open PRs, each with its lit control (total changed files: 6, 5, 8, 5, 4, 1, 38, 2, 2, 23, 100). This is the surface that matters this round - a sibling editing the same ledger would collide directly.",
"upstream_drift": "origin/main advanced 2 commits (72bcd77 to 2c208d5); neither touched ListView.tsx nor the ledger, so the base-vs-branch key-list diff stands and the fix applies cleanly"
},
"mcp_calls": "0 - all GitHub reads and writes went through repo-scoped REST on the public repo, this round included",
"deviations": [
"the worktree had been removed at the end of round 1 per the cleanup rule, so it was re-created on the pushed branch at e4afc5f and re-installed before this round",
"PR body PATCH: the platform re-stamped the bare attribution footer, as it did in round 1. Read back after the write: pure append, nothing deleted, all anchors intact, still draft, exactly one footer. The footer was not re-posted in a loop."
],
"not_redone": "consumer sweep, the two corrected card premises, the asymmetric call-site read, the zero in-repo contravariance cost and the four-probe acceptance run all stand from round 1 as accepted; commit e4afc5f is untouched",
"open_questions": [],
"out_of_scope_findings": [
"noted, not filed: the four in-repo handler sites still annotate their parameter as any ((sort: any), (filter: any)), which now shadows the contextual type this PR supplies. packages/app-shell source, outside this card's declared file surface, nothing wrong today. Successor: whoever next edits ObjectView's persistence handlers.",
"noted, not filed: the card named StudioDesignSurface as a consumer passing these callbacks; it renders ListView and passes neither.",
"noted, not filed: UNGATED_EXAMPLES keys embed a line number, so any diff that adds or removes lines above a ledgered @example silently invalidates its row, and nothing but check:doc-examples can see it - it bit objectui#8885 / PR #8895 and this card on the same day. A key anchored to the symbol name rather than the line would remove the class. Not filed because it is a design change to a gate that a card would have to rule on, not a defect in a shipped file; the coordinator already holds both instances."
]
}

Generated by Claude Code

ACCEPT — 补丁轮通过,PR #8965 翻 ready + auto-merge

派发席 domain:ui @ objectui,session_01MPaVWWMuWeT5LgB1qoXjVB,2026-09-10T11:5xZ,对 head 14f809720。

红已消,且消在正确的位置

Doc Snippet Type Check 11:36:44Z success(前一轮同一门 failure)· Type Check 11:39:07Z · Lint 11:37:54Z · Test (shard 1..4/4) 11:46–11:49Z 全 success · Governed Surface Queue Guard success。⇒ 33 个 check 全绿或按设计 skipped,零红零 pending。

⭐ 补丁轮里最该记的一条:算术会给出错误答案

交付席按锚点重新定位,并顺手量出了这条:

文件净增 24 行,而那个块只移动了 22 行。

⇒ 按 hunk delta 做算术会键到 :832,仍然是坏的。⛔「按锚点、不按算术」在这张卡上不是形式主义,它是唯一能得到正确答案的方法 —— 而这一点是可测的,不是可辩的。

⚠️ 同一次测量还确立了一条新的平台事实:该门键的是 @example 标签行,不是 fence、不是声明行 —— 由同一锚点在 base 72bcd7783(:808)与分支(:830)两侧的位置比对确立,与两个键恰好对上。

验证是正控式的,⛔ 不是"绿了"

修后:0 stale row、0 undeclared failure、89 行不变,门自己的判词是 Every covered @example compiles, or fails exactly as its ledger row declares.;base↔branch 键表 diff 恰好一行不同,且只差行号:

51c51
< packages/plugin-list/src/ListView.tsx:808 ListViewHandle
---
> packages/plugin-list/src/ListView.tsx:830 ListViewHandle

⇒ 无行新增、无行删除、无行被重键。

交付席补上了我漏的那道门 —— 并且多补了一道

它把 check:doc-examples 加进门族(本席派发令漏点的那道),并额外跑了该门脚本自己的测试(check-doc-example-types.test.ts + check-doc-example-shared-reader.test.ts,80 项)—— 理由是 diff 现在改到了一个 gate 脚本。那是它想到而本席没写进派发令的,记一笔。

串行约束第三次重测

12 个 open PR 逐个带点亮对照(总改动文件数 6/5/8/5/4/1/38/2/2/23/100)。关键面 scripts/check-doc-example-types.mjs:11 个其它 open PR 全部 0 命中 —— 这才是本轮真正要紧的面,一个兄弟卡编辑同一台账会直接撞车。packages/plugin-list 只有 #8941 / #7058 各一处 package.json 的 lucide bump,与 ListView.tsx 不交。

本卡的类已单独立卡

objectui#8969(未打标签,交分诊)—— UNGATED_EXAMPLES 的键内嵌行号,任何在被记录 @example 之上增删行的 diff 都会静默作废其行,而除这道门外没有任何仪器看得见(跨文件行号普查读的是散文里的 path:line)。今天两次独立实例:objectui#8885 / PR #8895 与本卡。⛔ 该卡不裁"改成按符号名键" —— 那是对台账格式的设计变更,需处理同符号双 @example 并迁移全部 89 行,归分诊与裁决。

⇒ 跟到 MERGED 为止。⚠️ 本卡带 Fixes,而 Fixes 自动关卡不摘 pm:*、不清 assignee(今日三次实测),落地后本席显式清理。

Generated by Claude Code

✅ 已落地 — PR #8965 MERGED;半状态在本笔清掉(今日第四次)

派发席 domain:ui @ objectui,session_01MPaVWWMuWeT5LgB1qoXjVB,2026-09-10T12:1xZ。origin/main = fb828773d,队列已清空。

落地核验 —— 按内容,两个主体反向移动

腿	合并前	现在
主体+ `onSortChange?: (sort: SortItem[])`	0	1
主体− `onSortChange?: (sort: any)`	1	0
正控 `ListView.tsx` 存在	YES	YES
负控 `zzzNoSuchListFile.tsx`	NO	NO

⇒ 两个主体腿反向同时移动,正控稳、负控死 ⇒ 真实状态转移,⛔ 不是探针漂了。

半状态:今日第四次

objectui#8912(10:15Z)· #8903(10:43Z)· #8853(11:11Z)· 本卡(12:1xZ)。四次全同 ⇒ Fixes 自动关卡从不摘 pm:*、从不清 assignee。已清:pm:dispatched 摘除、assignee 清空;bug / plugin / priority:p3 / domain:ui 保留。

本卡实际交付的东西

ListViewProps.onSortChange / onFilterChange 由 any 收窄到已在本包内出货的真实类型 —— 而哪个类型是读出来的,不是裁出来的:

sort → SortItem[]。每次发射都过 emitSortChange,其两条腿是传入的数组与 filterPlatformSortableSort 的返回,而后者在元素上是泛型、保留元素类型 ⇒ 「规范化还是原始」根本不移动 sort 的类型。
filters → FilterGroup。是工具栏 FilterBuilder 自己的 onChange 值直传,旁边就是同类型的 React state ⇒ 原始 builder group,刻意不是后段 normalizeFilters / buildEffectiveFilter 说的查询 AST。

⇒ 两者不对称,而这正是派发令要求「各自独立判、⛔ 不假设对称」的原因。

消费方 sweep 作为前提跑完:4/4 包 type-check exit 0,无一因收窄而编译失败 ⇒ 裁定判据成立。逆变成本 in-repo 为零(四个传参处都显式标注 any,仍可赋值),已写进 changeset 正文。

⭐ 并且它更正了卡片两条前提,都是让 sweep 变小:StudioDesignSurface 渲染 ListView 但两个回调都不传(卡片把它列为消费方,错了);ObjectDataPage 带明确注释说它刻意没有这些钩子。

那道红,以及它留下的东西

本卡在补丁轮前红在 Doc Snippet Type Check —— 位置轴,不是收窄写错:ListViewHandle 的 @example 块是已被接受的失败,而台账键内嵌行号,本 diff 在其上方增行使它由 :808 漂到 :830。

⭐ 修复时量出的这条值得留在卡上:文件净增 24 行,块只移动 22 行 ⇒ 按 hunk delta 做算术会键到 :832、仍然是坏的。「按锚点、⛔ 不按算术」在这里是可测的,不是可辩的。

该类已单独立卡 objectui#8969(两次独立实例:本卡与 objectui#8885 / PR #8895)。⚠️ 而 check:doc-examples 缺席于门族是本席派发令的漏,已记在案并进了后续所有派发令。

Generated by Claude Code

finding(plugin-list): ListViewProps.onSortChange / onFilterChange are declared any, so a documented callback example compiles without either parameter being checked #8106

Description

What was measured

Why this looks like an oversight rather than a decision

Why it is not decided here

Activity

os-zhuang commented on Sep 7, 2026

os-zhuang commented on Sep 7, 2026

分诊 —— pm:queue,并摘掉预挂的 needs:contract-review

为什么可以今天就派

承接者拿到的边界

os-justin commented on Sep 10, 2026

os-steve commented on Sep 10, 2026

裁定 —— 收窄到回调实际触发的那个值的已发布类型

授权,逐字引用,⛔ 不译

裁定内容

理由,以及为什么这是 Clause-②: no

⚠️ 交付席必须先证伪的三件事

验收

claude commented on Sep 10, 2026

os-steve commented on Sep 10, 2026

REWORK(补丁轮已续派)— CI 红在位置轴,不在收窄本身;⛔ 未放行

红的读数,逐字

诊断:行号键的台账行漂了,⛔ 不是收窄写错了

⚠️ 这道门没跑,而我的派发令也没点它

⛔ 本轮不放行,且⛔ 不重投

✅ 本轮其余部分已验收,⛔ 不必重做

claude commented on Sep 10, 2026

os-steve commented on Sep 10, 2026

ACCEPT — 补丁轮通过,PR #8965 翻 ready + auto-merge

红已消,且消在正确的位置

⭐ 补丁轮里最该记的一条:算术会给出错误答案

验证是正控式的,⛔ 不是"绿了"

交付席补上了我漏的那道门 —— 并且多补了一道

串行约束第三次重测

本卡的类已单独立卡

os-steve commented on Sep 10, 2026

✅ 已落地 — PR #8965 MERGED;半状态在本笔清掉(今日第四次)

落地核验 —— 按内容,两个主体反向移动

半状态:今日第四次

本卡实际交付的东西

那道红,以及它留下的东西

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

finding(plugin-list): `ListViewProps.onSortChange` / `onFilterChange` are declared `any`, so a documented callback example compiles without either parameter being checked #8106

分诊 —— `pm:queue`,并摘掉预挂的 `needs:contract-review`

理由,以及为什么这是 `Clause-②: no`