@genesislcap/ai-assistant 15.12.0 → 15.13.0

package/dist/ai-assistant.api.json

@@ -3583,7 +3583,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/ai-assistant!assembleDebugLog:function(1)",
-          "docComment": "/**\n * Reassemble diagnostic entries into the `{ readme, timeline, meta }` debug-log shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted by ISO `timestamp` (kind-rank tie-break). `meta` = the **newest** `meta-snapshot`'s block only — a \"state at export\" photo, matching the single-page log. The older snapshots are intentionally dropped: the per-turn evolution they would show is already in the timeline (`turn.agentSnapshot` + `context.updated` events), so keeping them would just repeat the bulky, near-static `agentSummary`. `readme` = the passed (current) constant. Pure — reused for both the live current-page log and the reassembled lifetime log stitched from the persisted stream, so both come out shape-identical.\n */\n",
+          "docComment": "/**\n * Reassemble diagnostic entries into the `{ readme, sessionUsage, timeline, meta }` debug-log shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted by ISO `timestamp` (kind-rank tie-break). `meta` = the **newest** `meta-snapshot`'s block only — a \"state at export\" photo, matching the single-page log. The older snapshots are intentionally dropped: the per-turn evolution they would show is already in the timeline (`turn.agentSnapshot` + `context.updated` events), so keeping them would just repeat the bulky, near-static `agentSummary`. `readme` = the passed (current) constant. `sessionUsage` = that same newest snapshot's `meta.context.sessionUsage`, lifted to the top level. Pure — reused for both the live current-page log and the reassembled lifetime log stitched from the persisted stream, so both come out shape-identical.\n *\n * NOTE for a caller stitching a STORED stream (a headless consumer harvesting its own lifetime log, say): the newest stored `meta-snapshot` is frozen at the last config-signature change, so `meta` and `sessionUsage` are as old as that unless you pass a fresh snapshot of your own — {@link withFreshMetaSnapshot} does exactly that, and the element's download path goes through it.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -6578,6 +6578,34 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!DebugLog#sessionUsage:member",
+              "docComment": "/**\n * Session usage — the four token buckets plus USD cost — lifted out of the newest `meta-snapshot`'s `meta.context.sessionUsage` so the headline spend figures sit at the top of an exported log rather than buried under the (large) `meta` block. The same object, not a second derivation.\n *\n * `undefined` when the stream carries no `meta-snapshot`, or one written before the field existed. Never re-derived from the timeline: the per-request costs the transports stamped are authoritative, and a ring-buffered timeline can have lost entries the total still legitimately counts.\n *\n * **As current as the snapshot it came from, which is not automatically \"now\".** The forward-capture delta only re-appends a `meta-snapshot` when the near-static config signature changes, so the newest STORED snapshot of a session whose config never changed is its first — with the totals frozen there. A caller reassembling a stored stream on its own therefore gets stale figures unless it appends an export-time snapshot first: see {@link withFreshMetaSnapshot}, which is what the assistant's own download path does. `meta.timestamp` against the newest timeline entry tells you which case you are holding.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "sessionUsage?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "sessionUsage",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!DebugLog#timeline:member",
@@ -6747,7 +6775,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry:interface",
-          "docComment": "/**\n * One entry in the diagnostics stream — the debug-log timeline-entry union (`message` / `turn` / `event`, as `getDebugLog()` builds) plus a point-in-time **`meta-snapshot`** carrying the export-time `meta` block (agent summary, context, active debug snapshot, …). Kept permissive: a provider stores and returns these opaquely, and reassembly reads only `kind`, `timestamp` (for ordering), and `meta` (on a snapshot).\n *\n * @public\n */\n",
+          "docComment": "/**\n * One entry in the diagnostics stream — the debug-log timeline-entry union (`message` / `turn` / `event`, as `getDebugLog()` builds) plus a point-in-time **`meta-snapshot`** carrying the export-time `meta` block (agent summary, context, active debug snapshot, …). Kept permissive: a provider stores and returns these opaquely, and reassembly reads only `kind`, `timestamp` (for ordering), `usage` (on a turn) and `meta` (on a snapshot).\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -6910,6 +6938,34 @@
                 "startIndex": 1,
                 "endIndex": 2
               }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry#usage:member",
