finding(docs): `docs/ARCHITECTURE.md` teaches a six-method `DataSource` interface that no package exports and `ObjectView` would reject — the examples type-check only because two `any`s launder the value

[baozhoutao]

Filed by the domain:devx @ objectui execution seat (PM session session_01FhBNJcLRZLe8M87VcUgpKr, R46, 2026-09-06T21:36Z) from the census objectui#7856 card 1 took while bringing docs/*.md into the doc-snippet walk (PR #8158, head f011733bf). This is a proposal that PR deliberately did NOT act on — the gate structurally cannot see it, and repairing it means deciding what the page should teach, which is not a typed-binding job.

What the page says

docs/ARCHITECTURE.md, section "Custom Data Source Interface" (the interface DataSource fence, ~line 240 on f011733bf), documents a six-method interface (find, findOne, create, update, delete, getObjectSchema-less) and says third-party systems implement it to plug into the console. Examples 1–3 on the same page pass such an object to DataSourceProvider and read it back with useDataSource() into ObjectView.

What the tree says (measured on f011733bf, through the gate's own compileSnippets)

• Annotate a stand-in with the page's verbatim interface and pass it to ObjectView: TS2741: Property 'getObjectSchema' is missing in type 'DataSource' but required in type 'DataSource(OPT)'.
• @object-ui/types exports a much larger DataSource; @object-ui/app-shell holds a near-identical private copy and does not export it. No package exports the shape the page documents.
• The page's examples compile only because DataSourceProviderProps.dataSource is declared any and useDataSource() returns any — the value is laundered between the provider and the renderer, so the page's central claim is unchecked end to end by construction. PR feat(gate): bring the root docs/*.md pages into the doc-snippet walk #8158's stand-ins record this honestly in a fence comment ("the annotation records where the value goes rather than checking it").

Why it is a finding and not a repair rider

The correct fix is a decision: either the page teaches the real exported DataSource from @object-ui/types (and says which methods a minimal adapter must implement), or a minimal-adapter contract is exported and the page names it. Both change what a reader is told to build. Adjacent cards on the any root cause: objectui#7912 (SchemaRendererProvider's dataSource prop typed any) and objectui#7483 (ObjectView's props surface typed any). This card is the documentation face of the same seam and should be routed together with them; it does not duplicate either.

Verification recipe

git fetch origin main
git show origin/main:docs/ARCHITECTURE.md | sed -n '/^interface DataSource/,/^}/p'
git grep -n "export interface DataSource\b" origin/main -- packages/types/src packages/app-shell/src

Refs objectui#7856, PR #8158.

[os-zhuang]

分诊 · 准入通过 (a) 类

标签：domain:devx · documentation · bug · pm:queue · priority:p2 · type Bug
finding 已摘。写前状态复核：open · 无 assignee · 无 PR。✅

准入判定 —— 失败探针已具名且已跑过

把该页逐字的接口标注到一个 stand-in 上、传给 ObjectView：TS2741: Property 'getObjectSchema' is missing

⇒ 这不是"读起来可疑"，是用门禁自己的 compileSnippets 跑出来的一条失败读数。(a) 命中，⛔ 无需再论证。

⇒ 业务上：第三方按这一页实现适配器，会得到一个 ObjectView 要求的方法它没有的对象。

⭐ 最重的一点：为什么没有任何东西拦住它

页面的例子能编译通过，只因为 DataSourceProviderProps.dataSource 声明为 any、useDataSource() 返回 any ⇒ 值在 provider 与渲染器之间被洗白了。

⇒ 卡片那句话我原样背书：「the page's central claim is unchecked end to end by construction」 —— 这一页的核心主张，按构造就是不可能被检查的。

⇒ 而且这决定了失败的时机：类型层不报、运行期直到 ObjectView 真去调 getObjectSchema 才炸。

p2 的理由（高于配对的 #8161 一档）

	#8161	本卡
失败何时发生	立刻	更晚 —— 直到某条路径真的调那个方法
失败说了什么	Next.js 的著名报错，自解释	undefined is not a function，⛔ 不指向文档
读者能否自查	能	⛔ 不能 —— any 把类型层的信号全洗掉了

⇒ 同一页、同一次普查、同一批读者，但"坏得晚且安静"要比"坏得早且响亮"高一档。 这是我本轮维持的分界。

为什么是 pm:queue 而不是决策箱

卡片给了两条路，⚠️ 但它们地位不对等：

• 甲：让这一页去教 @object-ui/types 真正导出的 DataSource，并说清最小适配器要实现哪几个方法 ⇒ 纯文档订正，今天就能做；
• 乙：导出一个新的"最小适配器"契约 ⇒ 新增公开 API，扩大公开面。

⇒ 按甲派单。⛔ 只有当实施者发现"没有一个自洽的最小子集可讲"时，乙才浮上来 —— 那时再作为决策提出。

边界

• ⛔ 不要顺手去修 any 的根因。卡片正确地把它指给了 finding(react): SchemaRendererProvider's dataSource prop and SchemaRendererContextType are typed any — a string passed where the host adapter belongs raises nothing #7912（SchemaRendererProvider.dataSource: any）和 finding(app-shell): ObjectView's entire props surface is typed any — a misspelled prop on a public route-level view raises nothing #7483（ObjectView 整个 props 面 any），并说明本卡是同一接缝的文档面、⛔ 非重复。⇒ 本卡只改文档；根因归那两张。
• ⭐ 但路由上应与它们同批（卡片建议，我背书）：三张一起看才知道"最小适配器"到底能不能讲清楚。
• ⭐ 与 finding(docs): docs/ARCHITECTURE.md's Next.js example has no 'use client' — app/layout.tsx and app/[object]/page.tsx are App Router server components as written and fail at runtime for a reader who copies them #8161 配对：同一页、同一受众，建议一个 PR 一起改，⛔ 别分两次评审。

---

Triage: lands in docs/ARCHITECTURE.md ("Custom Data Source Interface" + Examples 1–3); rationale: class (a) — a named, executed probe (TS2741: Property 'getObjectSchema' is missing) shows the documented six-method interface is rejected by ObjectView, and no package exports that shape. Graded p2 (above its pair objectui#8161) because two anys launder the value, so the failure arrives late and unattributable rather than immediately and self-explaining. Default direction: teach the real exported DataSource; exporting a new minimal-adapter contract is the fallback and would need review.

---

Generated by Claude Code