[objectstack-fleet]

domain:ui#4 · zhuangjianguo · session_01QsR2jR7ZFkpqmm4U8S1f9y

Requested by Steedos · project thread

Fixes #29138

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：RecordPageTimelineCountSchema 的文档注释与 total 的 .describe() 改为说明总数统计的是请求所点名各来源的行数（按调用者可读），是「动态」面板实际绘制条目数的上界，并点名两种少画的情形；API 参考页与 JSON schema 随之重新生成；@object-ui/types 中 RecordPageResponse.timeline 的镜像注释同步改为同一说法。
• 为什么改：record-page timeline count: the docblock should say the total is an upper bound of the entries the 动态 panel draws #28998（PR docs(spec): the record-page timeline total is an upper bound of the drawn 动态 entries #29120）只改了请求侧注释；发布到 JSON schema 的 total 描述仍写成「面板持有的条目数」，第三方客户端会把差值当成缺陷。
• 风险与回滚：仅描述文本与注释，不动任何键、类型、.min()、默认值、导出与运行时行为；回滚即 revert 本 PR。
• 先看：packages/spec/src/api/record-page.zod.ts（RecordPageTimelineCountSchema 注释与 total 描述）、content/docs/references/api/record-page.mdx（生成结果）、ui/packages/types/src/data.ts（timeline 注释）、.changeset/29138-timeline-total-describe.md。
• 两分钟验证：pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec check:generated，预期 All 14 generated artifacts are up to date。
• 需要你做的：无，席位落地（总监契约复核由席位转交）。

What changes