+              "docComment": "/**\n * Present on a `turn` entry once its model call has returned and reported usage — the four token buckets plus USD for that one call (`TurnSnapshot.usage`).\n *\n * Read by the forward-capture delta as well as by readers: the turn entry is created *before* the call, so a flush that lands mid-call persists it without usage, and the delta re-emits it once (see `collectDiagnosticsDelta`) so the priced copy reaches the stream. {@link assembleDebugLog} then collapses the pair.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "usage?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "usage",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             }
           ],
           "extendsTokenRanges": []
@@ -8858,7 +8914,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#getDebugLog:member(1)",
-              "docComment": "/**\n * The live current-page debug log (`{ readme, timeline, meta }`).\n *\n * @public\n */\n",
+              "docComment": "/**\n * The live current-page debug log (`{ readme, sessionUsage, timeline, meta }`).\n *\n * @public\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -19101,6 +19157,88 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#model:member",
+              "docComment": "/**\n * Concrete model that ran this call (e.g. `'claude-sonnet-4-6'`) — the serving model where the provider reports one, else the model the resolved tier was configured with. Undefined when the provider exposes no `getStatus` and the transport stamped nothing.\n *\n * Recorded per call, so an agent whose `provider` selector varies by state (a tier switch between steps of a flow) has each step attributed to the model that actually ran it — without the reader having to join the turn to the message after it, which is impossible for a call that produced no message.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "model?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "model",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#provider:member",
+              "docComment": "/**\n * Vendor behind the resolved slot (`'anthropic'`, `'gemini'`, …), when the provider reports it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "provider?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AIProviderType",
+                  "canonicalReference": "@genesislcap/foundation-ai!AIProviderType:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "provider",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#providerName:member",
+              "docComment": "/**\n * Registry slot the provider resolved under for this call — a tier name like `'high'`/`'low'`, or the registry default's name. Kept alongside {@link TurnSnapshot.model} because they answer different questions: the slot is what the agent asked for, the model is what served it, and repointing a slot at a new model mid-session is only visible when both are recorded.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "providerName?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "providerName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#systemPrompt:member",
@@ -19290,6 +19428,34 @@
                 "startIndex": 1,
                 "endIndex": 2
               }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#usage:member",
+              "docComment": "/**\n * What this one LLM call cost — the four disjoint token buckets plus USD, derived from the response's usage by `messageUsage`. Back-filled when the response lands (the rest of the snapshot is captured *before* the call), so it is `undefined` while the call is in flight, on providers that report no usage, and on a call that threw rather than returning — a malformed-call/truncation/402 error carries no usage block, so any tokens the provider billed for it are not recoverable here.\n *\n * A snapshot is one **model call**, not one user turn: every tool-loop iteration and every retried attempt records its own. That makes this the only record of spend on an attempt that produced no message — a blank or refused response is billed and then discarded (see the empty-response retries), so summing the transcript alone under-reports the turn.\n *\n * For a call that DID produce a message, this is the same money as that message's `cost`/token fields, not additional money — never add turn usage to message usage.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "usage?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "usage",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             }
           ],
           "extendsTokenRanges": []
