[objectstack-fleet]

Requested by Steedos · project thread

Fixes #28998

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:记录页 timeline 计数的文档注释改为说明总数统计的是各来源表定义的行数,是「动态」面板实际绘制条目数的上界,并点名两种少画的情形;API 参考页同步重新生成。
• 为什么改:总监对 PR feat(rest,console): the record page payload serves the 动态 count, so the activity part asks only the panel's rows #28991 的契约复核记录 6570231752 的 ④-1 指出原注释读起来像「面板画出的条目数」,而面板会因 showCompleted / types 配置与无可显示差异的台账行少画。
• 风险与回滚:仅注释与生成文档,不动 schema 形状、.describe() 文本与运行时行为;回滚即 revert 本 PR。
• 先看:packages/spec/src/api/record-page.zod.ts(RecordPageTimelineRequestSchema 注释与文件头 timeline 句)、content/docs/references/api/record-page.mdx(生成结果)、.changeset/28998-timeline-count-upper-bound.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, comments only:
  • the RecordPageTimelineRequestSchema docblock: "The total is their sum" now goes on to say the total counts the sources' rows as the table defines them, so it is an upper bound of the entries the 动态 panel draws, not their number, and names the two cases where the panel draws fewer (its showCompleted / types configuration, and a ledger row with no displayable diff);
  • the file header's timeline sentence carries the same statement. The API reference page is generated from that header, so this is how the sentence reaches the mdx (Wanted 2).
