@genesislcap/ai-assistant 15.19.0 → 15.19.1

package/src/state/persistence/diagnostics.test.ts

@@ -1,346 +0,0 @@
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import {
-  assembleDebugLog,
-  diagnosticsMessageKey,
-  type DiagnosticEntry,
-  withFreshMetaSnapshot,
-} from './diagnostics';
-
-// GENC-1351 §5.8: `assembleDebugLog` reassembles the forward-only diagnostics
-// stream back into the `{ readme, timeline, meta }` debug-log shape — timeline
-// sorted by timestamp, meta-snapshots pulled out with the latest winning.
-
-const README = ['read me'] as const;
-const Suite = createLogicSuite('assembleDebugLog');
-
-Suite('sorts the timeline by timestamp, tie-breaking event → turn → message', () => {
-  const entries: DiagnosticEntry[] = [
-    { kind: 'message', timestamp: '2026-01-01T00:00:02.000Z', content: 'later msg' },
-    { kind: 'turn', timestamp: '2026-01-01T00:00:01.000Z', turnIndex: '0' },
-    { kind: 'event', timestamp: '2026-01-01T00:00:01.000Z', type: 'turn.start' },
-    { kind: 'message', timestamp: '2026-01-01T00:00:01.000Z', content: 'first msg' },
-  ];
-  const { timeline } = assembleDebugLog(entries, README);
-  // Co-timestamped @ …01: event, then turn, then message; the …02 message last.
-  assert.equal(
-    timeline.map((e) => e.kind),
-    ['event', 'turn', 'message', 'message'],
-  );
-  assert.is(timeline[3].content, 'later msg');
-});
-
-Suite('pulls meta-snapshots out of the timeline and surfaces the latest as `meta`', () => {
-  const entries: DiagnosticEntry[] = [
-    { kind: 'meta-snapshot', timestamp: '2026-01-01T00:00:01.000Z', meta: { model: 'old' } },
-    { kind: 'message', timestamp: '2026-01-01T00:00:02.000Z', content: 'hi' },
-    { kind: 'meta-snapshot', timestamp: '2026-01-01T00:00:03.000Z', meta: { model: 'new' } },
-  ];
-  const { timeline, meta } = assembleDebugLog(entries, README);
-  assert.equal(
-    timeline.map((e) => e.kind),
-    ['message'],
-    'meta-snapshots do not leak into the timeline',
-  );
-  assert.equal(meta, { model: 'new' }, 'the newest meta-snapshot surfaces as top-level meta');
-});
-
-Suite('re-prepends the passed readme and tolerates an empty stream', () => {
-  const empty = assembleDebugLog([], README);
-  assert.is(empty.readme, README);
-  assert.equal(empty.timeline, []);
-  assert.is(empty.meta, undefined, 'no meta-snapshot → undefined meta');
-});
-
-Suite('reassembles two loads into one lifetime timeline (the stitch)', () => {
-  // Load 1's appended entries + load 2's — as loadDiagnostics would return them,
-  // in arbitrary order — stitch back chronologically.
-  const load2: DiagnosticEntry[] = [
-    { kind: 'message', timestamp: '2026-01-01T00:10:00.000Z', content: 'reload msg' },
-    { kind: 'meta-snapshot', timestamp: '2026-01-01T00:10:00.000Z', meta: { load: 2 } },
-  ];
-  const load1: DiagnosticEntry[] = [
-    { kind: 'message', timestamp: '2026-01-01T00:00:00.000Z', content: 'first msg' },
-    { kind: 'meta-snapshot', timestamp: '2026-01-01T00:00:00.000Z', meta: { load: 1 } },
-  ];
-  const { timeline, meta } = assembleDebugLog([...load2, ...load1], README);
-  assert.equal(
-    timeline.filter((e) => e.kind === 'message').map((e) => e.content),
-    ['first msg', 'reload msg'],
-    'messages ordered across loads regardless of input order',
-  );
-  assert.equal(meta, { load: 2 }, 'newest load’s meta-snapshot surfaces');
-});
-
-Suite('collapses exact-duplicate entries but keeps genuinely-distinct ones', () => {
-  // Two element instances (bubble + panel) can each append the same message, and a
-  // reload's second instance can re-append it — byte-identical copies. Two real
-  // `assistant.connected` (from two instances) differ by `index` and must be kept.
-  const msg: DiagnosticEntry = {
-    kind: 'message',
-    timestamp: '2026-01-01T00:00:01.000Z',
-    role: 'user',
-    content: 'hi',
-  };
-  const connA: DiagnosticEntry = {
-    kind: 'event',
-    timestamp: '2026-01-01T00:00:00.000Z',
-    type: 'assistant.connected',
-    index: 0,
-  };
-  const connB: DiagnosticEntry = { ...connA, index: 1 };
-  const { timeline } = assembleDebugLog([msg, connA, { ...msg }, connB, connA], README);
-  assert.is(timeline.filter((e) => e.kind === 'message').length, 1, 'identical message collapsed');
-  assert.is(
-    timeline.filter((e) => e.type === 'assistant.connected').length,
-    2,
-    'two distinct connects (different index) kept; the repeated connA collapsed',
-  );
-});
-
-Suite('lifts the newest snapshot’s session usage to the top of the log', () => {
-  // The four buckets + USD are the headline of a cost investigation, and `meta` is a
-  // large block to go digging in — so they surface at the top level. Same object, not a
-  // second derivation, and taken from the SAME snapshot that becomes `meta`.
-  const usage = {
-    costUsd: 1.25,
-    uncachedInputTokens: 1000,
-    cacheReadTokens: 9000,
-    cacheWriteTokens: 500,
-    outputTokens: 300,
-  };
-  const entries: DiagnosticEntry[] = [
-    {
-      kind: 'meta-snapshot',
-      timestamp: '2026-01-01T00:00:01.000Z',
-      meta: { context: { sessionUsage: { ...usage, costUsd: 0.01 } } },
-    },
-    {
-      kind: 'meta-snapshot',
-      timestamp: '2026-01-01T00:00:09.000Z',
-      meta: { context: { sessionUsage: usage } },
-    },
-  ];
-  assert.equal(assembleDebugLog(entries, README).sessionUsage, usage);
-});
-
-Suite('leaves session usage undefined when no snapshot carries it', () => {
-  // A stream with no meta-snapshot, or one written before the field existed. Absent
-  // rather than zeroed: "not recorded" must not read as "this session spent nothing".
-  assert.is(assembleDebugLog([], README).sessionUsage, undefined);
-  const noContext: DiagnosticEntry[] = [
-    { kind: 'meta-snapshot', timestamp: '2026-01-01T00:00:01.000Z', meta: { host: 'localhost' } },
-  ];
-  assert.is(assembleDebugLog(noContext, README).sessionUsage, undefined);
-});
-
-Suite('collapses the turn pair even when its rendered systemPrompt differs', () => {
-  // The pair is produced by two separate flushes, and `buildTimelineEntries` renders
-  // `systemPrompt` relative to the preceding snapshots — so if the snapshot holding the
-  // full prompt is evicted from the ring buffer between the two, the surviving turn
-  // renders its prompt in full where the earlier copy had the '<repeated>' marker. Any
-  // identity derived from the serialized entry breaks here and the log shows one model
-  // call as two turns, one unpriced. Identity is turnIndex + timestamp + agentName.
-  const unpriced: DiagnosticEntry = {
-    kind: 'turn',
-    turnIndex: '7',
-    timestamp: '2026-01-01T00:00:01.000Z',
-    agentName: 'Trade Operations',
-    systemPrompt: '<repeated — identical to turn 0>',
-    toolNames: [],
-  };
-  const priced: DiagnosticEntry = {
-    ...unpriced,
-    systemPrompt: 'the full prompt, now that turn 0 has been evicted',
-    usage: {
-      costUsd: 0.5,
-      uncachedInputTokens: 100,
-      cacheReadTokens: 0,
-      cacheWriteTokens: 0,
-      outputTokens: 20,
-    },
-  };
-  const turns = assembleDebugLog([unpriced, priced], README).timeline.filter(
-    (e) => e.kind === 'turn',
-  );
-  assert.is(turns.length, 1, 'still one model call');
-  assert.equal(turns[0].usage, priced.usage, 'and it is the priced copy');
-});
-
-Suite('keeps same-index turns from different loads and different sub-agents apart', () => {
-  // `turnIndex` restarts at '0' on every page load, so a lifetime log holds one turn '0'
-  // per load; two sub-agents invoked in one parent turn share the index prefix and are
-  // separated by `agentName` (see `forwardSubAgentSnapshots`).
-  const load1: DiagnosticEntry = {
-    kind: 'turn',
-    turnIndex: '0',
-    timestamp: '2026-01-01T00:00:01.000Z',
-    agentName: 'Booker',
-    toolNames: [],
-  };
-  const load2: DiagnosticEntry = { ...load1, timestamp: '2026-01-02T09:00:00.000Z' };
-  const sibling: DiagnosticEntry = { ...load1, turnIndex: '3-1', agentName: 'Planner' };
-  const cousin: DiagnosticEntry = { ...sibling, agentName: 'Grounding' };
-  const turns = assembleDebugLog([load1, load2, sibling, cousin], README).timeline.filter(
-    (e) => e.kind === 'turn',
-  );
-  assert.is(turns.length, 4, 'four distinct calls, none collapsed');
-});
-
-Suite('collapses the unpriced and priced copies of one turn onto the priced one', () => {
-  // A turn entry is persisted when it is created (before its model call) and again once
-  // `usage` is back-filled, so a stitched stream carries both. They are ONE model call
-  // and must read as one — with the cost, or the re-emit gained nothing.
-  const unpriced: DiagnosticEntry = {
-    kind: 'turn',
-    turnIndex: '0',
-    timestamp: '2026-01-01T00:00:01.000Z',
-    toolNames: [],
-  };
-  const priced: DiagnosticEntry = {
-    ...unpriced,
-    usage: {
-      costUsd: 0.5,
-      uncachedInputTokens: 100,
-      cacheReadTokens: 0,
-      cacheWriteTokens: 0,
-      outputTokens: 20,
-    },
-  };
-  for (const order of [
-    [unpriced, priced],
-    [priced, unpriced],
-  ]) {
-    const turns = assembleDebugLog(order, README).timeline.filter((e) => e.kind === 'turn');
-    assert.is(turns.length, 1, 'one turn, not two');
-    assert.equal(turns[0].usage, priced.usage, 'the priced copy wins regardless of stream order');
-  }
-});
-
-Suite('keeps two genuinely-different turns that differ only in usage', () => {
-  // The collapse keys on everything EXCEPT usage, so distinct calls stay distinct — they
-  // differ in timestamp (and turnIndex) whatever else they share.
-  const a: DiagnosticEntry = {
-    kind: 'turn',
-    turnIndex: '0',
-    timestamp: '2026-01-01T00:00:01.000Z',
-    toolNames: [],
-  };
-  const b: DiagnosticEntry = { ...a, turnIndex: '1', timestamp: '2026-01-01T00:00:02.000Z' };
-  const turns = assembleDebugLog([a, b], README).timeline.filter((e) => e.kind === 'turn');
-  assert.is(turns.length, 2);
-});
-
-Suite.run();
-
-// The download path's swap: a stored stream's `meta-snapshot`s replaced by an export-time
-// one. This is the fix for a SILENT bug — the persisted stream only re-appends that block
-// when the config signature changes, so a stitched lifetime log reported the totals frozen
-// at the session's first flush (near-zero spend against a transcript full of priced
-// messages) and nothing about it looked wrong.
-const FreshSuite = createLogicSuite('withFreshMetaSnapshot');
-
-const storedStream: DiagnosticEntry[] = [
-  {
-    kind: 'meta-snapshot',
-    timestamp: '2026-01-01T00:00:00.000Z',
-    meta: { context: { sessionUsage: { costUsd: 0.01 } } },
-    dedupSignature: 'cfg-1',
-  },
-  { kind: 'message', timestamp: '2026-01-01T00:00:01.000Z', role: 'user', content: 'hi' },
-  { kind: 'turn', turnIndex: '0', timestamp: '2026-01-01T00:00:02.000Z', toolNames: [] },
-  { kind: 'event', index: 0, timestamp: '2026-01-01T00:00:03.000Z', type: 'turn.end' },
-];
-
-const freshSnapshot: DiagnosticEntry = {
-  kind: 'meta-snapshot',
-  timestamp: '2026-01-01T02:00:00.000Z',
-  meta: {
-    context: {
-      sessionUsage: {
-        costUsd: 1.25,
-        uncachedInputTokens: 1000,
-        cacheReadTokens: 9000,
-        cacheWriteTokens: 500,
-        outputTokens: 300,
-      },
-    },
-  },
-  dedupSignature: 'cfg-1',
-};
-
-FreshSuite('reports the export-time totals, not the frozen stored ones', () => {
-  const log = assembleDebugLog(withFreshMetaSnapshot(storedStream, freshSnapshot), README);
-  assert.is(log.sessionUsage?.costUsd, 1.25, 'the fresh snapshot supplies the totals');
-  assert.is(log.sessionUsage?.cacheReadTokens, 9000);
-  assert.equal(log.meta, freshSnapshot.meta, 'and the whole meta block is the fresh one');
-});
-
-FreshSuite('keeps every non-snapshot entry', () => {
-  const timeline = assembleDebugLog(
-    withFreshMetaSnapshot(storedStream, freshSnapshot),
-    README,
-  ).timeline;
-  assert.equal(
-    timeline.map((e) => e.kind),
-    ['message', 'turn', 'event'],
-    'the conversation is untouched — only the snapshots are swapped',
-  );
-});
-
-FreshSuite('wins even when the stored snapshot claims a later time', () => {
-  // A stream written on another machine can carry a skewed clock, and reassembly keeps
-  // whichever snapshot claims the later timestamp — so the stale one must be REMOVED
-  // rather than out-timestamped.
-  const skewed: DiagnosticEntry[] = [
-    { ...storedStream[0], timestamp: '2099-01-01T00:00:00.000Z' },
-    ...storedStream.slice(1),
-  ];
-  const log = assembleDebugLog(withFreshMetaSnapshot(skewed, freshSnapshot), README);
-  assert.is(log.sessionUsage?.costUsd, 1.25);
-});
-
-FreshSuite.run();
-
-// GENC-1461: the reasoning/narration/answer split (GENC-1411) emits several messages from ONE model
-// response, so they share `timestamp` + `role` + `subAgentOf`. The message identity key must still
-// tell them apart — otherwise the forward-capture dedup treats them as one and drops all but the
-// first (a server generation's answer message vanished from the persisted download while its
-// reasoning survived).
-const KeySuite = createLogicSuite('diagnosticsMessageKey');
-
-KeySuite('gives co-timestamped split messages (reasoning vs answer) distinct keys', () => {
-  const base = {
-    kind: 'message' as const,
-    role: 'assistant',
-    timestamp: '2026-01-01T00:00:05.000Z',
-  };
-  const reasoning: DiagnosticEntry = { ...base, category: 'reasoning', content: 'thinking…' };
-  const answer: DiagnosticEntry = { ...base, content: 'the generated code' }; // no category = the answer
-  const kReasoning = diagnosticsMessageKey(reasoning);
-  const kAnswer = diagnosticsMessageKey(answer);
-  assert.ok(kReasoning, 'reasoning message has a key');
-  assert.ok(kAnswer, 'answer message has a key');
-  assert.not.equal(
-    kReasoning,
-    kAnswer,
-    'a reasoning and an answer split from one response must not collide',
-  );
-});
-
-KeySuite('still collapses a genuine re-append of the same message (same key)', () => {
-  const m: DiagnosticEntry = {
-    kind: 'message',
-    role: 'assistant',
-    timestamp: '2026-01-01T00:00:05.000Z',
-    category: 'reasoning',
-    content: 'thinking…',
-  };
-  // Two instances / a reload re-appending the SAME message must still share one key.
-  assert.equal(diagnosticsMessageKey(m), diagnosticsMessageKey({ ...m }));
-});
-
-KeySuite('returns null when the entry has no timestamp (treated as always-new)', () => {
-  assert.is(diagnosticsMessageKey({ kind: 'message', role: 'assistant' }), null);
-});
-
-KeySuite.run();

