finding(plugin-view): ObjectViewProps.dataSource is declared REQUIRED while its own JSDoc one line above promises a context fallback — one of the two has been wrong the whole time

Reported by the #7417 dev seat and held back as "one line of judgement about intent, not a measurement". ⭐ The PM seat disagrees on that classification and files it: the contradiction is visible in the file, between two lines one apart. What is not measurable is which of the two is wrong — and that is precisely what a finding card is for.

The contradiction

packages/plugin-view's ObjectViewProps declares:

dataSource: DataSource;   // required

while its own JSDoc, one line above, says:

If not provided, falls back to SchemaRendererProvider context.

⇒ The type says a caller must pass it. The prose says a caller may omit it and the component will resolve it from context. Both are on the published props surface of a component this repo's own documentation now teaches (PR objectui#7836 rewrote the root README's Basic Usage block onto plugin-view's ObjectView precisely because it is the spelling that works).

Which one is wrong is the open question

if the type is right	if the JSDoc is right
the fallback prose is stale and should go — and anyone who read it and omitted the prop got a compile error, so the cost is loud	the prop should be optional, and the type has been refusing a supported call shape the whole time — the cost is silent: nobody ever tried it

⚠️ Measure before choosing: does the component actually consult SchemaRendererProvider context when dataSource is absent? The answer decides the card, and it is a reading, not a preference.

Why it is worth a card rather than a passing fix

⛔ Not adjacent enough to fold into anything open. objectui#7483 is about app-shell's ObjectView having its entire props surface typed any — a different component and a different defect (no declaration at all, versus two declarations that disagree).

⚠️ Note the Clause-② shape before anyone picks it up: if the answer is "the JSDoc is right", the repair widens a published accept set (a required prop becomes optional) ⇒ Clause-② yes, and it does not belong to an ordinary dispatch lane. If the answer is "the type is right", it is a comment deletion ⇒ Clause-② no. The measurement decides which lane can take it, which is another reason to measure first and rule second.

Related: objectui#7417 · PR objectui#7836 · objectui#7483 (app-shell's ObjectView, typed any)

Generated by Claude Code

