From 83c123c2dd3795d275171c3c18171e4b6e8e00b2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 06:47:18 +0000
Subject: [PATCH 1/2] =?UTF-8?q?docs(spec):=20the=20record-page=20timeline?=
 =?UTF-8?q?=20total=20is=20an=20upper=20bound=20of=20the=20drawn=20?=
 =?UTF-8?q?=E5=8A=A8=E6=80=81=20entries?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude-Session: https://claude.ai/code/session_01QsR2jRs3fMDRLr3zkuDuVo
Co-authored-by: Claude <noreply@anthropic.com>
---
 packages/spec/src/api/record-page.zod.ts | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/spec/src/api/record-page.zod.ts b/packages/spec/src/api/record-page.zod.ts
index 1eec560f183..7a11240da19 100644
--- a/packages/spec/src/api/record-page.zod.ts
+++ b/packages/spec/src/api/record-page.zod.ts
@@ -43,7 +43,12 @@ import type { SysActivityBuiltinType } from '../data/feed.zod';
  * their own routes. [#28737] The `timeline` part is the size of the record's
  * 动态 stream — the comments, the activity and the field changes it merges —
  * counted by those reads as the caller (`RecordPageTimelineRequestSchema`), so
- * a page draws the stream's count without holding every row of it. Object permissions, row-level security, sharing and
+ * a page draws the stream's count without holding every row of it. The total
+ * counts the sources' rows as that schema's table defines them, so it is an
+ * upper bound of the entries the 动态 panel draws, not their number. The panel
+ * draws fewer where its `showCompleted` / `types` configuration filters entries
+ * out, and where a ledger row has no displayable diff and so draws no entry.
+ * Object permissions, row-level security, sharing and
  * field-level security therefore apply exactly as they apply to those reads.
  * A part whose read refuses carries that refusal in place of an answer — a
  * related list the caller may not read carries neither a count nor rows — and
@@ -167,7 +172,11 @@ export type RecordPageActivityRequestParsed = z.infer<typeof RecordPageActivityR
  * | `fieldChanges` | `sys_audit_log` where `object_name` = `{object}`, `record_id` = `{id}` and `action` is a    |
  * |                | write (`create`, `update`, `delete`)                                                         |
  *
- * The total is their sum. A source this deployment does not serve (its read
+ * The total is their sum: it counts the sources' rows as this table defines
+ * them, so it is an upper bound of the entries the 动态 panel draws, not their
+ * number. The panel draws fewer where its `showCompleted` / `types`
+ * configuration filters entries out, and where a ledger row has no
+ * displayable diff and so draws no entry. A source this deployment does not serve (its read
  * answers `OBJECT_NOT_FOUND`) holds no entry, as the page reads such a stream
  * as an empty one. The field changes are the history the stream merges only
  * where the caller may read it: a refused `sys_audit_log` read counts none, as

From 36952b45c256361c10d8067d5c68ff9870186a59 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 06:54:11 +0000
Subject: [PATCH 2/2] docs(spec): regenerate the record-page API reference and
 add the changeset

Claude-Session: https://claude.ai/code/session_01QsR2jRs3fMDRLr3zkuDuVo
Co-authored-by: Claude <noreply@anthropic.com>
---
 .changeset/28998-timeline-count-upper-bound.md | 10 ++++++++++
 content/docs/references/api/record-page.mdx    |  7 ++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/28998-timeline-count-upper-bound.md

diff --git a/.changeset/28998-timeline-count-upper-bound.md b/.changeset/28998-timeline-count-upper-bound.md
new file mode 100644
index 00000000000..c35389d312b
--- /dev/null
+++ b/.changeset/28998-timeline-count-upper-bound.md
@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the record-page `timeline` total is documented as an upper bound of the entries the 动态 panel draws
+
+Clause-②: no
+Metadata-protocol: none
+
+The `RecordPageTimelineRequestSchema` docblock, and the record-page file header that the API reference page is generated from, now say what the `timeline` total counts: the sources' rows as the schema's table defines them. That makes it an upper bound of the entries the 动态 panel draws, not their number. The panel draws fewer where its `showCompleted` / `types` configuration filters entries out, and where a ledger row has no displayable diff. Prose only: no schema shape, `.describe()` text or behaviour changes.
diff --git a/content/docs/references/api/record-page.mdx b/content/docs/references/api/record-page.mdx
index a8ccdcc3153..69f69e145b7 100644
--- a/content/docs/references/api/record-page.mdx
+++ b/content/docs/references/api/record-page.mdx
@@ -42,7 +42,12 @@ and how many rows. Paging further, posting, reacting and uploading keep
 their own routes. [#28737] The `timeline` part is the size of the record's
 动态 stream — the comments, the activity and the field changes it merges —
 counted by those reads as the caller (`RecordPageTimelineRequestSchema`), so
-a page draws the stream's count without holding every row of it. Object permissions, row-level security, sharing and
+a page draws the stream's count without holding every row of it. The total
+counts the sources' rows as that schema's table defines them, so it is an
+upper bound of the entries the 动态 panel draws, not their number. The panel
+draws fewer where its `showCompleted` / `types` configuration filters entries
+out, and where a ledger row has no displayable diff and so draws no entry.
+Object permissions, row-level security, sharing and
 field-level security therefore apply exactly as they apply to those reads.
 A part whose read refuses carries that refusal in place of an answer — a
 related list the caller may not read carries neither a count nor rows — and