@@ -19892,6 +20058,82 @@
               "endIndex": 2
             }
           ]
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/ai-assistant!withFreshMetaSnapshot:function(1)",
+          "docComment": "/**\n * A stored diagnostics stream with its `meta-snapshot`s replaced by `fresh` — what to pass {@link assembleDebugLog} when reassembling a persisted stream for export.\n *\n * The stored snapshots are dropped rather than out-timestamped. `assembleDebugLog` keeps whichever claims the later time, and a stream written on another machine can carry a skewed clock; `fresh` is built from live state and so is the more current by construction. Only one snapshot ever survives reassembly, so the count is unchanged — though a snapshot taken while the driver is unwired (mid-popout) can leave `activeFoldStack`/`activeDebugSnapshot` unset where a stored one had them. The figures this exists for — the context block and `sessionUsage` — read the session store and element props, which survive an unwire.\n *\n * Pure, and separate from the element for that reason: the swap it performs is the fix for a silent bug (a lifetime log reporting near-zero spend against a transcript full of priced messages), so it needs to be testable without mounting anything.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function withFreshMetaSnapshot(stored: "
+            },
+            {
+              "kind": "Content",
+              "text": "readonly "
+            },
+            {
+              "kind": "Reference",
+              "text": "DiagnosticEntry",
+              "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "[]"
+            },
+            {
+              "kind": "Content",
+              "text": ", fresh: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DiagnosticEntry",
+              "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "DiagnosticEntry",
+              "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "[]"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/state/persistence/diagnostics.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 7,
+            "endIndex": 9
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "stored",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 4
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "fresh",
+              "parameterTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "withFreshMetaSnapshot"
         }
       ]
     }

package/dist/ai-assistant.d.ts

@@ -766,16 +766,23 @@ export declare const ANIMATION_DEFS: {
 };
 
 /**
- * Reassemble diagnostic entries into the `{ readme, timeline, meta }` debug-log
- * shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted
+ * Reassemble diagnostic entries into the `{ readme, sessionUsage, timeline, meta }`
+ * debug-log shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted
  * by ISO `timestamp` (kind-rank tie-break). `meta` = the **newest** `meta-snapshot`'s
  * block only — a "state at export" photo, matching the single-page log. The older
  * snapshots are intentionally dropped: the per-turn evolution they would show is
  * already in the timeline (`turn.agentSnapshot` + `context.updated` events), so
  * keeping them would just repeat the bulky, near-static `agentSummary`. `readme` =
- * the passed (current) constant. Pure — reused for both the live current-page log
- * and the reassembled lifetime log stitched from the persisted stream, so both
- * come out shape-identical.
+ * the passed (current) constant. `sessionUsage` = that same newest snapshot's
+ * `meta.context.sessionUsage`, lifted to the top level. Pure — reused for both the
+ * live current-page log and the reassembled lifetime log stitched from the persisted
+ * stream, so both come out shape-identical.
+ *
+ * NOTE for a caller stitching a STORED stream (a headless consumer harvesting its own
+ * lifetime log, say): the newest stored `meta-snapshot` is frozen at the last
+ * config-signature change, so `meta` and `sessionUsage` are as old as that unless you
+ * pass a fresh snapshot of your own — {@link withFreshMetaSnapshot} does exactly that,
+ * and the element's download path goes through it.
  */
 export declare function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly string[]): DebugLog;
 
@@ -1754,6 +1761,10 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
      * before each LLM call — that's the latest point where the prompt, tool
      * surface, and agent state line up with what the model is about to see.
+     *
+     * Returns the pushed object so the caller can back-fill what only the response
+     * knows (`usage`). Mutating it after the fact is safe whether or not the ring
+     * buffer has since evicted it — an evicted snapshot is simply no longer exported.
      */
     private recordTurnSnapshot;
     /**
@@ -2150,6 +2161,27 @@ export declare function createToolFold(config: {
 /** The reassembled debug log — the exact shape `getDebugLog()` returns. @public */
 export declare interface DebugLog {
     readme: readonly string[];
+    /**
+     * Session usage — the four token buckets plus USD cost — lifted out of the newest
+     * `meta-snapshot`'s `meta.context.sessionUsage` so the headline spend figures sit at
+     * the top of an exported log rather than buried under the (large) `meta` block. The
+     * same object, not a second derivation.
+     *
+     * `undefined` when the stream carries no `meta-snapshot`, or one written before the
+     * field existed. Never re-derived from the timeline: the per-request costs the
+     * transports stamped are authoritative, and a ring-buffered timeline can have lost
+     * entries the total still legitimately counts.
+     *
+     * **As current as the snapshot it came from, which is not automatically "now".** The
+     * forward-capture delta only re-appends a `meta-snapshot` when the near-static config
+     * signature changes, so the newest STORED snapshot of a session whose config never
+     * changed is its first — with the totals frozen there. A caller reassembling a stored
+     * stream on its own therefore gets stale figures unless it appends an export-time
+     * snapshot first: see {@link withFreshMetaSnapshot}, which is what the assistant's own
+     * download path does. `meta.timestamp` against the newest timeline entry tells you
+     * which case you are holding.
+     */
+    sessionUsage?: AggregateUsage;
     timeline: DiagnosticEntry[];
     meta: unknown;
 }
