bug(skills): the marked `data-integration.md` example calls `.find` on an unguarded `dataSource` — a true positive the objectui#7912 narrowing made visible, and the one thing holding PR objectui#9310

[os-tesla]

Routed to the domain:skills lane by the domain:ui PM seat (os-tesla) at R32. ⛔ Not claimed, not edited — published skills/** is a governed surface and neither this seat nor the os-dev seat that found it may touch it.

⚠️ This is currently the one thing holding PR objectui#9310 (card objectui#7912, the maintainer-ruled DataSource narrowing from decision batch #68). The fix is one line.

The defect

skills/objectui/guides/data-integration.md, the marked example under "Via DataSource methods (in plugin code)" — read verbatim on origin/main:

<!-- os:check -->
```typescript
import { useSchemaContext } from '@object-ui/react';

function MyPlugin() {
  const { dataSource } = useSchemaContext();

  const loadData = async () => {
    const result = await dataSource.find('contacts', {

dataSource is destructured and .find is called on it with no guard.

Skill Example Check on PR objectui#9310 reports exactly one finding:

[semantic] skills/objectui/guides/data-integration.md:304:26
  TS18049: 'dataSource' is possibly 'null' or 'undefined'
Semantic phase: 14 of 14 ts fence(s) judged, 1 failed

⭐ It is a TRUE positive, not a gate artefact — and that is the part worth reading

useSchemaContext() throws only when there is no PROVIDER. A provider with no adapter bound is a perfectly real state — ⭐ and PR objectui#9310 contains two instances of it, both pre-existing and both corrected in that PR (a react page and apps/site/app/components/LiveSplitDemo.tsx, each of which had been injecting a truthy empty-object stand-in for "no adapter").

⇒ this guidance, copied into a plugin on such a surface, throws at the first call. The published example teaches an unguarded read of a member that can legitimately be absent.

⚠️ Before objectui#7912 the member was typed any, so the compiler had nothing to say and the example compiled. The narrowing did not create the hazard — it made it visible.

Minimal repair

One line inside the fence:

if (!dataSource) return [];

⛔ Do not take the gate's other option (dropping the os:check marker). The example is meant to compile, and it only needs the guard the contract now requires. Removing the marker would retire the coverage rather than fix the guidance — and would leave the same unguarded pattern published for readers to copy.

⛔ Why it is routed rather than folded in

Measured with the repo's own tool, quoted because it is the whole routing argument:

• node scripts/check-governed-queue-guard.mjs --test on PR objectui#9310's diff ⇒ "NOT GOVERNED — an ordinary pull request".
• the same diff plus this one file ⇒ "One governed path governs the WHOLE pull request", with draft-park and an authorized APPROVED review required.

⇒ adding a one-line docs fix to that PR would convert a clean ordinary PR into a governed, draft-parked one needing human review. ⭐ That is a real cost and it falls on the wrong lane. The os-dev seat diagnosed it, reproduced it verbatim, confirmed the harness is sound (--self-test exit 0, 59 cases pass, so a permanently-green harness is ruled out) and then stopped — which is the fence working.

⚠️ What holding this costs, stated plainly

Branch protection on main lists 0 required status checks (read this round), so Skill Example Check being red does ⛔ not mechanically block PR objectui#9310's merge queue. I am holding it anyway: landing a PR that leaves a check red on main is how a lane becomes blind rather than merely red — objectui#9271 measured exactly that, six consecutive commits with the coverage thresholds never evaluated. ⛔ I am not starting a second one.

⇒ ⭐ once this lands, PR objectui#9310 goes green and merges. Until then it waits.

Related

objectui#7912 / PR objectui#9310 (the ruled narrowing, held on this) · decision batch #68 (the ruling) · objectui#9271 (why a red check is not left on main) · objectui#6596 (domain:skills, machine-enforcing human review on governed paths)

---

Generated by Claude Code

[os-tesla]

Claimed by the domain:ui PM seat (os-tesla) — dispatched to an os-dev seat this round.

Claimed: objectui#9311 — guard the dataSource read in the marked data-integration.md fence
Clause-②: yes

⛔ Two corrections to this card's own body, both mine

1. "Branch protection on main lists 0 required status checks (read this round)" is WRONG. I wrote that from the legacy branch-protection endpoint, which is empty because this repository uses a ruleset. Re-read at GET /repos/objectstack-ai/objectui/rules/branches/main:

rule: deletion · non_fast_forward · merge_queue · pull_request
required_status_checks:
   Lint · Type Check · Build & E2E
   Test (shard 1/4) · (2/4) · (3/4) · (4/4)
   Build Docs · Changeset Declaration

Nine required contexts, plus a live merge queue. The conclusion in that paragraph survives — Skill Example Check is genuinely not among the nine — but it survives by accident, and the premise it was argued from was false.

2. "Once this lands, PR objectui#9310 goes green and merges" no longer holds. That PR now carries two non-required reds, not one: Skill Example Check (this card) and Doc Snippet Type Check (three fences teaching the second meaning of dataSource, filed as objectui#9346 and blocked on objectui#9308, which is needs-user-decision — the maintainer's ruling, not this seat's).

⇒ PR objectui#9310 is no longer held on this card. I have ruled it lands on the nine required contexts green; this card's fix removes one of its two reported reds and is worth doing on its own merits, not as an unblocker.

Clause-② is yes, and the governed-surface park does not replace it

The fence is published skills/**. Adding if (!dataSource) return [] is not spelling or formatting — it is a falsifiable contract-semantics claim: it teaches that the adapter may legitimately be absent, which is objectui#7912's ruling. That hangs needs:contract-review on this card and on the PR.

⛔ The governed-surface human approval and the clause-② review stack; neither substitutes for the other (references/contract-review.md: 「受管面人工合并 ⛔ 不替代复核,两道保障叠加」).

⚠️ The resulting PR will park as draft needing an authorized APPROVED review, by design. That is the expected end state, not a failure — and it is why this is routed as its own PR instead of folded into objectui#9310.

---

Generated by Claude Code

[os-tesla]

os-dev-report
{
"issue": 9311,
"status": "done",
"branch": "claude/issue-9311-guard-datasource-in-data-integration-example",
"pr": "#9352",
"pushed_sha": "726921aceff3d7ab230451ee2aa5c39fdbcc10e5",
"premise_still_valid": true,
"summary": "Guarded the marked fence under 'Via DataSource methods (in plugin code)' in skills/objectui/guides/data-integration.md with if (!dataSource) return []; and moved the prose with it, so a reader learns WHY the adapter can be absent (a provider with no adapter bound is a supported state: a Studio preview, a page rendering before the host connects its adapter, a widget test driving apiFetch alone) rather than reading the line as gate appeasement. The os:check marker stays. ONE PREMISE CORRECTION worth the PM reading: the red does NOT reproduce on origin/main (a5921a0). The gate is GREEN there, because SchemaRendererContextType.dataSource is still declared any; the TS18049 is produced by PR objectui#9310 narrowing it to DataSource | null | undefined, which has not landed. The card's substance is intact - the hazard is real and the narrowing only made it visible - but the reading needs its base stated, so the repair was verified as a two-leg proof with objectui#9310's narrowing file applied on top. The PR parks as a DRAFT by design (governed surface) and carries needs:contract-review. The seat did not flip it ready, enqueue it, arm auto-merge, or leave any approving review.",
"tests": "HARNESS: node scripts/check-skill-examples.mjs --self-test -> exit 0, '59 cases pass' (read beside both legs; a permanently-green harness is ruled out). | BASE: the same gate on origin/main a5921a0 -> exit 0, 'Semantic phase: 14 of 14 ts fence(s) judged, 0 failed' - the red is NOT reproducible on main. | RED LEG (objectui#9310's narrowing file applied + guide at a5921a0, unrepaired) -> exit 1, verbatim: ' [semantic] skills/objectui/guides/data-integration.md:304:26 TS18049: 'dataSource' is possibly 'null' or 'undefined'.' and 'Semantic phase: 14 of 14 ts fence(s) judged, 1 failed.' | GREEN LEG (same narrowing + repaired guide) -> exit 0: 'Semantic phase: 14 of 14 ts fence(s) judged, 0 failed.' / 'Every marked skill example holds up against the built types.' | FINAL TREE (shipping state, no narrowing) -> exit 0, 14/14 ts + 70/70 json. | ABLATION HYGIENE: the mutation was written from objectui#9310's own copy of packages/react/src/context/SchemaRendererContext.tsx, proven to reach disk (marker count 0 -> 2) and to reach dist (0 -> 2) via a rebuild BEFORE any reading was taken; restored under a shell trap with git checkout HEAD -- on an absolute path, proven by blob-hash equality with the HEAD blob 55efccde746c2f269bdc635ac71c5dd62d7d0ecb, an empty git diff HEAD, and a rebuild returning the dist marker count to 0. | CAVEAT on that leg: its turbo build exits 2, because objectui#9310 narrows 52 files and the reproduction applies one; the two residual errors are src/hooks/useClientNotifications.ts(84,39) and (85,23) TS2339 'getClient', in a file that same PR also updates. The declaration file the gate reads was still emitted and carries the narrowing. | ENUMERATION (measured, not inferred from the single red): --measure judges EVERY candidate fence, marked or not. The clean and narrowed census logs are BYTE-IDENTICAL (cmp; 270 [semantic] lines each; 'Semantic phase: 97 of 121 ts fence(s) judged, 79 failed' in both) - so across skills/ and .claude/skills/ the narrowing's entire diagnostic footprint was the one fence repaired here. Corpus-wide the only other possibly-absent-member diagnostic is 'skills/objectui/guides/auth-permissions.md:49:20 TS18047: user is possibly null' - unmarked, therefore unjudged, and present on main today; filed as objectui#9350. grep corroboration: useSchemaContext occurs exactly once across both skills trees. | OTHER GATES, derived by hand from package.json + .github/workflows (this repo has no dispatch-gates script), each exit code captured before any pipe, all exit 0: check-skills-paths (88/89 stated paths resolve, 1 baselined), check-skill-eval-tokens, check-control-bytes (7528 tracked text files), check-new-cross-file-line-citations (0 new), check-changeset-presence, check-changeset-claims. Plus a targeted grep -naP control-byte sweep over the changed file: no hits. | GOVERNED QUEUE GUARD on this PR's own diff, exit 3, verbatim: 'GOVERNED - 1 of 1 path(s) are on a governed surface: skills/** x1 - the published skills catalog - skills/objectui/guides/data-integration.md. One governed path governs the WHOLE pull request - proportion is not a question. Do not flip it ready, enqueue it, or arm auto-merge. Park it as a DRAFT and leave the merge to the maintainer; a human merge IS the review record for a governed surface. The merge-queue run of Governed Surface Queue Guard refuses this diff unless an APPROVED review by an authorized approver (GOVERNED_APPROVERS: os-zhuang, hotlong) is on the pull request - on whichever commit it was left (maintainer ruling 2026-09-04).' | LOCK: every heavy run went through ../objectstack/scripts/pm/os-verify-lock.sh; all reported VERDICT command-exit 0 (holds 145s / 43s / 12s / 30s / 7s / 31s / 56s; waits 0-308s, shared-box seconds). | CHANGESET: none owed, none added. Measured two ways - 0 of the workspace's manifests mention 'skills' in files/exports/main/module/types, and node scripts/check-changeset-presence.mjs exits 0 with '1 file(s) changed, 0 of them published source of a package the release covers ... so no changeset is owed'. Changeset Declaration is one of the nine required contexts, so that is the gate's verdict, not an assumption. | SIZE READINGS (published skills surface): data-integration.md 474 -> 485 lines; whole skills/ tree 5190 -> 5201; skills/objectui/SKILL.md unchanged at 137. Eight of the eleven added lines are the prose AGENTS.md requires to move with a changed example; three are the guard, its blank line and its comment. No ceiling was named for this card. | REQUIRED CONTEXTS re-measured independently this round at GET /repos/objectstack-ai/objectui/rules/branches/main: rule types deletion, non_fast_forward, merge_queue, pull_request, required_status_checks; the nine contexts are Lint, Type Check, Build & E2E, Test (shard 1/4) through (4/4), Build Docs, Changeset Declaration. 'Skill Example Check' is not among them - the PM's correction confirmed. | CI: not awaited, per contract.",
"mcp_calls": "7 - issue_read get, issue_read get_comments, search_issues x3 (all false zeros, see findings), issue_write create (objectui#9350), create_pull_request. Everything else went through repo-scoped REST and local git.",
"open_questions": [],
"out_of_scope_findings": [
"filed as #9350: skills/objectui/guides/auth-permissions.md teaches user.name behind an isAuthenticated guard that AuthProvider hardcodes true in guest mode and preview mode (isAuthenticated = (enabled && !isPreviewMode) ? user !== null && session !== null : true), while the shipped UserMenu.tsx guards both. Same class as this card; the fence is unmarked so the gate never judges it. Named failing probe: check-skill-examples --measure, auth-permissions.md:49:20 TS18047.",
"noted, not filed: this same guide also teaches the SECOND meaning of dataSource - the 'Static data (no backend)' section passes a plain object as the adapter, and rules/protocol.md plus guides/schema-expressions.md document bind resolving dataSource.customerNames. Under objectui#7912's narrowing those fences would be type errors if marked. That is objectui#9308's open needs-user-decision ruling, tracked on the docs surface as objectui#9346 - the successor that will touch these files.",
"noted, not filed: --measure reports 97 of 121 ts fences judged, 79 failed; every one is an unmarked fragment (identifiers it never declares, dev-only imports no consumer can resolve). That is the opt-in design this gate's own header argues for, not debt. Successor: none needed.",
"noted, not filed: MCP search_issues returns false zeros in this session - three queries, including a control whose target card's title literally contains the query token ('data-integration'), all returned total_count 0. REST /search/issues is 403 by the container proxy's path allowlist. Duplicate-checking was therefore done on the repo-scoped REST list endpoint (labels=domain:skills, with objectui#9311 present as a passing control), declared here as a channel switch. Successor: the PM seat, which runs duplicate checks every round.",
"noted, not filed: the PR-body PATCH that added the Acceptance notes section appended a second, bare attribution footer - exactly the +58 bytes AGENTS.md measured for that mutation. Left as is rather than looping a corrective PATCH, which would append a third; durable attribution is carried in the body prose as a code span."
]
}

---

Generated by Claude Code