finding(components): the only working route from a provider dataSource into a data-table is the properties envelope protocol.md tells authors not to use

Found while implementing #5126 / #5337 (PR #5371), which corrects three skill guides that taught data-table + bind. Direction there was settled by inheritance from #5125 — data-table does not gain bind, the teaching changes — so this is filed separately rather than folded in. It is the measurement anyone weighing that decision again would want, and it is not an argument for re-opening it.

The question

After PR #5371 the guides teach data-table's inline data array, which is correct and renders. That leaves an unanswered one: how does an author put provider data (SchemaRendererProvider dataSource) into a data-table at all, without the host pre-resolving the array into the schema?

Measured

Real SchemaRenderer inside a SchemaRendererProvider holding dataSource = { customers: [ 2 records ] }, columns identical in all three legs, reading tbody td text (objectui@99d8721a3, vitest from the repo root):

leg	node	rendered body cells
A	`{ "type": "data-table", "data": "${data.customers}", "columns": [...] }`	`["No results foundTry adjusting your filters or search query."]`
B	`{ "type": "data-table", "properties": { "data": "${data.customers}" }, "columns": [...] }`	`["Ada Lovelace","ada@example.com","Grace Hopper","grace@example.com"]`
C	`{ "type": "data-table", "props": { "data": "${data.customers}" }, "columns": [...] }`	`["No results foundTry adjusting your filters or search query."]`

So exactly one of the three spellings works, and it is B.

Why

SchemaRenderer's evaluatedSchema memo evaluates expressions in exactly four places: properties.*, content, props.*, and the visibility / disabled predicates. A top-level key is never evaluated, which kills A — Array.isArray is false for the raw ${...} string, so DataTableRenderer falls back to EMPTY_ROWS.

Then the COMPAT hoist copies every properties.* value onto the node's top level. props.* gets evaluated but is not hoisted, and DataTableRenderer destructures data off the node, not off schema.props — which kills C.

B survives because it is the only spelling that gets both halves: evaluated, then hoisted.

Why it is worth recording

skills/objectui/rules/protocol.md opens by telling authors the opposite:

The one exception is the element:* namespace. Those components read their config out of properties / props by design ... Match the envelope to the namespace; do not apply either shape everywhere.

So the one envelope the published rules tell an author not to reach for is the only one that reaches the provider's data, and the two spellings the rules endorse both fail in the shape this repo keeps paying for — no throw, no console line, a header over an empty state. An AI author following the rules file cannot get there; one ignoring it can.

This is also the inverse of the shape #4799 corrected. There the canonical properties spelling was starved while the legacy props alias was fed; here properties is the only fed spelling and the canonical node-level one is starved. Same seam, opposite polarity.

Not proposed here

No fix is proposed and none should be inferred. The plausible directions all cost something and at least one of them was already declined in the neighbourhood:

Evaluate data (or a declared set of array-valued keys) at the node level. Widens what expressions reach, on the generic path, for every component.
Give data-table a bind read. This is the direction finding(components): table 被注册两次,data-display 的 SimpleTableRenderer 被 complex/table.tsx 完全遮蔽 —— 而它是唯一读 bind 的表格渲染器 #5125's ruling declined for its sibling renderer; it would need a new Feature card through the decision inbox.
Rule that host-side resolution is the only supported route, and say so in the guides — the cheapest, and it makes the current teaching complete rather than merely true.
Change nothing and record the measurement, which is what this card does today.

Nothing here is blocked on it and no behaviour is broken; #5126 is not addressed by this card and #5120 remains open as its own separate question about the columns key spelling.

Reproducing

Three nodes above, rendered through SchemaRenderer with a provider; the evaluation order is in packages/react/src/SchemaRenderer.tsx (the evaluatedSchema memo), and the row read is data: rawData = EMPTY_ROWS in packages/components/src/renderers/complex/data-table.tsx.

Generated by Claude Code

