docs(spec): the record-page timeline total's published description reads it as an upper bound of the drawn entries

.changeset/29138-timeline-total-describe.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': patch
+'@object-ui/types': patch
+---
+
+docs(spec): the record-page `timeline` total's published description reads it as an upper bound of the drawn 动态 entries
+
+Clause-②: no
+Metadata-protocol: none
+
+`RecordPageTimelineCountSchema.total`'s `.describe()`, which ships in the published JSON schema and the API reference, and the schema's docblock now say what the `RecordPageTimelineRequestSchema` docblock 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. 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. Description text only: no key, type, bound, default or export changes, and no behaviour changes.
+
+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, and the panel draws fewer in the same two cases. Comment only: no type, member or export changes.

content/docs/references/api/record-page.mdx

@@ -548,7 +548,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **total** | `integer` | ✅ | How many entries the record's timeline stream holds for this caller, over the sources the request named. |
+| **total** | `integer` | ✅ | The rows of the sources the request named, counted as this caller may read them: an upper bound of the entries the timeline 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. |
 
 ### Nested Shape: `RecordPageResponse.timeline[option 2]`
 
@@ -596,7 +596,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **total** | `integer` | ✅ | How many entries the record's timeline stream holds for this caller, over the sources the request named. |
+| **total** | `integer` | ✅ | The rows of the sources the request named, counted as this caller may read them: an upper bound of the entries the timeline 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. |
 
 
 ---

packages/spec/src/api/record-page.zod.ts

@@ -313,10 +313,18 @@ export const RecordPageStreamRowsSchema = lazySchema(() => z.object({
 export type RecordPageStreamRows = z.input<typeof RecordPageStreamRowsSchema>;
 export type RecordPageStreamRowsParsed = z.infer<typeof RecordPageStreamRowsSchema>;
 
-/** [#28737] The `timeline` part: how many entries the record's 动态 stream holds. */
+/**
+ * [#28737] The `timeline` part: the size of the record's 动态 stream, counted
+ * by the reads `RecordPageTimelineRequestSchema` names, as the caller. 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.
+ */
 export const RecordPageTimelineCountSchema = lazySchema(() => z.object({
   total: z.number().int().min(0).describe(
-    'How many entries the record\'s timeline stream holds for this caller, over the sources the request named.',
+    'The rows of the sources the request named, counted as this caller may read them: an upper bound of the entries the timeline 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.',
   ),
 }).strict());
 export type RecordPageTimelineCount = z.input<typeof RecordPageTimelineCountSchema>;

ui/packages/types/src/data.ts

@@ -423,9 +423,12 @@ export interface RecordPagePayload {
   /** The record's newest attachments and their count, or their read's refusal (objectstack#28470). */
   attachments?: { total: number; records: Record<string, any>[] } | { error: RecordPagePartRefusal };
   /**
-   * How many entries the record's 动态 stream holds over the sources the
-   * request named (objectstack#28737), or the refusal of a comment or
-   * activity read.
+   * The size of the record's 动态 stream over the sources the request named
+   * (objectstack#28737), or the refusal of a comment or activity read. The
+   * total counts the sources' rows, 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.
    */
   timeline?: { total: number } | { error: RecordPagePartRefusal };
 }