package/src/state/persistence/diagnostics.ts

@@ -1,220 +0,0 @@
-/**
- * Server-saved diagnostics (GENC-1351 §5.8) — the forward-only stream that lets
- * the debug log persist across a whole session lifetime, not just the current
- * page load. This module owns the *pure* pieces: the entry type and the
- * reassembly back into the `{ readme, sessionUsage, timeline, meta }` debug-log
- * shape. The element owns capture/cadence; the provider owns storage layout.
- *
- * @packageDocumentation
- */
-
-import type { AggregateUsage } from '@genesislcap/foundation-ai';
-
-/**
- * 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).
- *
- * @public
- */
-export interface DiagnosticEntry {
-  kind: 'message' | 'turn' | 'event' | 'meta-snapshot';
-  /** ISO timestamp — string-comparable, so it orders the stream chronologically. */
-  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
-   * delta to skip re-appending an unchanged block (GENC-1351 §5.8). Absent on other
-   * kinds and on pre-signature entries (the delta falls back to the full `meta` then).
-   */
-  dedupSignature?: string;
-  [key: string]: unknown;
-}
-
-/** The reassembled debug log — the exact shape `getDebugLog()` returns. @public */
-export 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;
-}
-
-/**
- * Stable identity for a message diagnostic entry — `timestamp::role::subAgentOf::category`.
- * Used by the forward-capture delta (skip already-emitted messages) and by the
- * restore watermark (skip messages already present in a prior load's stream).
- * `null` when the entry has no timestamp → treat as always-new. Shared so the
- * element's diagnostics capture and the `SessionPersister`'s restore watermark
- * compute identity identically (GENC-1351 §5.8/§5.10).
- *
- * `category` is part of the key because the reasoning/narration/answer split (GENC-1411) emits
- * SEVERAL messages from one model response — the thought summary, any interstitial narration, and
- * the answer/tool-call message — which share `timestamp` + `role` + `subAgentOf`. Keying on those
- * alone collapsed them to one, so the forward-capture dropped all but the first: a server
- * generation's answer message vanished from the persisted debug log while its reasoning survived
- * (GENC-1461). `category` is stable across a message's in-place annotation (only `toolCalls` change,
- * which is deliberately excluded), so a genuine re-append of the same message still dedups.
- *
- * @internal
- */
-export function diagnosticsMessageKey(entry: DiagnosticEntry): string | null {
-  return typeof entry.timestamp === 'string'
-    ? `${entry.timestamp}::${(entry.role as string) ?? ''}::${(entry.subAgentOf as string) ?? ''}::${(entry.category as string) ?? ''}`
-    : null;
-}
-
-/**
- * Identity of a `turn` entry — `turnIndex::timestamp::agentName`.
- *
- * Deliberately NOT the serialized entry, which two copies of the same call do not always
- * share. `buildTimelineEntries` renders `systemPrompt` *relative to the preceding
- * snapshots* (collapsing it to `<repeated — identical to turn N>` when it matches the
- * previous full prompt), so if the snapshot holding that full prompt is evicted from the
- * ring buffer between the unpriced flush and the priced one, the surviving turn renders
- * its prompt differently and the two serializations diverge. Both copies are in the
- * stream by then, so nothing would collapse them — and the log whose purpose is per-call
- * cost would show one model call as two turns, one of them unpriced.
- *
- * All three components are fixed when the snapshot is created and never re-derived.
- * `turnIndex` alone is not enough: it restarts at `'0'` on each page load, and a lifetime
- * log legitimately holds one turn `'0'` per load. `agentName` separates two sub-agents
- * invoked in the same parent turn, which share a `turnIndex` prefix by construction (see
- * `forwardSubAgentSnapshots`).
- */
-function turnIdentity(entry: DiagnosticEntry): string {
-  return `turn::${String(entry.turnIndex ?? '')}::${entry.timestamp ?? ''}::${String(entry.agentName ?? '')}`;
-}
-
-// Tie-break co-timestamped entries by cause → call → output (event, turn, message),
-// matching the original in-place `getDebugLog` sort.
-const KIND_RANK: Record<string, number> = { event: 0, turn: 1, message: 2 };
-// Any non-{event,turn,message} kind (shouldn't reach the timeline — meta-snapshots
-// are filtered out first) sorts last.
-const UNKNOWN_KIND_RANK = 99;
-
-/**
- * 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.
- *
- * 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 function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly string[]): DebugLog {
-  // Safety net for exact-duplicate entries: two element instances sharing one
-  // session (bubble + popped-out panel) can each append the same entry, and a
-  // reload's second instance can re-append restored history. Such copies are
-  // byte-identical, so collapse by serialized identity — genuinely-distinct entries
-  // (e.g. two real `assistant.connected` from two instances) differ in index /
-  // placement and are kept. (The shared cursor store prevents most of this at
-  // write time; this guards the read path regardless of what's in the stream.)
-  //
-  // A `turn` is identified by `turnIndex` + `timestamp` + `agentName` instead (see
-  // `turnIdentity`), so the unpriced copy a mid-call flush persisted and the priced copy
-  // that follows it collapse into ONE turn — the priced one — rather than reading as two
-  // model calls.
-  const seenAt = new Map<string, number>();
-  let latestMeta: DiagnosticEntry | undefined;
-  const timeline: DiagnosticEntry[] = [];
-  for (const entry of entries) {
-    if (entry.kind === 'meta-snapshot') {
-      if (!latestMeta || (entry.timestamp ?? '') >= (latestMeta.timestamp ?? '')) {
-        latestMeta = entry;
-      }
-      continue;
-    }
-    const id = entry.kind === 'turn' ? turnIdentity(entry) : JSON.stringify(entry);
-    const at = seenAt.get(id);
-    if (at !== undefined) {
-      // Same entry seen twice — keep the richer copy. `usage` on a turn is the only
-      // field that can arrive late, so it is the only upgrade there is to make.
-      if (entry.usage && !timeline[at].usage) timeline[at] = entry;
-      continue;
-    }
-    seenAt.set(id, timeline.length);
-    timeline.push(entry);
-  }
-  timeline.sort((a, b) => {
-    const ta = a.timestamp ?? '';
-    const tb = b.timestamp ?? '';
-    if (ta < tb) return -1;
-    if (ta > tb) return 1;
-    return (KIND_RANK[a.kind] ?? UNKNOWN_KIND_RANK) - (KIND_RANK[b.kind] ?? UNKNOWN_KIND_RANK);
-  });
-  // The session totals live inside the newest snapshot's `meta`, which is `unknown` by
-  // design (a provider stores these opaquely) — so this narrows just the one path it
-  // reads rather than typing the whole block.
-  const context = (latestMeta?.meta as { context?: { sessionUsage?: AggregateUsage } } | undefined)
-    ?.context;
-  return { readme, sessionUsage: context?.sessionUsage, timeline, meta: latestMeta?.meta };
-}
-
-/**
- * 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 function withFreshMetaSnapshot(
-  stored: readonly DiagnosticEntry[],
-  fresh: DiagnosticEntry,
-): DiagnosticEntry[] {
-  return [...stored.filter((e) => e.kind !== 'meta-snapshot'), fresh];
-}

package/src/state/persistence/index.ts

@@ -1,10 +0,0 @@
-export { PERSISTED_SESSION_VERSION } from './session-snapshot';
-export type { PersistedSession } from './session-snapshot';
-export { WebStorageSessionProvider } from './session-persistence-provider';
-export type {
-  SessionPersistenceProvider,
-  SessionPersistenceConfig,
-  SessionPreferences,
-} from './session-persistence-provider';
-export { assembleDebugLog, withFreshMetaSnapshot } from './diagnostics';
-export type { DiagnosticEntry, DebugLog } from './diagnostics';

package/src/state/persistence/persister-registry.ts

@@ -1,55 +0,0 @@
-import type { SessionPersister } from './session-persister';
-
-/**
- * Module-level registry of {@link SessionPersister}s keyed by session identity
- * string (GENC-1351 §5.10).
- *
- * A persister's lifetime is tied to the conversation session, not the DOM — like
- * the driver registry. The (up to two) element views that share a session (a
- * collapsed bubble + a popped-out panel) look up or create the ONE persister for
- * their key and delegate all restore-core persistence to it, so there is a single
- * save timer + carry-forward cache per session (no per-view double-writes/races).
- *
- * @internal
- */
-const persisterRegistry = new Map<string, SessionPersister>();
-
-/**
- * Returns the existing persister for `key`, or calls `factory` to create and
- * register a new one. First view to connect creates it; later views share it.
- */
-export function getOrCreatePersister(
-  key: string,
-  factory: () => SessionPersister,
-): SessionPersister {
-  const existing = persisterRegistry.get(key);
-  if (existing) return existing;
-  const persister = factory();
-  persisterRegistry.set(key, persister);
-  return persister;
-}
-
-/** Returns the existing persister for `key`, or `undefined`. */
-export function getPersister(key: string): SessionPersister | undefined {
-  return persisterRegistry.get(key);
-}
-
-/**
- * Removes the persister for `key` (explicit session teardown). Disposes it first
- * so its debounced save AND diagnostics timers are cancelled — otherwise a timer
- * scheduled by the outgoing session fires after the in-place switch and flushes the
- * NEW session's entries under the OLD key, corrupting its stream (GENC-1351 §5.12).
- */
-export function deletePersister(key: string): void {
-  persisterRegistry.get(key)?.dispose();
-  persisterRegistry.delete(key);
-}
-
-/**
- * Removes all entries. Exposed for test isolation only — not part of the public API.
- *
- * @internal
- */
-export function clearPersisterRegistry(): void {
-  persisterRegistry.clear();
-}