• packages/spec/src/api/record-page.zod.ts: the RecordPageTimelineCountSchema docblock and its total .describe() now say what the RecordPageTimelineRequestSchema docblock (landed in d089dac) says: the total counts the rows of the sources the request named, as that schema's table defines them and as the caller may read them, so it is an upper bound of the entries the 动态 panel draws, not their number. Both name the two cases where the panel draws fewer: its showCompleted / types configuration, and a ledger row with no displayable diff.
• The request-side timeline .describe() in RecordPageRequestSchema ("Return the size of the record's timeline stream over the sources named (RecordPageTimelineCountSchema).") is not touched. It says "size", the word the landed file header defines as the sources' row count, and it points at RecordPageTimelineCountSchema, whose total now carries the upper-bound sentence. The response-side timeline .describe() uses the same word and the card keeps it fixed, so leaving the request side alone keeps the two sides in the same words.
• ui/packages/types/src/data.ts: the RecordPageResponse.timeline docblock in @object-ui/types, the UI's mirror of the response, says the same: the total counts the sources' rows, so it is an upper bound of the drawn entries, with the same two cases. Folded in by the seat's claim amendment on the card (comment 6577666544). Comment only.
• No key, type, member, .min(), default or export moves. Only the two docblock comments and one description string change.
• Generated: content/docs/references/api/record-page.mdx (the total row in both nested shapes that show RecordPageTimelineCount). The JSON schema under packages/spec/json-schema/ is gitignored and regenerated by the build; nothing else that check:generated covers moved.
• Changeset: .changeset/29138-timeline-total-describe.md, @objectstack/spec: patch and @object-ui/types: patch (its dist/*.d.ts ships the docblock).

Tests

No new tests: the change is prose. The spec package's suite and check:generated ran on the final head (readings below).

Verification

check:generated and the JSON schema reverse check

• pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec check:generated before regenerating: ✗ 1 of 14 artifact(s) stale: check:docs. After check:generated --fix: ✓ All 14 generated artifacts are up to date.
• Reverse check: grep -rl "upper bound of the entries the timeline panel draws" packages/spec/json-schema lists api/RecordPageTimelineCount.json, api/RecordPageResponse.json and objectstack.json; the old sentence has zero hits in packages/spec/json-schema, content/docs and packages/spec/src.

Tests, type-checks and the derived gate sweep on head 3d67012

• pnpm --filter @objectstack/spec test on 21c2817 (the last head that moved packages/spec; 3d67012 only adds the @object-ui/types comment and the changeset line): VERDICT command-exit 0, Test Files 791 passed (791), Tests 23391 passed, 1 todo.
• pnpm --filter @objectstack/spec typecheck (21c2817): exit 0. pnpm --filter @object-ui/types run type-check (3d67012): exit 0.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on 3d67012: 100 derived commands (38 changed lines, 4 files), including node scripts/check-sdui-manifest.mjs and pnpm --dir ui exec vitest run scripts/. Ran all 100: 99 exit 0, and pnpm check:dual-build-cjs-loads exits 3 (PREREQUISITE NOT MET: some workspace packages have no dist without a full build), so it is NOT MEASURED locally and left to CI. --ran reconciliation: 100 derived, 99 run, 1 NOT-MEASURED, 0 UNRUN.
• The body gates (check-changeset-no-major --base origin/main, check-closing-keyword-parity, check-adr-0087-registration --base origin/main, check-partof-closing-keyword) exit 0 on this body with Clause-②: no / Metadata-protocol: none; none asked for a different declaration.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 60 of 216 client-bound route-ledger rows — the other 156 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 156: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 101 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 168 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 57cde8cb3da5970f2c3f6512569cacdb9b2b06a8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 6aef5fdb82b60b72cc07a834e6a1709596be6a33 — the merge of head 3d670128cf3ea57a2845ad44ea6d11b03212657d into base 57cde8cb3da5970f2c3f6512569cacdb9b2b06a8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 6aef5fdb82b60b72cc07a834e6a1709596be6a33 && git checkout 6aef5fdb82b60b72cc07a834e6a1709596be6a33
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 57cde8cb3da5970f2c3f6512569cacdb9b2b06a8 3d670128cf3ea57a2845ad44ea6d11b03212657d && git checkout -B drift-repro 57cde8cb3da5970f2c3f6512569cacdb9b2b06a8 && git merge --no-ff 3d670128cf3ea57a2845ad44ea6d11b03212657d

node scripts/docs-audit/affected-docs.mjs --json 57cde8cb3da5970f2c3f6512569cacdb9b2b06a8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[zhuangjianguo]

director#1 · zhuangjianguo · session_01QsR2jV5sBSzCYNEDgpYLJw

Contract-review-claim: session_01QsR2jV5sBSzCYNEDgpYLJw · head 3d67012 · 2026-11-02T13:36Z

---

Generated by Claude Code

[zhuangjianguo]

director#1 · zhuangjianguo · session_01QsR2jV5sBSzCYNEDgpYLJw

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3d670128cf3ea57a2845ad44ea6d11b03212657d
Local-runs: none
Scope: packages/spec/src/api/record-page.zod.ts (RecordPageTimelineCountSchema docblock and total .describe()) + packages/spec/src/api/record-page.zod.ts on main (the landed #29120 file header and RecordPageTimelineRequestSchema docblock, the request-side timeline .describe() L234–236), content/docs/references/api/record-page.mdx (regenerated), ui/packages/types/src/data.ts (RecordPagePayload.timeline docblock), .changeset/29138-timeline-total-describe.md, record 6572879461 on PR #29120 (its deferred should-fix ④-1, which this card implements) and the code that record judged: packages/rest/src/record-page-routes.ts answerTimeline, ui/packages/plugin-detail/src/renderers/recordActivityFeed.ts applyFeedConfig, ui/packages/plugin-detail/src/recordTimelineStream.ts auditEntriesToFeedItems

Read-only review of the committed tree. Check-runs on the head at claim time: 59 success, 9 skipped, 1 in progress (the PR-body guard re-run after the seat's body patch); the seat lands on a green head.

① Derived judgments

• Accept set and public surface unchanged. The net diff of record-page.zod.ts is one docblock and one .describe() string; no z.* call, .min(), default, member or export moves. RecordPageTimelineCountSchema still parses exactly { total: int ≥ 0 } strict. Right.
• Published prose moves, and that is the point. The .describe() feeds packages/spec/json-schema/api/RecordPageTimelineCount.json, RecordPageResponse.json, objectstack.json and the API reference; the regenerated record-page.mdx carries the new sentence in both nested shapes that show the count, and nothing else in the page moved. The @object-ui/types docblock ships in its dist/*.d.ts. Both are the prose channels a third-party client reads, which is the card's reach. Right.
• The sentence is true of the tree, as record 6572879461 ④ already established for the same words: answerTimeline counts rows by the table as the caller may read them; applyFeedConfig hides entries by showCompleted / types; auditEntriesToFeedItems draws nothing for a ledger row with no displayable diff. "An upper bound of the entries the panel draws, not their number" is the exact relation. Right.
• No security-relevant finding; nothing withheld from this record.

② Semver level

• Changeset: @objectstack/spec patch, @object-ui/types patch; Clause-②: no and Metadata-protocol: none at line start in the changeset and the PR body. A description-only change alters no accept set, default or meaning of what an author writes, so none / patch is the required grade (the same grading record 6572879461 accepted for docs(spec): the record-page timeline total is an upper bound of the drawn 动态 entries #29120's docblock). Right.
• @object-ui/types owes its entry because the docblock ships in the published .d.ts; the regenerated mdx publishes nothing. Right.

③ Boundary flags

• Tier S (packages/spec/src/** is a published-schema face, not a governed path): the seat lands after this record and a green head.
• The request-side timeline .describe() is deliberately untouched ("Return the size of the record's timeline stream over the sources named (RecordPageTimelineCountSchema)"). Judged: "size" is the word the landed file header defines as the sources' row count, and the sentence points at the count schema whose total now carries the bound, so the request and response sides read in the same words and the bound is stated once, where the number is. Leaving it alone is right; rewording it would say the bound twice in the same JSON schema.
• Amendment 6577666544 folds in the @object-ui/types mirror docblock (comment only). Consistent with the card's "no shape or behaviour change". Accepted.
• Dev deviation: check:dual-build-cjs-loads NOT MEASURED locally (prerequisite dist), left to CI; CI is green on the head for it. No open questions.
• This closes the deferred should-fix ④-1 of record 6572879461; nothing from that line remains open after this lands.

④ Design judgment

packages/spec/src/api/record-page.zod.ts — judged against the landed #29120 docblock it must agree with and the consumers above.

• The count docblock now defines the total the way the request docblock does (the reads RecordPageTimelineRequestSchema names, as the caller; rows as that schema's table defines them) and names the same two fewer-drawn cases. The two blocks agree word for word on the relation, so a reader of either arrives at the same number. Holds.
• The .describe() is the one sentence that ships to third parties; it states the bound first, then the two cases, and names the panel's configuration keys by their real spellings (showCompleted, types). Break attempt: a client that reads the old sentence and asserts total === drawn.length was the card's defect; under the new sentence that assertion is stated as wrong, and no stronger promise is made that the tree does not keep. Holds.
• [#28737] stays in the docblock, so the ADR/card anchor survives the rewrite. Holds.

ui/packages/types/src/data.ts — the mirror says the same relation and the same two cases, keeps the objectstack#28737 anchor and the refusal arm. Holds.

No must-fix found. No should-fix.

Implemented-by: claude/project-thread-5majrv
Reviewed-by: session_01QsR2jV5sBSzCYNEDgpYLJw

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

domain:ui#4 · zhuangjianguo · session_01QsR2jR7ZFkpqmm4U8S1f9y

席位核对 · ACCEPT · 2026-11-02T13:36Z

Head-sha: 3d670128cf3ea57a2845ad44ea6d11b03212657d

• Shape: draft → main, Fixes #29138 in the body only. 4 files, +31 / −7 (38 lines ≤ 3000). No governed path: check-governed-merges --pr 29357 hit 0 of 4 paths. Author objectstack-fleet[bot]. Clause-②: no and Metadata-protocol: none are line-initial in the body and the changeset. The body was patched by the seat with the dev's v2.

• Contract review: CONTRACT_REVIEW_TIER by the director seat, PASS 6578539416 on this head. It has no must-fix and no should-fix, and it closes the deferred should-fix ④-1 of record 6572879461.

• File surface: inside the claim as amended (6577666544). The changes are:

  • the RecordPageTimelineCountSchema docblock and its total .describe() in packages/spec/src/api/record-page.zod.ts;
  • the regenerated content/docs/references/api/record-page.mdx;
  • the @object-ui/types RecordPageResponse.timeline docblock;
  • the changeset (@objectstack/spec and @object-ui/types, both patch).

  No shape, key, .min() or export moves.

• Read in the diff: the docblock and the .describe() now say what record-page timeline count: the docblock should say the total is an upper bound of the entries the 动态 panel draws #28998's landed docblock says. The total counts the sources' rows, so it is an upper bound of the drawn entries, and both name the showCompleted / types configuration and a ledger row with no displayable diff. The request-side timeline .describe() stays as it is, as the brief allowed and the director judged right.

• Tests and gates: spec tests pass 791 of 791 files, and check:generated is green. The reverse check shows the new text in the generated RecordPageTimelineCount.json. 99 of 100 derived gates exited 0; dual-build-cjs-loads was not measured locally, and CI covers it.

• Check-runs on this head: 60 success, 9 skipped, 0 failed or pending, including all 16 Test UI shards and the PR-body guard re-run after the body patch. All ten required contexts succeeded.

• Landing: ordinary queue landing, pr_ready then automerge_enable. Fixes #29138 closes the card on merge.

---

Generated by Claude Code

[objectstack-fleet]

domain:ui#4 · zhuangjianguo · session_01QsR2jR7ZFkpqmm4U8S1f9y

Landed · 2026-11-02T14:13Z · PR #29357 merged through the merge queue as 53dda03d. Record: ACCEPT 6578563992 at 3d670128 (director CONTRACT_REVIEW_TIER PASS 6578539416).

probe	before (53dda03d~1)	now (origin/main)
an upper bound of the entries the timeline panel draws, not their number in packages/spec/src/api/record-page.zod.ts (the published .describe())	0	1
so it is an upper bound of the entries the in ui/packages/types/src/data.ts (the @object-ui/types docblock, folded in per the ruling)	0	1

The card closed through Fixes. pm:dispatched comes off with this note.

---

Generated by Claude Code