Triage (objectui finding round): promoted to pm:queue · domain:ui · type Task, scoped to the teaching fix only: amend skills/objectui/rules/protocol.md (and any guide that repeats the envelope rule) to record the measured reality — provider dataSource reaches a data-table only through the properties envelope today; the node-level and props spellings render an empty state with no error. This documents enforced behavior and inherits nothing new; the silent-empty-table failure is the recurring class the published rules must not steer authors into. ⛔ Out of scope: directions 1 and 2 (widening node-level evaluation, or giving data-table a bind read — the latter already declined by the #5125 ruling); either needs its own decision card if real author pull appears. S, sonnet; Clause-②: no.

Generated by Claude Code

Claim — domain:ui execution seat (#5560), round 10.

Session: session_012u2pRjcqAYtoEjgr3wwhnK
Branch: claude/issue-5372-protocol-envelope-teaching
Label: pm:queue → pm:dispatched

⚠️ This card lands on a GOVERNED SURFACE (skills/**) and therefore cannot be merged by this seat. The work is dispatchable and the PR will be opened, but it stays a draft and is never flipped ready, enqueued, or auto-merged — governed surfaces are human-merge only. Flagged on the seat post (#5560 §6) for the maintainer's merge. Claiming it anyway because the defect is author-facing and real; only the merge step is gated, not the work.

Scope, exactly as triage set it — ⛔ the teaching fix only: amend skills/objectui/rules/protocol.md (and any guide repeating the envelope rule) to record the measured reality — a provider dataSource reaches a data-table only through the properties envelope today; the node-level and props spellings render an empty state with no error.

⛔ Out of scope, both of them: widening node-level evaluation, and giving data-table a bind read. The latter was already declined by the #5125 ruling. Either would need its own decision card if real author pull appears; neither is to be attempted, and neither is to be quietly prepared for.

Two things this seat requires beyond the triage note:

Re-measure before writing. The card's claim is that only the properties envelope works. That is a statement about runtime behaviour on a tip that has moved since filing (2026-08-21T10:33Z). Verify all three spellings against current origin/main and quote what each actually renders — a teaching fix that documents a behaviour which has since changed is the same defect one layer up.
⚠️ Note the published-skill net-addition budget. Prefer replacing the false teaching in place over appending a new section.

Generated by Claude Code

skills(objectui): record the measured envelope reality instead of con…

os-dev report — domain:ui seat, round 10. Draft PR #5641 (governed-surface handling: left as a draft, not flipped ready, not enqueued, no auto-merge).

{
  "issue": 5372,
  "status": "done",
  "branch": "claude/issue-5372-protocol-envelope-teaching",
  "pr": "https://github.com/objectstack-ai/objectui/pull/5641",
  "premise_still_valid": true,
  "summary": "Re-measured all three spellings on current origin/main f1c27f037 before writing: the card's claim holds unchanged. A provider dataSource reaches a data-table ONLY through the `properties` envelope; the node-level `data` expression and the `props` envelope both render the empty state with nothing thrown and nothing logged. Probing a ui:* `card` showed the rule was wrong about the NAMESPACE, not just about data-table: `properties` is evaluated and then hoisted onto the node in every namespace, so protocol.md's \"the one exception is the element:* namespace ... do not apply either shape everywhere\" is false as written, while the same sentence is true of `props`. Six published files now record the measurement; the taught route is unchanged (keys on the node, host-resolved values) because whether `properties` is an official ui:* authoring channel is #4795's open sub-question 2, still awaiting the maintainer. Both out-of-scope directions are untouched and unprepared-for: zero renderer/SchemaRenderer/types changes, and no bind read for data-table. One new test pins the measurement to the real renderer and guards the class. PR #5641 is a DRAFT and is left there for human merge, per dispatch.",
  "tests": "All at final commit 2c03db447 (git rev-parse --short HEAD in the same locked run), exit codes captured before any pipe. BUILD_EXIT=0 for `pnpm --workspace-concurrency=2 --filter '@object-ui/components^...' build`. TYPECHECK_EXIT=0 for `pnpm --filter @object-ui/components type-check` — the run echoed `> @object-ui/components@17.6.0 type-check` / `> tsc --noEmit && tsc -p tsconfig.test.json`, so it was not a zero-match silent pass (objectui spells it type-check, hyphenated). TEST_EXIT=0: `Test Files 2 passed (2) / Tests 29 passed (29)` (the new pin plus the sibling skill-guide-data-table-binding). Gates, quoting their own verdict lines: check:skills-paths `OK (95/96 stated path(s) resolve across 18 guide file(s); 1 baselined)`; check:control-bytes `OK (scanned 4690 tracked text file(s); skipped 85 binary)`; docs:check-links `Links are valid across 13 scan roots.`; check:doc-types `Every documented component type is registered.`; changeset:check `No changeset declares a major bump.`; quick-reference:check green. check:doc-snippets not quoted — broken gauge until built, and its scan surface excludes skills/ (#5465). ABLATION: both retired sites re-introduced on the committed tree; mutation confirmed ON DISK by anchored greps before the run (`instead of \\`props.*\\`` present=1, `renders nothing at all` absent=0) and by re-parsing the JSON (eval 1 must_contain became ['props.value','props.label','${data.']). Predicted direction was RED on exactly the two class-guard cases, and that is what happened: `Tests 2 failed | 12 passed (14)`. The mutation script carried `trap ... EXIT INT TERM`; the restore leg is proven by `git status --porcelain` returning empty, i.e. byte-identical to the tree that ran 29/29 green. NO REBUILD LEG IS CLAIMED because none applies: the pin reads the guides via fs.readFileSync on source paths and the renderer legs resolve through vitest's workspace alias map to packages/*/src, never dist. LINT is a declared, measured narrowing, not a skipped run: eslint's own config refuses skills/ outright ('all of the files matching the glob pattern \"skills/\" are ignored') and reports markdown as 'File ignored because no matching configuration was supplied', with files:['**/*.{ts,tsx}'] its only source glob, so 1 of 8 changed files is in its population; `--format json` reports `files eslint linted: 1 | errors: 0 | warnings: 0`; and `grep -c 'projectService\\|project:' eslint.config.js` = 0, so no type-aware linting exists and this diff cannot move a verdict on an untouched file. CI runs the farm regardless; CI convergence was not waited on.",
  "open_questions": [
    {
      "question": "The dispatch flagged skills/** as a GOVERNED SURFACE (human-merge only), but AGENTS.md §受管面 says the opposite in as many words: `.claude/skills/**` is governed, while `skills/**` at the repo root (the published tree, e.g. skills/objectui/) is explicitly NOT — and it warns that misjudging conservatively is still misjudging because it parks the work. Which governs this PR's merge path?",
      "options": [
        "A: AGENTS.md is right — skills/** at repo root is an ordinary code PR; the seat may flip it ready and enqueue once CI is green.",
        "B: The dispatch is right — treat the published skill tree as governed; then AGENTS.md §受管面 needs amending, since it currently tells every future seat the opposite.",
        "C: Leave the PR parked in draft indefinitely without reconciling the two."
      ],
      "recommendation": "A or B, but not C — and whichever is chosen, the losing document should be amended in the same stroke. I left the PR as a draft either way, because a draft is where a dev seat's PR ends and I never flip ready; this is relayed rather than acted on, per the rule that a conflict is surfaced, not silently sided with. The concrete risk of C is that this sits waiting for a merge nobody is obliged to perform."
    },
    {
      "question": "#4795's sub-question 2 — whether `properties` is an official ui:* authoring channel — is still awaiting the maintainer's one-liner (comment 5328302083). The guides now RECORD the channel without recommending it. Does the maintainer want the teaching to go further once that is ruled?",
      "options": [
        "A: Rule `properties` an official ui:* authoring channel, and the guides promote it from recorded to taught (a one-paragraph follow-up edit).",
        "B: Rule it a compat-only path; the guides then say so explicitly and the current wording stands almost as-is.",
        "C: Leave it open; the current 'recorded, not recommended' wording is stable under either outcome."
      ],
      "recommendation": "C for now — the wording was deliberately chosen to stay true under A or B, so no rework is owed by this PR. Flagging only because ruling #4795 (2) later makes a small, cheap follow-up edit available, not because anything here is blocked on it."
    }
  ],
  "out_of_scope_findings": [
    "filed as #5640: skills/objectui/SKILL.md:81 still teaches the dead `cols: { sm: ... }` layout spelling that rules/protocol.md:252 and guides/mobile.md:100 both retire citing objectui#4001 — different defect class (layout key, already ruled), filed unassigned rather than ridden in on this PR"
  ],
  "evidence": {
    "three_spellings_measured_on_current_tip": {
      "tip": "origin/main f1c27f037 (card filed against 99d8721a3; triage annotated 2026-08-21T10:33Z)",
      "method": "real SchemaRenderer inside a SchemaRendererProvider holding { customers: [2 records] }, identical columns in every leg, reading `tbody td`; vitest from the repo ROOT (package-cwd is refused, objectui#3378)",
      "A_node_level": "{ type: data-table, data: \"${data.customers}\" } => [\"No results foundTry adjusting your filters or search query.\"]",
      "B_properties_envelope": "{ type: data-table, properties: { data: \"${data.customers}\" } } => [\"Ada Lovelace\",\"ada@example.com\",\"Grace Hopper\",\"grace@example.com\"]",
      "C_props_envelope": "{ type: data-table, props: { data: \"${data.customers}\" } } => [\"No results foundTry adjusting your filters or search query.\"]",
      "D_inline_literal_control": "{ type: data-table, data: [2 literal records] } => the two rows (the route the guides teach, still working)",
      "F_bind_control": "{ type: data-table, bind: \"customers\" } => empty state (confirms the existing #5126/#5337 teaching is still true)",
      "namespace_probe_card": "props.title => NO header element at all; properties.title => header renders; node title \"${data.label}\" => literal \"${data.label}\"; properties.title \"${data.label}\" => \"Evaluated Title\". This is what rules the published sentence false rather than merely incomplete: the hoist is not element:*-scoped.",
      "verdict": "the card's central claim HOLDS unchanged on the current tip; nothing had drifted"
    },
    "sites_found_by_claim_not_grep": [
      "skills/objectui/SKILL.md:138 — Common Mistakes bullet 'Putting expression values in top-level `value` / `label` fields instead of `props.*`', i.e. the retired #4786 workaround prescribed as the FIX, in the entry file every agent loads first. None of the envelope tokens (element:*, envelope) appear in it.",
      "skills/objectui/guides/page-builder.md:481 — the identical bullet, which made that file contradict ITSELF: line 188 of the same file already said 'Moving it under `props` does not help.'",
      "skills/objectui/evals/schema-expressions.json — the GRADED form of the same false rule and the site with no prose tokens at all: evals 1 and 2 listed props.value / props.label in `must_contain`, so an assistant answering with the spelling that renders blank scored CORRECT and one answering correctly scored wrong. Fixed under the bounded in-place exemption (same defect class; correct shape pinned by the sibling prose and the 2026-08-17 ruling; no other claim on the file — no open PR touches skills/, no open issue names the evals; same gate family) and named explicitly in the PR body.",
      "grep-only sites, for contrast: rules/protocol.md (22, 49, 86), guides/page-builder.md (92, 182), guides/schema-expressions.md (86)"
    ],
    "net_addition_budget": {
      "unit": "lines (no sibling gate defines a token count for skills/ — scripts/ carries only check-skills-paths.mjs and its baseline)",
      "per_file_whole_file_before_after": {
        "skills/objectui/SKILL.md": "155 -> 155 (+0, a same-length in-place swap)",
        "skills/objectui/rules/protocol.md": "231 -> 275 (+44)",
        "skills/objectui/guides/schema-expressions.md": "612 -> 621 (+9)",
        "skills/objectui/guides/page-builder.md": "502 -> 510 (+8)",
        "skills/objectui/guides/data-integration.md": "430 -> 437 (+7)",
        "skills/objectui/evals/schema-expressions.json": "51 -> 53 (+2)"
      },
      "whole_package_before_after": "published .md across skills/: 5608 -> 5676 (+68, +1.2%); whole skills/ tree incl. eval JSON: 6216 -> 6286 (+70)",
      "note": "Preference honoured — the false teaching is replaced in place, not appended to. The +44 sits in the one file whose central rule was false and is mostly two measured tables standing in for prose that was wrong; the other four sites are pointers into it rather than restatements, which is what holds the package delta at +1.2%. No dispatch budget number was given, so this is reported rather than checked against a ceiling; if the seat has a tighter ceiling, say so and I will cut the protocol.md tables to one."
    }
  },
  "out_of_scope_respected": {
    "node_level_widening": false,
    "bind_read": false
  },
  "changeset": {
    "present": true,
    "verdict_line": "✅  No source of a released package changed in this range, so no changeset is owed. (full line: 'Compared the working tree with f1c27f037 (merge-base with origin/main): 6 file(s) changed, 0 of them under the src/ of a package the release covers, 0 under a package changesets ignores, 1 changeset(s) added.') — the gate rules none is OWED; an explicit empty-frontmatter changeset (.changeset/skill-provider-envelope-teaching-5372.md) is added anyway as objectui's first-class 'publishes nothing' declaration. This repo has no skip-changeset label and none was created or applied."
  }
}

Generated by Claude Code

skills(objectui): record the measured envelope reality instead of con…

Navigation Menu

Repository navigation

finding(components): the only working route from a provider `dataSource` into a `data-table` is the `properties` envelope protocol.md tells authors not to use #5372

The question

Measured

Why

Why it is worth recording

Not proposed here

Reproducing

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

finding(components): the only working route from a provider dataSource into a data-table is the properties envelope protocol.md tells authors not to use #5372

Description

The question

Measured

Why

Why it is worth recording

Not proposed here

Reproducing

Activity

os-zhuang commented on Aug 21, 2026

os-sales commented on Aug 21, 2026

os-sales commented on Aug 21, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

finding(components): the only working route from a provider `dataSource` into a `data-table` is the `properties` envelope protocol.md tells authors not to use #5372