Repository navigation
Commit 49c8568
docs(spec): the app page record binding's describe and TSDoc say what the console does (#30663)
domain:spec#3 · os-sales · session_01L6bhgTqqeHSwZYJmApbDCa
<!-- claude-projects-attribution: {"github_login":"os-sales"} -->
_Requested by **Sales** · [project
thread](https://claude.ai/code/project/chan_01D5bWFY3rFzgJcytD5gD4Uu?thread=cmsg_01D5bWFY3rFzgJcytD5gD4UuKB8Sg6c6sVpL96ruVvdxaf)_
Fixes #30614
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:`page.zod.ts` 中 app 页面 `record` 绑定的 describe 与
`PageRecordBindingSchema` TSDoc,以及组件 `visibleWhen` 的 describe 与
TSDoc,改写为控制台的真实行为,并重新生成参考页。
- 为什么改:旧文案说"渲染器尚未实现、`record` 不绑定",而控制台早已读取它;照文案写元数据的作者和 AI 会放弃一个能用的绑定。
- 风险与回滚:仅文案,无键、形状、默认值或导出变化;回滚即 revert 本 PR。
- 先看:`packages/spec/src/ui/page.zod.ts`(四处文案:`PageRecordBindingSchema`
TSDoc、`record` describe、组件 `visibleWhen` TSDoc 含其「Measured on the
renderer」段、`visibleWhen` describe)、`content/docs/ui/pages.mdx`(手写指南
`record` 行)、`packages/spec/liveness/page.json`(两条说明)。
- 两分钟验证:`git grep -n "Planned in the renderer\|faulting predicate
renders\|configEvaluationScope" -- packages/spec/src/ui/page.zod.ts
content/docs ':!content/docs/releases'` 预期零命中(在 4afb995 实测退出码 1、无输出)。
- 需要你做的:无,席位落地。
## What changes
- `packages/spec/src/ui/page.zod.ts`, the `PageRecordBindingSchema`
TSDoc: the "Planned in the renderer" paragraph is replaced by what the
console does. The binding is read once per page open (the first row
under `sort`, under the caller's identity); every component's
`visibleWhen` sees that row as `record`; a record block that binds its
own row still provides that row to its own subtree; and the three states
a predicate sees (pending: the body is not drawn; no row, or a read the
server refuses as forbidden (403): `record` is null; any other failure:
the body is not drawn). A page drawn through `interfaceConfig.source`
reads no binding (round 2).
- The same file, the `record` key's `.describe()`: the same reading, in
one string. The parse half is unchanged and still stated: `type: 'app'`
only (`checkPageRecordBindingPlacement`), a strict one-row shape with no
`limit`.
- The same file, the component `visibleWhen` TSDoc and `.describe()`
(round 2, review escalation): "a faulting `visibleWhen` renders the
component ... a gate that never gates" (TSDoc), "a faulting predicate
renders the component, so such a gate never gates" and, for
`hasCapability` on a host with no capability list, "a faulting predicate
renders the component" (describe) now say the console withholds the
component. `data.total > 0` and `data.total == 0` both hide it. The
advice that the page's row is `record` is kept.
- The same file, the `visibleWhen` TSDoc's "Measured on the renderer"
paragraph (round 3, delta review 6672431263). It named
`configEvaluationScope`, which does not exist under `ui/`, and said
`record` is added "only when the page has a row — on an app page, once
the renderer mounts the page's `record` binding". It now names
`buildNodeEvaluationScope` and says `record` is the page's row: the
record a record page opens, or the row an app page's `record` binding
reads, `null` when that read finds no row or is refused as forbidden.
- `content/docs/references/ui/page.mdx`: regenerated by `gen:docs`,
never hand-edited.
- `content/docs/ui/pages.mdx` :63, the hand-written `record` row of the
Pages guide: "Planned in the renderer: until the console mounts it,
`record` stays unbound on an `app` page" is replaced by the describe's
reading, in the same words, kept as one table cell (round 1). A grep of
`content/docs` outside `releases/` for "stays unbound" and "Planned in
the renderer" now finds no hit.
- `packages/spec/liveness/page.json`, the `props.regions` note (round
3): the `[120] PageComponent.visibleWhen` read point named
`SchemaRenderer.tsx#configEvaluationScope` with `record` "only when the
page has a row". It now names
`ui/packages/react/src/SchemaRenderer.tsx#buildNodeEvaluationScope`
(noting the old name at objectui @1fb1ced36243) and states the same
`record` reading as the TSDoc.
- `packages/spec/liveness/page.json`, the `props.record` note: its last
sentence said this describe and TSDoc were stale. This PR makes that
false, so it now says they state the same reading.
- `.changeset/30614-page-record-binding-describe.md`:
`@objectstack/spec` patch, which also names the Pages guide row.
Every sentence was checked against the readers on `origin/main`
`b8929f486`: `ui/packages/app-shell/src/views/PageView.tsx`
(`appPageRecordBinding`, `AppPageRecordGate`, `AppPageRecordRead` with
`$top: 1` and `$orderby` from `sort`),
`ui/packages/app-shell/src/providers/ExpressionProvider.tsx#PageRecordScope`,
`ui/packages/react/src/SchemaRenderer.tsx#buildNodeEvaluationScope`, and
the pin
`ui/packages/app-shell/src/views/__tests__/PageView.appPageRecord-12931.test.tsx`.
## Tests
No behaviour changes, so there is no new test and no ablation. The
`@objectstack/spec` page suites pass, spec typecheck passes, and
`check:generated` reports all 14 artifacts up to date.
## Acceptance notes
- Two old sentences beyond "Planned in the renderer" were also false
against the console, and were replaced as part of stating the three
states. The TSDoc said zero rows or a refused row "leaves `record`
unbound: a predicate reading it faults, and a faulting `visibleWhen`
renders the component". The describe said "No row, no `record`: the
predicate faults and the component renders". On `main`,
`AppPageRecordRead` binds `record` as `null` for both cases (pinned by
the 0-row and 403 cases of the pin test). Separately,
`SchemaRenderer.tsx#visibilityFaultOutcome` now fails a declared
`visibleWhen` closed on a fault, so "renders" is no longer the verdict.
The new text does not describe the fault verdict of a field read on a
null `record`, because no test pins it.
- `packages/spec/liveness/page.json`, the `props.record` note: its last
sentence ("The schema's own describe() and TSDoc still say 'Planned in
the renderer' — stale prose left for a spec change") was made false by
this PR. It now reads "The schema's own describe() and TSDoc state this
same reading." It ships (`liveness` is in the package's `files`), the
claim's file surface was amended to hold it (6670237155), and
`check:liveness` is green.
- `content/docs/ui/pages.mdx` :63 carried the same stale sentence and is
fixed in round 1, under the amended claim (6670237155). The Pages guide
row was already silent on the no-row verdict, so only the "Planned in
the renderer" sentence was false there. It gains the three states the
describe states, and no claim the describe does not make.
- Round 2 (contract review 6671102362, PASS, should-fix S1-S3 and the
escalation; claim amendment 6671162776):
- S1: "a refused read" is narrowed to "a read the server refuses as
forbidden (403)". Only 403 / `PERMISSION_DENIED` / `FORBIDDEN` classify
`forbidden` (`ui/packages/react/src/utils/error-message.ts`). A 401, a
400 or rejected read, and api-disabled land in the failed-read state.
- S2: the TSDoc drops "and the failed-read state stands in its place".
An unresolved view, a refused filter or no adapter draws the gate's own
panel (`ElementDataSourceGate.tsx`). The TSDoc now agrees with the
describe: any other failure draws no page body.
- S3: an `app` page that also sets `interfaceConfig.source` is drawn as
`InterfaceListPage` outside `AppPageRecord` (`PageView.tsx`), so it
reads no binding. One clause in both texts, and no refinement.
- Escalation: since objectui#13299, `visibilityFaultOutcome`
(`SchemaRenderer.tsx`) answers a declared `visibleWhen` that faults with
`false`, pinned by
`SchemaRenderer.nodeVisibilityFailClosed-13299.test.tsx` and
`SchemaRenderer.visibleWhenRecordBinding.test.tsx` ("WITHHOLDS the
block").
- Grep of `packages/spec/src/**` (non-test) and the hand-written
`content/docs/**` for "faulting predicate renders", "faulting
`visibleWhen` renders" and "never gates": only the `page.zod.ts` sites
carried the false claim. The other hits
(`automation/schemaless-node-config.zod.ts` decision `condition`,
`ui/action.zod.ts` `pressed`, `data/object.zod.ts` `disabledWhen`
fail-soft, `kernel/public-auth-features.ts`, two migration entries)
carry no visibility fault-renders claim and are untouched.
- Round 2b: `content/docs/ui/pages.mdx` :63 now matches the round-2
describe word for word on the two points, with "no row, or a read the
server refuses as forbidden (403), binds `record` as null" and "A page
drawn through `interfaceConfig.source` reads no binding". It is still
one table cell and adds no other claim.
- Not changed: the
`ui/packages/app-shell/src/providers/ExpressionProvider.tsx`
`PageRecordScope` docblock still states the fail-soft verdict (no `ui/`
change).
- `packages/spec/src/ui/page.zod.ts` keeps "re-read when the bound
object is written": `AppPageRecordRead` keys its read on
`useDataInvalidation(object)`, so it is still true beside "once per page
open".
## Verification
<details><summary>Local gates, round 3 (head 4afb995, after merging
origin/main at 606df50)</summary>
- `turbo run build --concurrency=2`: lock VERDICT command-exit 0,
119/119 tasks.
- `gen:docs && check:generated && vitest run` over the page suites `&&
typecheck` (spec): lock VERDICT command-exit 0. "All 14 generated
artifacts are up to date" (no regenerated diff: the edited paragraph is
TSDoc only). Test Files 10 passed (10), Tests 572 passed (572).
`check:test-typecheck: OK`.
- `eslint --no-inline-config packages/spec/src/ui/page.zod.ts`: exit 0.
- `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97
commands, all exit 0 on the first pass (`check:liveness` among them).
`--ran`: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN".
- `check-changeset-no-major --base origin/main`: "This diff introduces
no `major` bump".
- The two-minute grep in 维护者速读: exit 1, no output.
</details>
<details><summary>Local gates, round 2b (head 0aeb81b, after merging
origin/main at 8f4aaf7)</summary>
- `turbo run build --concurrency=2`: lock VERDICT command-exit 0,
119/119 tasks.
- `pnpm --filter @objectstack/spec check:generated`: exit 0, "All 14
generated artifacts are up to date".
- `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97
commands, all exit 0 on the first pass (`check:doc-authoring`,
`check:doc-anchors`, `check:doc-frontmatter`, `check:docs-single-h1` and
`check:docs-redirects` among them). `--ran`: "97 derived, 97 run, 0
NOT-MEASURED, 0 UNRUN".
- `check-changeset-no-major --base origin/main`: "This diff introduces
no `major` bump".
</details>
<details><summary>Local gates, round 2 (head f7299af, after merging
origin/main at 4533101)</summary>
- `turbo run build --concurrency=2`: lock VERDICT command-exit 0,
119/119 tasks.
- `gen:docs && check:generated && vitest run` over the page suites `&&
typecheck` (spec): lock VERDICT command-exit 0. "All 14 generated
artifacts are up to date". Test Files 10 passed (10), Tests 572 passed
(572). `check:test-typecheck: OK`.
- `eslint --no-inline-config packages/spec/src/ui/page.zod.ts`: exit 0.
- `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97
commands, all exit 0 on the first pass. `--ran`: "97 derived, 97 run, 0
NOT-MEASURED, 0 UNRUN".
- `check-changeset-no-major --base origin/main`: "This diff introduces
no `major` bump".
</details>
<details><summary>Local gates, round 1 (head 03429fc, after merging
origin/main)</summary>
- `turbo run build --concurrency=2`: lock VERDICT command-exit 0,
119/119 tasks.
- `pnpm --filter @objectstack/spec check:generated`: exit 0, "All 14
generated artifacts are up to date".
- `dispatch-gates --commands --repo objectstack-ai/objectstack`: 97
commands, all exit 0 on the first pass, `check:doc-authoring`,
`check:doc-anchors`, `check:doc-frontmatter` and `check:docs-single-h1`
among them. `--ran`: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN".
- `check-changeset-no-major --base origin/main`: "This diff introduces
no `major` bump".
</details>
<details><summary>Local gates, round 0 (head 2529918)</summary>
All read at head `2529918f4`, exit codes captured before any pipe.
- `pnpm --filter @objectstack/spec build`: lock VERDICT command-exit 0.
- `pnpm --filter @objectstack/spec gen:docs && pnpm --filter
@objectstack/spec check:generated`: exit 0. "All 14 generated artifacts
are up to date". The first `check:generated` run named
`content/docs/references/**` stale. That page is regenerated in the
second commit.
- `vitest run` over `src/ui/page*.test.ts` (9 files) and
`src/ui/object-refinement-check-exports.test.ts`: Test Files 10 passed
(10), Tests 572 passed (572).
- `pnpm --filter @objectstack/spec typecheck`: exit 0.
- `eslint --no-inline-config packages/spec/src/ui/page.zod.ts`: exit 0.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack`: 97 commands, all exit 0. Six first exited 3
(PREREQUISITE NOT MET, unbuilt workspace packages). They were re-run
after `turbo run build` and exited 0.
- `--ran` reconciliation: "97 derived, 97 run, 0 NOT-MEASURED, 0 UNRUN".
- `check-changeset-no-major --base origin/main`: "This diff introduces
no `major` bump".
- Local-only: `check:dev-prereqs` exit 0, `check:skill-frame-freshness`
exit 0.
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa)_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01L6bhgTqqeHSwZYJmApbDCa
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 40a9265 commit 49c8568
5 files changed
Lines changed: 35 additions & 20 deletions
File tree
- .changeset
- content/docs
- references/ui
- ui
- packages/spec
- liveness
- src/ui
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
223 | 223 | | |
224 | 224 | | |
225 | 225 | | |
226 | | - | |
| 226 | + | |
227 | 227 | | |
228 | 228 | | |
229 | 229 | | |
| |||
348 | 348 | | |
349 | 349 | | |
350 | 350 | | |
351 | | - | |
| 351 | + | |
352 | 352 | | |
353 | 353 | | |
354 | 354 | | |
| |||
528 | 528 | | |
529 | 529 | | |
530 | 530 | | |
531 | | - | |
| 531 | + | |
532 | 532 | | |
533 | 533 | | |
534 | 534 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
60 | 60 | | |
61 | 61 | | |
62 | 62 | | |
63 | | - | |
| 63 | + | |
64 | 64 | | |
65 | 65 | | |
66 | 66 | | |
| |||
0 commit comments