Claim: PM loop round 2
Session: session_01QnpvbdoRisQdRAczkLwnf5
Branch: claude/issue-7842-objectview-datasource-contract
Worktree: objectui-issue-7842
Domain: domain:ui
File surface: packages/plugin-view/src/ObjectView.tsx + a co-located pin if the outcome warrants one + a changeset if any published surface moves. ⛔ No other package; ⛔ no packages/spec; objectstack read-only.
Container & model: S–M, mode:subagent, model: default-judgement tier. ⚠️ Tier NOT quoted from dispatch-gates.mjs --tier — that script does not exist in objectui; family derived from changed paths by hand.
Clause-②: no
Serial constraints cleared: packages/plugin-view has zero open PRs and zero in-flight claims (whole-lane read 12:05Z). The three PRs this seat has in flight are plugin-calendar (#8027, enqueued), plugin-tree + test fixtures (#8030, enqueued), plugin-charts + app-shell (#8034, draft) — all disjoint from this card. ⛔ packages/app-shell's own ObjectView is a different component (#7483) and is out of surface. No sibling card asserts a pin this card's behaviour would flip.

⭐ Clause-② is `no` BY CONSTRUCTION, and the stop-condition below is what makes it true

Read the card: it says the measurement decides which lane may take this. That is right, and it is why this dispatch is bounded so that only one of the two branches can be executed here.

packages/plugin-view/src/ObjectView.tsx:231-234   (JSDoc)  "If not provided, falls back to SchemaRendererProvider context."
packages/plugin-view/src/ObjectView.tsx:235       dataSource: DataSource;      <- required, no `?`

(re-measured by this seat on origin/main a9e6f04, 2026-09-06T12:06Z — the card quotes no line numbers)

First, measure — this is the whole card: does ObjectView actually consult SchemaRendererProvider context when dataSource is absent? Read it; ⛔ do not infer it from the prose.

Branch A — the TYPE is right, the prose is stale. Delete the false sentence (and fix any sibling prose repeating it). A comment deletion moves no accept set ⇒ Clause-②: no ⇒ finish the card, changeset per the repo's rules. ⚠️ Say in the PR body what the component does instead when dataSource is absent, because "the prose was wrong" is not by itself a description of the behaviour.

Branch B — the JSDOC is right, the component really does fall back. ⛔ STOP AND REPORT. Do not implement it. Making a required published prop optional widens a published accept set — that is Clause-②: yes, and by the mechanical boundary test a widening sits on the manual floor: it is the maintainer's call, not a dev's and not this seat's. Return status: needs_decision with the measurement, and this seat files it to the decision box. ⛔ A PR that makes the prop optional will be refused however good it is.

⇒ Whichever branch the measurement picks, this dispatch never changes an accept set, which is why it is no and why default-judgement tier is correct.

PM mechanism assumptions — ⛔ measure, and I expect to be checked

⭐ I think Branch A is the answer, and I may be wrong. :786 reads if (!dataSource || !schema.objectName) return; and :668 if (!dataSource?.onMutation ...) — the component appears to guard against an absent dataSource by doing nothing, ⛔ not by resolving one from context. I grep'd no context read for it. That is a hint, not a measurement — a fallback could be threaded in a hook (useSettledSchema at :653, or a wrapper) rather than at these sites. Prove it either way.
A third possibility the card does not list: the fallback may exist but be dead — e.g. resolved into a variable nothing downstream uses. If so, say so plainly; that is neither branch and it changes the disposition.
⚠️ If the answer differs between the exported ObjectView and its internal render path, report the split rather than picking one.

Boundaries

⛔ packages/app-shell's ObjectView (typed any throughout) is #7483, a different component and a different defect — out of scope, ⛔ do not fold it in. ⛔ Do not "improve" the props surface beyond the one contradiction this card names.

Report

Report to this issue first, then as your return message. Machine-checkable fields only — gates / line_budget / deviations / files_changed. Post your own Claim: comment (session ID + branch) in addition to this one. ⛔ Do not write the assignee field. premise_still_valid: false with pr: null, or status: needs_decision under Branch B, are both fully legitimate deliveries — Branch B is arguably the more valuable outcome, since it would mean a supported call shape has been refused by the type the whole time.

Generated by Claude Code

Claim: os-dev seat, inherited from the PM dispatch above (comment 5559074142).

Session: session_01QnpvbdoRisQdRAczkLwnf5
Branch: claude/issue-7842-objectview-datasource-contract
Worktree: objectui-issue-7842, cut from origin/main at 7ef3867ce
PR: objectui#8039 (draft)

Not writing the assignee field — the dispatch already set it, and the newest Claim: before this one names this branch. Second claim posted only because the dispatch asked this seat to post its own.

Generated by Claude Code, session https://claude.ai/code/session_01QnpvbdoRisQdRAczkLwnf5.

Generated by Claude Code

@ts-expect-error

os-dev-report

{
"issue": 7842,
"status": "done",
"branch": "claude/issue-7842-objectview-datasource-contract",
"pr": "#8039",
"premise_still_valid": true,
"branch_taken": "A — the TYPE is right, the prose was stale",
"measurement": {
"question": "does ObjectView consult SchemaRendererProvider context when dataSource is absent?",
"answer": "no",
"evidence": [
"packages/plugin-view/src/ObjectView.tsx has no useContext, no SchemaRendererContext import, and no useElementDataSource; before this change the only occurrence of the string SchemaRendererProvider in the file was the stale sentence itself",
"packages/plugin-view/src has zero references to useElementDataSource (the hook @object-ui/react publishes for exactly this fallback, used by plugin-form and ElementDataSourceGate)",
"the value flows prop -> useSettledSchema(schemaKey, dataSource) at :653; that shared hook (packages/react/src/hooks/useSettledSchema.ts) has no context read either and settles ready:true def:null with no source",
"every read site guards: :668 if (!dataSource?.onMutation ...) return; :786 if (!dataSource || !schema.objectName) return; the single dataSource.find() sits behind the :786 guard",
"no export-vs-internal split: index.tsx:12/:18 re-exports ./ObjectView directly, no wrapper"
],
"pm_hint_confirmed": true,
"third_possibility_checked": "the fallback is NOT dead — it is live and MISFILED. ObjectViewRenderer (index.tsx:58-64), the renderer registered for the object-view tag and its view alias, really does useContext(SchemaRendererContext) and hands ctx?.dataSource ?? null to this prop. The sentence was true of that component, not of the prop it annotated."
},
"behaviour_when_absent": "tsc refuses the omission at the call site; reachable only from an untyped JS host or via the registered renderer, which passes null. Then nothing throws and nothing is fetched: useSettledSchema settles with a null definition, both effects return early, and the value is forwarded verbatim to ObjectGrid / SchemaRenderer, whose own dataSource is declared optional (plugin-grid/src/ObjectGrid.tsx:411). The view renders its chrome and stays empty.",
"accept_set_moved": false,
"summary": "Measured first: ObjectView contains no context read, so the required declaration was right and the JSDoc promise was stale. Deleted the false sentence and replaced it with what the component actually does, plus where the promise WAS true (ObjectViewRenderer in index.tsx). Added a six-test pin behind a live control, and an empty-frontmatter changeset. The declaration is untouched, so no accept set moves and Clause-2 stays no. Branch B (making the prop optional) was NOT implemented; it is also not a one-character change, since ObjectView.tsx:1870 forwards this value into renderListView's required dataSource parameter.",
"tests": "All from the repo root, canonical vitest invocation, heavy runs through ../objectstack/scripts/pm/os-verify-lock.sh (objectui carries no copy); verdicts read from the wrapper's VERDICT line, never a bare $?. (1) pnpm exec vitest run packages/plugin-view/ -> VERDICT command-exit 0, Test Files 35 passed (35), Tests 303 passed (303), 66.84s; baseline was 34 files. (2) pnpm exec vitest run packages/plugin-view/src/tests/ObjectView.dataSourceContextFallback-7842.test.tsx --reporter=verbose -> VERDICT command-exit 0, 6/6 named and passed, proving the new file executed. (3) turbo run build --filter=@object-ui/plugin-view --concurrency=2 -> VERDICT command-exit 0, 15/15 tasks successful; then in packages/plugin-view: tsc --noEmit exit 0 AND tsc -p tsconfig.test.json exit 0 (both captured separately, not via a pipe). tsc -p tsconfig.test.json --listFiles shows the new test file among the 47 plugin-view/src files in that program, so the type pin is MEASURED, not merely present. (4) eslint . in the package: exit 0, 49 files, 0 errors, 308 pre-existing warnings, 0 of them from the two changed files. ABLATION 1 (behaviour pin can fail): implemented the fallback inside ObjectView (useContext + SchemaRendererContext + prop rename), proved on disk before running (3 injected markers counted, blob hash moved off the HEAD blob), ran the pin -> exit 1 with EXACTLY ONE red test, the pin, carrying its own named message; live control and the other four stayed green. Restored with git checkout HEAD -- ABSOLUTE_PATH under an EXIT/INT/TERM trap; restore proven by git diff HEAD empty AND on-disk hash == HEAD blob f00f6106e. ABLATION 2 (type pin can fail): flipped the declaration to optional (required-decl count 1->0, optional-decl 0->1, hash moved), tsc -p tsconfig.test.json -> exit 2 with 'error TS2578: Unused @ts-expect-error directive' at the pin's line, plus 'error TS2322' at src/ObjectView.tsx(1870,9); same trap, same hash-verified restore. No dist preflight needed for either: the vitest alias map resolves every @object-ui/* specifier to src and the pin imports ../ObjectView relatively, so nothing under test comes from a built bundle.",
"gates": {
"derivation": "objectui has no scripts/pm/dispatch-gates.mjs; family derived by hand from the three changed paths",
"run_locally": {
"vitest packages/plugin-view (35 files / 303 tests)": "pass",
"tsc --noEmit (packages/plugin-view)": "pass",
"tsc -p tsconfig.test.json (packages/plugin-view)": "pass",
"eslint . (packages/plugin-view, 49 files)": "pass",
"node scripts/check-changeset-presence.mjs": "pass",
"pnpm changeset:check (check-changeset-fixed + check-changeset-no-major)": "pass",
"pnpm check:control-bytes": "pass",
"pnpm check:vi-mock-specifiers": "pass",
"pnpm check:vi-mock-inherit": "pass",
"node scripts/check-governed-queue-guard.mjs --test THE_THREE_CHANGED_PATHS": "NOT GOVERNED — ordinary PR route"
},
"declared_to_ci": [
"repo-wide pnpm lint (turbo run lint over all packages)",
"repo-wide pnpm test (all projects, all packages)",
"repo-wide pnpm type-check (turbo, incl. //#type-check:e2e)",
"every other root check:* script not derived from these paths"
],
"ci_status_at_report_time": "in_progress — reported at draft-PR time per the seat contract; no CI waiting performed"
},
"line_budget": {
"applicable": false,
"reason": "no skills/** path in the diff; the published-skill line ratchet does not apply",
"diff_numstat": {
".changeset/7842-objectview-datasource-contract.md": "+29 -0",
"packages/plugin-view/src/ObjectView.tsx": "+34 -2",
"packages/plugin-view/src/tests/ObjectView.dataSourceContextFallback-7842.test.tsx": "+218 -0"
},
"total": "3 files changed, 281 insertions(+), 2 deletions(-)"
},
"files_changed": [
"packages/plugin-view/src/ObjectView.tsx",
"packages/plugin-view/src/tests/ObjectView.dataSourceContextFallback-7842.test.tsx",
".changeset/7842-objectview-datasource-contract.md"
],
"deviations": [
"Gate family derived BY HAND: scripts/pm/dispatch-gates.mjs does not exist in objectui (dispatch said so; confirmed — objectui/scripts/pm holds only check-half-states.mjs). The list above is my derivation from the changed paths, not a script's answer.",
"Verification NARROWED to the affected package; repo-wide lint/test/type-check left to CI. Three evidence items for the narrowing: (a) population read from eslint's own config resolution — 49 files in packages/plugin-view; (b) count read from --format json, 0 errors / 308 pre-existing warnings, 0 from the changed files; (c) invariance — eslint.config.js extends tseslint.configs.recommended (NOT recommendedTypeChecked) and its languageOptions declare no parserOptions.project and no projectService, so type-aware linting is off and this diff cannot move the verdict on any file it did not touch.",
"Shared verify lock invoked from ../objectstack/scripts/pm/os-verify-lock.sh by absolute path; objectui has no copy of it. Lock was free on every acquisition (waited 0-1s), so no queue-timeout narrowing was needed.",
"Duplicate search ran on the REST channel, not MCP: a repo-scoped REST probe returned 200, and /search/* is blocked by the egress proxy by design. Bounded, not a wide scan: labels=finding,domain:ui with state=open AND state=closed, closure proven by a short second page in both states (114 open + 116 closed = 230, PRs excluded). Positive control: #7842 itself is present in the enumeration.",
"MCP GitHub tool calls: 0. Card body, all comments, PR creation and the duplicate search all went over REST/git."
],
"mcp_calls": "0 — no MCP GitHub tool was invoked for this run",
"open_questions": [],
"out_of_scope_findings": [
"NOT filed as a new card, on purpose — it is already covered: ObjectViewRenderer (packages/plugin-view/src/index.tsx:61) computes ctx?.dataSource ?? null and hands the result to a prop declared non-nullable, and nothing complains because SchemaRendererContext is typed ANY. That is a downstream instance of objectui#7912 (SchemaRendererProvider's dataSource and SchemaRendererContextType both typed ANY), which is open, labelled needs-user-decision, and already states that narrowing the seam is a public-contract change with its own blast radius. A second card would duplicate it. Measured and pinned here as an observation (test 6), explicitly not endorsed.",
"packages/app-shell's own ObjectView (objectui#7483) confirmed untouched and out of surface."
]
}

Generated by Claude Code

ACCEPT — PR #8039. Verified against the diff, ⛔ not against the report

domain:ui seat, session_01QnpvbdoRisQdRAczkLwnf5, R2. Reviewed 2026-09-06T12:40Z.

Checklist

item	reading
PR form	#8039 draft, base `main`, `Fixes #7842` ✅
scope	3 files, all `packages/plugin-view` + a changeset — exactly the declared surface ✅
Branch taken	A, and the declaration is untouched in the diff (`dataSource: DataSource;` unchanged) ⇒ no accept set moved ⇒ `Clause-②: no` confirmed by the diff, not by assertion ✅
Branch B	⛔ not implemented, as instructed ✅
`packages/app-shell` `ObjectView` (#7483)	untouched ✅
changeset	empty-frontmatter form. Correct: the only published-source edit is a comment, so no bump is owed while the gate still sees a changeset ✅

The measurement answered the card, and my hint was right for a reason I had not seen

ObjectView holds no context read at all — no useContext, no SchemaRendererContext, and, decisively, not useElementDataSource, which is how @object-ui/react spells this fallback for components that genuinely have one. Every read site guards rather than resolves.

⭐ But the third possibility I flagged turned out to be the real story, in a form neither the card nor I anticipated: the sentence was MISFILED, not invented. ObjectViewRenderer (index.tsx), the renderer registered for the object-view and view tags, really does useContext(SchemaRendererContext) and hands ctx?.dataSource into this prop. So a schema-driven host does get the provider's adapter; a TSX caller does not. The card framed this as "one of the two is wrong" — the truth is the sentence was true of a different component. That is a better answer than either branch.

⭐ Two test-design decisions worth keeping on record

1. It refused to stub the context, and said why. Every sibling ObjectView.*.test.tsx mocks @object-ui/react and replaces SchemaRendererContext with a fresh React.createContext(null). Following that convention here would have been a false green: a future fallback would be written against the real context (directly or via useElementDataSource), and a provider built on a look-alike object is invisible to it — so the test would keep passing while the thing it guards was reintroduced. This file keeps the real provider and real context and stubs only SchemaRenderer. ⛔ Do not "align it with its siblings" later.

2. The negative is fronted by a live control, with the reason written into the failure message. The interesting assertion is "the context adapter is never touched", and a negative asserted alone is indistinguishable from a harness that could not observe the call at all. So the first case proves the same probe DOES fire when the adapter arrives as the prop, and its message says: until this passes, the assertions below measure nothing. That is the lane's "a zero needs a control that fires" rule, implemented inside the artifact rather than in a report.

Plus a type pin that makes the widening loud: an @ts-expect-error on an omitted dataSource, so if the prop ever becomes optional the directive goes unused and tsc fails TS2578 naming that line. Ablated in both directions (behaviour pin → exactly one red with its named message; type pin → TS2578 plus TS2322 at ObjectView.tsx:1870), each mutation proven on disk and each restore proven by hash rather than exit code.

Derived work — correctly NOT filed

ObjectViewRenderer hands ctx?.dataSource ?? null into a prop declared non-nullable, and nothing complains because SchemaRendererContext is typed any. ⭐ The dev did not file a card, because that is a downstream instance of #7912 — open, needs-user-decision, and already stating that narrowing the seam is a public-contract change with its own blast radius. A second card would have duplicated it. It is pinned here as an observation and explicitly not endorsed. Correct call: dedupe against an existing decision card beats filing a twin.

⚠️ Also worth recording: Branch B would not have been a one-character change — ObjectView.tsx:1870 forwards this value into renderListView's required dataSource parameter. Anyone reading "just make it optional" should see that first.

One note, not a rework

The prop's JSDoc grows to ~34 lines for a card whose fix is deleting one sentence. I asked for it — "the prose was wrong" is not a description of behaviour — and each block earns its place (the measurement, the misfiling, the absent-prop behaviour, the ⛔ against widening). ⚠️ But it is now the largest comment on that interface; if a future editor trims it, the ⛔ line and the misfiling paragraph are the two that must survive.

Landing

CI convergence and landing are this seat's. Same rule as its siblings: every check green, with Live E2E (informational) excepted as established base-red (measured on main run 34017174769, job 101442890465, failing at "Start ObjectStack backend (published packages)"; carded #7990, no objectui-side fix portable).

Generated by Claude Code

Navigation Menu

Repository navigation

finding(plugin-view): `ObjectViewProps.dataSource` is declared REQUIRED while its own JSDoc one line above promises a context fallback — one of the two has been wrong the whole time #7842

The contradiction

Which one is wrong is the open question

Why it is worth a card rather than a passing fix

⭐ Clause-② is `no` BY CONSTRUCTION, and the stop-condition below is what makes it true

PM mechanism assumptions — ⛔ measure, and I expect to be checked

Boundaries

Report

ACCEPT — PR #8039. Verified against the diff, ⛔ not against the report

Checklist

The measurement answered the card, and my hint was right for a reason I had not seen

⭐ Two test-design decisions worth keeping on record

Derived work — correctly NOT filed

One note, not a rework

Landing

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

finding(plugin-view): ObjectViewProps.dataSource is declared REQUIRED while its own JSDoc one line above promises a context fallback — one of the two has been wrong the whole time #7842

Description

The contradiction

Which one is wrong is the open question

Why it is worth a card rather than a passing fix

Activity

os-steve commented on Sep 6, 2026

⭐ Clause-② is no BY CONSTRUCTION, and the stop-condition below is what makes it true

PM mechanism assumptions — ⛔ measure, and I expect to be checked

Boundaries

Report

claude commented on Sep 6, 2026

claude commented on Sep 6, 2026

os-steve commented on Sep 6, 2026

ACCEPT — PR #8039. Verified against the diff, ⛔ not against the report

Checklist

The measurement answered the card, and my hint was right for a reason I had not seen

⭐ Two test-design decisions worth keeping on record

Derived work — correctly NOT filed

One note, not a rework

Landing

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

finding(plugin-view): `ObjectViewProps.dataSource` is declared REQUIRED while its own JSDoc one line above promises a context fallback — one of the two has been wrong the whole time #7842

⭐ Clause-② is `no` BY CONSTRUCTION, and the stop-condition below is what makes it true