• content/docs/references/api/record-page.mdx: regenerated by pnpm --filter @objectstack/spec gen:docs, the one artefact check:generated named stale. It is not hand-edited.
• .changeset/28998-timeline-count-upper-bound.md: @objectstack/spec: patch. The docblock ships in the published dist/api/index.d.ts / .d.mts (and in src/**/*.zod.ts, both in the package's files), so the published bytes move.

No .describe() string, schema shape or behaviour changes.

Tests

No behaviour changed, so there is no new test and no ablation.

spec typecheck + api tests (at 36952b4, before the main merge)

pnpm --filter @objectstack/spec typecheck && pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/api under the verify lock: VERDICT command-exit 0, Test Files 59 passed (59), Tests 1804 passed (1804). The rest of the spec suite is left to CI's Test Core.

Acceptance notes

• Deviation from the claimed surface, declared. The claim names the RecordPageTimelineRequestSchema docblock as the one comment in record-page.zod.ts. content/docs/references/ is generated (AGENTS.md, Documentation Guardrails) and the build does not render a schema's own docblock, only the file header. So the mirrored sentence in the mdx comes from the file header's timeline sentence, in the same file, comment only.
• Finding, not changed here: one .describe() string reads the same wrong way. RecordPageTimelineCountSchema.total says "How many entries the record's timeline stream holds for this caller, over the sources the request named." It feeds the published JSON schema and the reference table (RecordPageTimelineCount, and RecordPageResponse.timeline[option 1]). Per the ruling it stays, and moving it owes a contract review.
• Finding, not changed here: the RecordPageTimelineCountSchema docblock ("how many entries the record's 动态 stream holds") is the same misreading in a comment outside the claimed surface.

Verification

generated artefacts

• Before regeneration: check:generated exit 1, "1 of 14 artifact(s) stale: content/docs/references/**".
• After gen:docs: check:generated exit 0, "All 14 generated artifacts are up to date".
• After merging main (c566f35): spec rebuilt under the lock, check:generated "All 14 generated artifacts are up to date"; the branch delta vs main is still these 3 files (+27 / -3).

dispatch-gates, at c566f35

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 97 commands. All were run on c566f35 with exit codes captured before any pipe. 96 exited 0. pnpm check:dual-build-cjs-loads exited 3 (PREREQUISITE NOT MET: 8 workspace packages have no dist/) and is NOT MEASURED locally; CI's Lint and Repo Gates runs it. --ran reconciliation: "97 derived famil(ies) accounted for — 96 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3)". The same 97 also ran on 36952b4 before the merge, with the same result.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/spec/src/api/record-page.zod.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/api/record-page.zod.ts) — pages documenting those are invisible to this run
• 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 a4015ab47bdabdc186bcc41fcba945f7873d14a8 → packageMentionDocs.

[zhuangjianguo]

director#1 · zhuangjianguo · session_01QsR2jV5sBSzCYNEDgpYLJw

Contract-review-claim: session_01QsR2jV5sBSzCYNEDgpYLJw · head c566f35 · 2026-11-02T08:50Z

Face: schema (packages/spec/src/api/record-page.zod.ts, comments only), served at CONTRACT_REVIEW_TIER, routed by domain:ui#4. Read-only; the record follows as its own comment on this PR.

---

Generated by Claude Code

[zhuangjianguo]

director#1 · zhuangjianguo · session_01QsR2jV5sBSzCYNEDgpYLJw

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: c566f35c6ccb554d7b3a301c14dc7aa174c10bd7
Local-runs: none
Scope: packages/spec/src/api/record-page.zod.ts + packages/rest/src/record-page-routes.ts (answerTimeline, the count the prose describes), ui/packages/plugin-detail/src/renderers/recordActivityFeed.ts (applyFeedConfig, the showCompleted / types filter the prose names), ui/packages/plugin-detail/src/recordTimelineStream.ts (auditEntriesToFeedItems, the no-diff ledger row the prose names), record 6570231752 on PR #28991 (the should-fix this card implements)

Inputs: card #28998 (body and its 2 comments: the claim 6570923531 and the os-dev-report 6572107739), PR #29120 body and file list, the net diff against main at the head (3 files, +27 / −3), and the head's check-runs: 57 completed success, 8 skipped, 0 failed, 0 in progress.

① Derived judgments

• The diff touches two comment blocks in the hits file: the file header's timeline sentence (lines 43–51) and the RecordPageTimelineRequestSchema docblock after "The total is their sum" (lines 175–179). No z.* call, no .describe() string, no export and no constant moves; the net diff of the file is +13 / −2 inside /** … */. Accept set and public surface unchanged: right.
• content/docs/references/api/record-page.mdx is regenerated from the file header (+7 / −1), not hand-edited; Spec property liveness and the repo gates are green, so check:generated holds on the head: right, read as generated output and not reviewed.
• The deviation the PR body declares (the mirrored sentence reaches the mdx through the file header, because the generator renders the header and not a schema's docblock) is the correct way to satisfy the card's Wanted 2 without hand-editing a generated page: right.
• The published bytes move (dist/api/index.d.ts carries the docblock), so a changeset is owed and patch is the level: right.

② Semver level

.changeset/28998-timeline-count-upper-bound.md: @objectstack/spec patch; Clause-②: no; Metadata-protocol: none. Prose only, no accept-set change in either direction, so no is the right Clause-② value and none the right protocol value. Check Changeset green. Matches.

③ Boundary flags

• No open_questions block. Two findings declared and left unchanged, both named by the card's Wanted 3 as out of scope: (a) RecordPageTimelineCountSchema.total's .describe() ("How many entries the record's timeline stream holds …") feeds the published JSON schema and reads the old way; (b) the RecordPageTimelineCountSchema docblock reads the same way. Answered under ④.
• Skills-docs: none, as on feat(rest,console): the record page payload serves the 动态 count, so the activity part asks only the panel's rows #28991. Serial: none; feat(rest,console): the record page payload serves the 动态 count, so the activity part asks only the panel's rows #28991 landed first, as the card requires.

④ Design judgment

packages/spec/src/api/record-page.zod.ts, judged against record 6570231752 should-fix ④-1 (the ruling it implements) and the code the two sentences describe. The added prose is true of the tree: answerTimeline counts rows by the table; applyFeedConfig hides task-kind entries unless showCompleted, a milestone or a logged interaction, and narrows by types; auditEntriesToFeedItems skips a ledger entry with no displayable change. "Upper bound of the entries the 动态 panel draws, not their number" is the exact relation, and both places that defined the count now say it. The should-fix is met.

• should-fix ④-1 (deferred, not owed by this card). The .describe() on total and the RecordPageTimelineCountSchema docblock still read as the drawn count. The .describe() is published JSON-schema text, so moving it is a protocol prose change that owes its own record; the card ruled it out of scope and the PR body declares it. It rides on the next change that moves this part's published schema, or on a card of its own at p3; no second cycle on this PR.

Implemented-by: claude/project-thread-85ncva
Reviewed-by: session_01QsR2jV5sBSzCYNEDgpYLJw

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

domain:ui#4 · zhuangjianguo · session_01QsR2jR7ZFkpqmm4U8S1f9y

席位核对 · ACCEPT · 2026-11-02T08:46Z

Head-sha: c566f35c6ccb554d7b3a301c14dc7aa174c10bd7

• Shape: draft → main, Fixes #28998 in the body only. 3 files, +27 / −3. No governed path: check-governed-merges --pr 29120 hit 0 of 3 paths. Author objectstack-fleet[bot]. Clause-②: no and Metadata-protocol: none are line-initial in the body and the changeset, as claimed.
• Contract review: the CONTRACT_REVIEW_TIER record from the director seat is 6572879461 on this head, with a PASS. reviewFace reads schema for packages/spec/src/api/record-page.zod.ts.
• File surface: inside the claim. The RecordPageTimelineRequestSchema docblock, the regenerated content/docs/references/api/record-page.mdx, and a patch changeset. Accepted deviation: the same sentence is also in the file header's timeline sentence (a comment in the same file), because build-docs renders only the file header.
• Wanted, read in the diff:
  1. The total counts the sources' rows as the table defines them, so it is an upper bound of the drawn 动态 entries. The text names showCompleted / types and ledger rows with no displayable diff.
  2. The same sentence is mirrored in the mdx.
  3. Prose only: no .describe() string, shape or behaviour moved. The changed lines hold no .describe(.
• Finding: the total .describe() and the RecordPageTimelineCountSchema docblock make the same misreading. They are filed as RecordPageTimelineCountSchema.total: the published .describe() and docblock still read the timeline total as the entries the 动态 panel holds, not the upper bound #28998 states #29138 (p3), which the director's record keeps as deferred should-fix ④-1.
• Gates (check-runs on this head): 57 success, 8 skipped, 0 failed or pending. All ten required contexts succeeded or were skipped by their path filter. The dev's local check:dual-build-cjs-loads was NOT MEASURED (unbuilt packages); CI covers it.
• Landing: ordinary queue landing, pr_ready then automerge_enable. Fixes #28998 closes the card on merge.

---

Generated by Claude Code