docs(spec): the record-page timeline total is an upper bound of the drawn 动态 entries

.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.

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

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