@@ -2213,7 +2245,7 @@ export declare function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): Agen
  * **`meta-snapshot`** carrying the export-time `meta` block (agent summary,
  * context, active debug snapshot, …). Kept permissive: a provider stores and
  * returns these opaquely, and reassembly reads only `kind`, `timestamp` (for
- * ordering), and `meta` (on a snapshot).
+ * ordering), `usage` (on a turn) and `meta` (on a snapshot).
  *
  * @public
  */
@@ -2223,6 +2255,16 @@ export declare interface DiagnosticEntry {
     timestamp?: string;
     /** Present on `meta-snapshot` entries: the export-time `meta` block. */
     meta?: unknown;
+    /**
+     * Present on a `turn` entry once its model call has returned and reported usage —
+     * the four token buckets plus USD for that one call (`TurnSnapshot.usage`).
+     *
+     * Read by the forward-capture delta as well as by readers: the turn entry is
+     * created *before* the call, so a flush that lands mid-call persists it without
+     * usage, and the delta re-emits it once (see `collectDiagnosticsDelta`) so the
+     * priced copy reaches the stream. {@link assembleDebugLog} then collapses the pair.
+     */
+    usage?: AggregateUsage;
     /**
      * Present on `meta-snapshot` entries: a stable signature of the near-static config
      * (excludes volatile timestamp/context/debug-snapshot), used by the forward-capture
@@ -3732,7 +3774,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
     toggleShowNarration(): void;
     toggleShowAgentSwitchIndicator(): void;
     setEnabledAnimations(animations: AiAssistantAnimation[]): void;
-    /** The live current-page debug log (`{ readme, timeline, meta }`). @public */
+    /** The live current-page debug log (`{ readme, sessionUsage, timeline, meta }`). @public */
     getDebugLog(): DebugLog;
     /**
      * Build the current page's diagnostic entries (GENC-1351 §5.8) — the debug-log
@@ -3743,6 +3785,17 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * been appended to the persisted stream.
      */
     private buildDiagnosticEntries;
+    /**
+     * The single `meta-snapshot` entry for right now — the export-time `meta` block
+     * (agent summary, active prompt/state, context + cost) plus the `dedupSignature`
+     * the forward-capture delta keys on.
+     *
+     * Separate from `buildDiagnosticEntries` because the download path needs a
+     * FRESH one on its own: the persisted stream only re-appends this block when the
+     * near-static config changes, so the newest stored snapshot's volatile half — the
+     * `context` figures especially — is typically frozen at the session's first flush.
+     */
+    private buildMetaSnapshot;
     downloadDebugLog(): Promise<void>;
     /**
      * The log to download (GENC-1351 §5.8). When the provider persists diagnostics,
@@ -3752,6 +3805,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * chat" — diagnostics are a forensic stream keyed on provider capability, not on
      * whether the *chat* is remembered (like preferences). Falls back to the live
      * current-page log when diagnostics isn't available or the fetch fails.
+     *
+     * The stored `meta-snapshot`s are replaced by a fresh one (`withFreshMetaSnapshot`)
+     * before reassembly. The persisted stream only re-appends that block when the
+     * near-static config signature changes (see `collectDiagnosticsDelta`), so on a session
+     * whose config never changes the newest STORED snapshot is the first one — its
+     * `context` half (session cost/usage, context tokens, live agent state) frozen seconds
+     * into the session, which is how a lifetime log came out reporting near-zero spend
+     * against a transcript full of priced messages.
      */
     private buildDownloadLog;
     /**
@@ -5127,6 +5188,46 @@ export declare interface TurnSnapshot {
     agentLabel?: string;
     /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
     agentSnapshot?: unknown;
+    /**
+     * Concrete model that ran this call (e.g. `'claude-sonnet-4-6'`) — the serving model
+     * where the provider reports one, else the model the resolved tier was configured
+     * with. Undefined when the provider exposes no `getStatus` and the transport stamped
+     * nothing.
+     *
+     * Recorded per call, so an agent whose `provider` selector varies by state (a tier
+     * switch between steps of a flow) has each step attributed to the model that actually
+     * ran it — without the reader having to join the turn to the message after it, which
+     * is impossible for a call that produced no message.
+     */
+    model?: string;
+    /**
+     * Registry slot the provider resolved under for this call — a tier name like
+     * `'high'`/`'low'`, or the registry default's name. Kept alongside {@link
+     * TurnSnapshot.model} because they answer different questions: the slot is what the
+     * agent asked for, the model is what served it, and repointing a slot at a new model
+     * mid-session is only visible when both are recorded.
+     */
+    providerName?: string;
+    /** Vendor behind the resolved slot (`'anthropic'`, `'gemini'`, …), when the provider reports it. */
+    provider?: AIProviderType;
+    /**
+     * What this one LLM call cost — the four disjoint token buckets plus USD, derived
+     * from the response's usage by `messageUsage`. Back-filled when the response lands
+     * (the rest of the snapshot is captured *before* the call), so it is `undefined`
+     * while the call is in flight, on providers that report no usage, and on a call that
+     * threw rather than returning — a malformed-call/truncation/402 error carries no usage
+     * block, so any tokens the provider billed for it are not recoverable here.
+     *
+     * A snapshot is one **model call**, not one user turn: every tool-loop iteration and
+     * every retried attempt records its own. That makes this the only record of spend on
+     * an attempt that produced no message — a blank or refused response is billed and
+     * then discarded (see the empty-response retries), so summing the transcript alone
+     * under-reports the turn.
+     *
+     * For a call that DID produce a message, this is the same money as that message's
+     * `cost`/token fields, not additional money — never add turn usage to message usage.
+     */
+    usage?: AggregateUsage;
 }
 
 /**
@@ -5222,4 +5323,23 @@ export declare class WebStorageSessionProvider implements SessionPersistenceProv
     savePreferences(sessionKey: string, preferences: SessionPreferences): Promise<void>;
 }
 
+/**
+ * A stored diagnostics stream with its `meta-snapshot`s replaced by `fresh` — what to
+ * pass {@link assembleDebugLog} when reassembling a persisted stream for export.
+ *
+ * The stored snapshots are dropped rather than out-timestamped. `assembleDebugLog` keeps
+ * whichever claims the later time, and a stream written on another machine can carry a
+ * skewed clock; `fresh` is built from live state and so is the more current by
+ * construction. Only one snapshot ever survives reassembly, so the count is unchanged —
+ * though a snapshot taken while the driver is unwired (mid-popout) can leave
+ * `activeFoldStack`/`activeDebugSnapshot` unset where a stored one had them. The figures
+ * this exists for — the context block and `sessionUsage` — read the session store and
+ * element props, which survive an unwire.
+ *
+ * Pure, and separate from the element for that reason: the swap it performs is the fix
+ * for a silent bug (a lifetime log reporting near-zero spend against a transcript full of
+ * priced messages), so it needs to be testable without mounting anything.
+ */
+export declare function withFreshMetaSnapshot(stored: readonly DiagnosticEntry[], fresh: DiagnosticEntry): DiagnosticEntry[];
+
 export { }