@morlay/session-rdb 0.0.21-alpha.7 → 0.0.21-alpha.9

package/src/index.ts

@@ -1,4 +1,5 @@
 import { Context } from "@deepseek-ai/cordis";
+import type { Volatile } from "@deepseek-ai/cosmokit";
 import z from "@deepseek-ai/schemastery";
 import { randomUUID } from "node:crypto";
 import { Pool } from "pg";
@@ -41,11 +42,13 @@ import { sessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
 import {
   type Backend,
   type BackendTx,
-  type EventCountBucket,
   type EventInsert,
+  type SessionCountBucket,
+  type SessionUsageBucket,
 } from "./backend.ts";
 import { WriteGuard } from "./write-guard.ts";
-import { repairReadView, rowToMeta, scanRows, toJsonlArtifact } from "./log.ts";
+import { repairReadView, rowToMeta, scanRows, toJsonlArtifact, usageRowOf } from "./log.ts";
+import type { EventUsageRow } from "./log.ts";
 import {
   DEFAULT_BUSY_TIMEOUT_MS,
   eventDimensions,
@@ -61,11 +64,16 @@ import { registerSessionDeletion } from "./deletion.ts";
 import { registerSessionExport } from "./export.ts";
 import { registerSessionGc } from "./gc.ts";
 import { registerSessionRows } from "./rows.ts";
-import { COUNTED_EVENT_TYPES, localDayKey, registerSessionUsage } from "./usage.ts";
+import {
+  COUNTED_EVENT_TYPES,
+  addActivityCount,
+  localDayKey,
+  registerSessionUsage,
+} from "./usage.ts";
 import type { UsageAggregate } from "./usage.ts";
 import { SessionQueryRdb } from "./session-query.ts";
 import { adoptLegacyRows, convertLegacyRows, isLegacyVersion } from "./legacy.ts";
-import { hasLegacyShape } from "./log.ts";
+import { needsShapeAdoption, sealOwnEvents } from "./log.ts";
 import { installStorageTakeover } from "./storage-takeover/index.ts";
 
 /** 一批事件里的最大时间：写路径据此推进会话行的「最后活动时间」。 */
@@ -122,25 +130,21 @@ export interface ProjectionCacheOptions {
 export type Config =
   | {
       type: "sqlite";
-
       path: string;
-
-      journalMode?: JournalMode;
-
-      busyTimeout?: number;
-
-      projectionCache?: ProjectionCacheOptions;
+      journalMode?: JournalMode | undefined;
+      busyTimeout?: number | undefined;
+      projectionCache?: ProjectionCacheOptions | undefined;
     }
   | {
       type: "postgres";
-
       connectionString: string;
-
-      schema?: string;
-
-      projectionCache?: ProjectionCacheOptions;
+      schema?: string | undefined;
+      projectionCache?: ProjectionCacheOptions | undefined;
     };
 
+/** schema 解析之后的形状：整段 Config 是 **volatile 稳定引用**（页面可编辑），读它要过 `.get()`。 */
+export type ResolvedConfig = Volatile<Config>;
+
 export type SessionDeletionErrorCode =
   | "SESSION_NOT_FOUND"
   | "SESSION_NOT_ARCHIVED"
@@ -484,40 +488,111 @@ class RdbSessionHandle implements SessionHandle {
   static readonly LIVE_WRITE_BATCH_MAX_DELAY_MS = 200;
 }
 
+/**
+ * 本地化说明：`description()` 的类型签名只声明 `string`，而 meta 本身接受 `Dict<string>`
+ * （`vendor/schemastery/src/index.ts` 的 `mergeDesc` 就是按字典合并的），所以这里只做一次类型放行。
+ */
+const localized = (text: { zh: string; en: string }): string => text as unknown as string;
+
+/** 投影 checkpoint 的写回节流：两个分支共用。 */
+const projectionCacheSchema = z
+  .object({
+    writeEveryEvents: z
+      .natural()
+      .min(1)
+      .default(DEFAULT_PROJECTION_WRITE_EVERY_EVENTS)
+      .description(
+        localized({
+          zh: "每累计这么多事件写回一次投影 checkpoint。",
+          en: "Write the projection checkpoint back after this many events.",
+        }),
+      ),
+    writeIntervalMs: z
+      .natural()
+      .min(1)
+      .default(DEFAULT_PROJECTION_WRITE_INTERVAL_MS)
+      .description(
+        localized({
+          zh: "距离上次写回超过这个间隔（毫秒）时也写一次。",
+          en: "Also write back when this many ms passed since the last one.",
+        }),
+      ),
+  })
+  .default({
+    writeEveryEvents: DEFAULT_PROJECTION_WRITE_EVERY_EVENTS,
+    writeIntervalMs: DEFAULT_PROJECTION_WRITE_INTERVAL_MS,
+  });
+
 export class SessionPersistenceRdb extends SessionPersistence {
   static inject = ["sessions"];
 
-  static Config: z<Config> = z.union([
-    z.object({
-      type: z.const("sqlite"),
-      path: z.string().required(),
-      journalMode: z.union(["wal", "delete", "truncate", "persist"] as const).default("wal"),
-      busyTimeout: z.number().step(1).min(0).default(DEFAULT_BUSY_TIMEOUT_MS),
-      projectionCache: z
-        .object({
-          writeEveryEvents: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_EVERY_EVENTS),
-          writeIntervalMs: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_INTERVAL_MS),
-        })
-        .default({
-          writeEveryEvents: DEFAULT_PROJECTION_WRITE_EVERY_EVENTS,
-          writeIntervalMs: DEFAULT_PROJECTION_WRITE_INTERVAL_MS,
-        }),
-    }),
-    z.object({
-      type: z.const("postgres"),
-      connectionString: z.string().required(),
-      schema: z.string().default("public"),
-      projectionCache: z
-        .object({
-          writeEveryEvents: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_EVERY_EVENTS),
-          writeIntervalMs: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_INTERVAL_MS),
-        })
-        .default({
-          writeEveryEvents: DEFAULT_PROJECTION_WRITE_EVERY_EVENTS,
-          writeIntervalMs: DEFAULT_PROJECTION_WRITE_INTERVAL_MS,
-        }),
-    }),
-  ]);
+  // 显式声明「输入 → 解析后」的形状：整段是 volatile，读它要过 `.get()`。union + volatile 的推断形状与手写类型
+  // 在可选性 / 索引签名上不完全对齐，所以这里断言一次，类型面由此固定。
+  static Config = z
+    .union([
+      z.object({
+        type: z.const("sqlite"),
+        path: z
+          .string()
+          .required()
+          .description(
+            localized({
+              zh: "SQLite 数据库文件路径；`:memory:` 是内存库（进程结束即丢）。",
+              en: "SQLite database file path; `:memory:` keeps it in memory and loses it with the process.",
+            }),
+          ),
+        journalMode: z
+          .union(["wal", "delete", "truncate", "persist"] as const)
+          .default("wal")
+          .description(
+            localized({
+              zh: "SQLite 日志模式；默认 wal（并发读最好）。",
+              en: "SQLite journal mode; `wal` by default (best concurrent reads).",
+            }),
+          ),
+        busyTimeout: z
+          .number()
+          .step(1)
+          .min(0)
+          .default(DEFAULT_BUSY_TIMEOUT_MS)
+          .description(
+            localized({
+              zh: "写锁冲突时的忙等超时（毫秒）。",
+              en: "Busy timeout in ms while a write lock is contended.",
+            }),
+          ),
+        projectionCache: projectionCacheSchema,
+      }),
+      z.object({
+        type: z.const("postgres"),
+        connectionString: z
+          .string()
+          .required()
+          .description(
+            localized({
+              zh: "PostgreSQL 连接串（含库名与凭证）。",
+              en: "PostgreSQL connection string (database and credentials).",
+            }),
+          ),
+        schema: z
+          .string()
+          .default("public")
+          .description(
+            localized({
+              zh: "库内的 schema 名；默认 public。",
+              en: "Schema name inside the database; `public` by default.",
+            }),
+          ),
+        projectionCache: projectionCacheSchema,
+      }),
+    ])
+    .description(
+      localized({
+        zh: "会话持久化后端：改这里的连接参数会在这一行重挂时生效（Loader 会重装被改的行）。",
+        en: "Session persistence backend: edits apply when this row is remounted (the Loader re-installs changed rows).",
+      }),
+    )
+    .volatile() as unknown as z<Config, ResolvedConfig>;
 
   override readonly name = "session-rdb";
 
@@ -534,9 +609,12 @@ export class SessionPersistenceRdb extends SessionPersistence {
   private readonly liveBuffers = new Map<SessionId, SessionEvent[]>();
   private readonly liveReady = new Map<SessionId, Promise<void>>();
 
+  /** 本次装配用的配置快照（整段 Config 是 volatile，重挂会给新的）。 */
+  readonly config: Config;
+
   constructor(
     ctx: Context,
-    public config: Config,
+    config: ResolvedConfig,
 
     injectedBackend?: Backend,
   ) {
@@ -544,7 +622,12 @@ export class SessionPersistenceRdb extends SessionPersistence {
 
     // 配置就是这一行的 config（cordis.patch.yml / profile patch，或设置页改它）；上游 0.1.7 的 settings
     // 不再提供 namespace section 覆盖，旧 `settings.yaml` 的 `session-rdb` 段由上游一次性导进同 id 的行。
-    this.backend = injectedBackend ?? createBackend(config);
+    //
+    // 整段 Config 标了 volatile（页面可编辑），而生效靠 **Loader 重挂这一行**（settings 写完经
+    // `reconcileProfilePatches` 让 Loader 重装受影响的 entry）：重挂会构造新实例、拿到新快照，所以这里取一次
+    // 就够，运行期不必反复读引用。
+    this.config = config.get();
+    this.backend = injectedBackend ?? createBackend(this.config);
     this.ready = this.init();
     this.installLiveRouting(ctx);
 
@@ -754,7 +837,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
     this.liveFailures.delete(id);
     this.liveDropWarned.delete(id);
     this.reuseEventIds.delete(id);
-    await this.deleteEventCounts(id);
+    await this.dropSessionStats(id);
   }
 
   /** GC 通道：回收已无桥接行引用的事件行（孤儿），返回删除行数。 */
@@ -778,7 +861,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
       this.liveFailures.delete(id);
       this.liveDropWarned.delete(id);
       this.reuseEventIds.delete(id);
-      await this.deleteEventCounts(id);
+      await this.dropSessionStats(id);
     }
     return deleted;
   }
@@ -854,10 +937,14 @@ export class SessionPersistenceRdb extends SessionPersistence {
     await this.ready;
     if (events.length === 0) return false;
 
+    // 本仓库自造的事件类型落库前补上 `ignorable` 信封：不补的话上游那道校验连写入都拒。
+    sealOwnEvents(events);
     validateStoredEvents(meta, [...events]);
 
     const reuse = this.reuseEventIds.get(meta.id);
     let confirmedHead = -1;
+    // 本批用量行由 `appendEventTail` 折好；事务成功后旁路据此累加 token 汇总表。
+    let usageRows: EventUsageRow[] = [];
     await this.backend.transaction(async (tx) => {
       if (tornTruncateTo !== undefined) {
         await tx.deleteBridgeTail(meta.id, tornTruncateTo);
@@ -872,16 +959,17 @@ export class SessionPersistenceRdb extends SessionPersistence {
       const head = await tx.getHead(meta.id);
 
       this.writeGuard.assertNoConcurrentWriter(meta.id, head.fHeadSequence);
-      const { headEventId, headSequence } = await appendEventTail(
+      const appended = await appendEventTail(
         tx,
         meta,
         events,
         { parentId: head.fHeadEventId, nextSeq: head.fHeadSequence + 1 },
         reuse,
       );
-      await tx.updateHead(meta.id, headEventId, headSequence);
+      usageRows = appended.usageRows;
+      await tx.updateHead(meta.id, appended.headEventId, appended.headSequence);
       await tx.bumpRevision(meta.id, maxEventTime(events));
-      confirmedHead = headSequence;
+      confirmedHead = appended.headSequence;
     });
     // 事务**成功之后**才丢掉复用映射：失败（并发写者校验、唯一键冲突等）时这份映射还没被消费，
     // 重试同一个 append 还要靠它复用父会话的事件行——提前删掉会让前缀事件行被重新插入一遍。
@@ -889,7 +977,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
 
     this.writeGuard.confirmHead(meta.id, confirmedHead);
     this.tracker.materialized(meta.id);
-    await this.recordEventCounts(meta.id, events);
+    await this.recordSessionStats(meta.id, events, usageRows);
     return true;
   }
 
@@ -959,7 +1047,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
     const { preserved, tornFrom } = scanRows(eventRows, options.fromSeq ?? 0);
     // 版本号不完全可信：写路径曾把回退视图的结果以当前版本号落库，于是库里存在「v4 标记 + 旧代形状」
     // 的行——在扫干净的边界之内再按内容判一次（撕裂尾部与坏行已经被 `scanRows` 丢掉了）。
-    if (hasLegacyShape(preserved)) {
+    if (needsShapeAdoption(preserved)) {
       const adopted = adoptLegacyRows(row, eventRows);
       return {
         meta: adopted.meta,
@@ -985,39 +1073,60 @@ export class SessionPersistenceRdb extends SessionPersistence {
   }
 
   /**
-   * 活动计数**旁路累加**：不在写事务里、失败只 warn——`t_event_counts` 是可销毁重建的派生表，
-   * 丢几次累加不影响可用性（需要时用 `rebuildEventCounts` 重算）。
+   * 统计衍生表的**旁路累加**：不在写事务里、失败只 warn——两张会话汇总表都是可销毁重建的
+   * 派生表，丢几次累加不影响可用性（需要时用 `rebuildSessionStats` 重算）。
+   * token 走写路径已折好的用量行，活动计数走本批事件类型。
    */
-  private async recordEventCounts(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
-    const buckets = eventCountBuckets(events);
-    if (buckets.length === 0) return;
-    try {
-      await this.backend.incrementEventCounts(id, buckets);
-    } catch (error: unknown) {
-      this.ctx.logger.warn(
-        `session-rdb: activity counts for "${id}" not updated (${describeError(error)})`,
-      );
+  private async recordSessionStats(
+    id: SessionId,
+    events: readonly SessionEvent[],
+    usageRows: readonly EventUsageRow[],
+  ): Promise<void> {
+    const usageBuckets = sessionUsageBuckets(usageRows);
+    if (usageBuckets.length > 0) {
+      try {
+        await this.backend.incrementSessionUsage(id, usageBuckets);
+      } catch (error: unknown) {
+        this.ctx.logger.warn(
+          `session-rdb: token usage for "${id}" not updated (${describeError(error)})`,
+        );
+      }
+    }
+    const countBuckets = sessionCountBuckets(events);
+    if (countBuckets.length > 0) {
+      try {
+        await this.backend.incrementSessionCounts(id, countBuckets);
+      } catch (error: unknown) {
+        this.ctx.logger.warn(
+          `session-rdb: activity counts for "${id}" not updated (${describeError(error)})`,
+        );
+      }
     }
   }
 
-  /** 重算一个会话的活动计数（rewind / fork 之后；best-effort，同 `recordEventCounts`）。 */
-  async rebuildEventCounts(id: SessionId): Promise<void> {
+  /**
+   * 重算一个会话的统计（rewind / fork 之后；best-effort，同 `recordSessionStats`）：
+   * 两张汇总表按会话重算，用量行的引用标记全量重算（引用可能跨会话消失）。
+   */
+  async rebuildSessionStats(id: SessionId): Promise<void> {
     try {
-      await this.backend.rebuildEventCounts(id);
+      await this.backend.rebuildSessionStats(id);
+      await this.backend.refreshEventUsageFlags();
     } catch (error: unknown) {
       this.ctx.logger.warn(
-        `session-rdb: activity counts for "${id}" not rebuilt (${describeError(error)})`,
+        `session-rdb: session stats for "${id}" not rebuilt (${describeError(error)})`,
       );
     }
   }
 
-  /** 会话删除时清掉它的活动计数行（best-effort）。 */
-  private async deleteEventCounts(id: SessionId): Promise<void> {
+  /** 会话删除时清掉它的汇总行，并重算用量行的引用标记（被删会话引用的行要立刻退出统计）。 */
+  private async dropSessionStats(id: SessionId): Promise<void> {
     try {
-      await this.backend.deleteEventCounts(id);
+      await this.backend.deleteSessionStats(id);
+      await this.backend.refreshEventUsageFlags();
     } catch (error: unknown) {
       this.ctx.logger.warn(
-        `session-rdb: activity counts for "${id}" not deleted (${describeError(error)})`,
+        `session-rdb: session stats for "${id}" not deleted (${describeError(error)})`,
       );
     }
   }
@@ -1039,13 +1148,15 @@ export class SessionPersistenceRdb extends SessionPersistence {
         { meta: log.meta, inheritedEventCount: SessionLogOffset(log.inheritedEventCount) },
         randomUUID(),
       );
-      const { headEventId, headSequence } = await appendEventTail(tx, log.meta, log.events, {
+      const appended = await appendEventTail(tx, log.meta, log.events, {
         parentId: "",
         nextSeq: 0,
       });
-      await tx.updateHead(id, headEventId, headSequence);
+      await tx.updateHead(id, appended.headEventId, appended.headSequence);
       await tx.bumpRevision(id, maxEventTime(log.events));
     });
+    // 重写换了事件行：被删掉的那批成了孤儿（引用标记要落回 0），本会话汇总按新事件重算。
+    await this.rebuildSessionStats(id);
   }
 
   async listSnapshots(
@@ -1374,15 +1485,41 @@ function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly Sessio
   );
 }
 
-/** 一批事件折成活动计数的桶：只数四种类型，按本地日聚合。 */
-function eventCountBuckets(events: readonly SessionEvent[]): EventCountBucket[] {
-  const counted = new Map<string, EventCountBucket>();
+/** 一批事件折成活动计数的桶：只数四种类型，按本地日聚合成四项。 */
+function sessionCountBuckets(events: readonly SessionEvent[]): SessionCountBucket[] {
+  const counted = new Map<string, SessionCountBucket>();
   for (const event of events) {
     if (!(COUNTED_EVENT_TYPES as readonly string[]).includes(event.type)) continue;
     const day = localDayKey(event.time);
-    const key = `${day}#${event.type}`;
-    const bucket = counted.get(key) ?? { day, type: event.type, count: 0 };
-    bucket.count += 1;
+    const bucket = counted.get(day) ?? { day, turns: 0, steps: 0, userInputs: 0, toolCalls: 0 };
+    addActivityCount(bucket, event.type, 1);
+    counted.set(day, bucket);
+  }
+  return [...counted.values()];
+}
+
+/** 一批用量行折成 token 桶：按「本地日 × 模型」聚合（模型未知落空串，与表口径一致）。 */
+function sessionUsageBuckets(usageRows: readonly EventUsageRow[]): SessionUsageBucket[] {
+  const counted = new Map<string, SessionUsageBucket>();
+  for (const row of usageRows) {
+    const provider = row.fProvider ?? "";
+    const model = row.fModel ?? "";
+    const key = `${row.fDay}#${provider}#${model}`;
+    const bucket = counted.get(key) ?? {
+      day: row.fDay,
+      provider,
+      model,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      reasoningTokens: 0,
+      totalTokens: 0,
+    };
+    bucket.inputTokens += row.fInputTokens;
+    bucket.outputTokens += row.fOutputTokens;
+    bucket.cacheReadTokens += row.fCacheReadTokens;
+    bucket.reasoningTokens += row.fReasoningTokens;
+    bucket.totalTokens += row.fTotalTokens;
     counted.set(key, bucket);
   }
   return [...counted.values()];
@@ -1424,11 +1561,12 @@ async function appendEventTail(
   events: readonly SessionEvent[],
   anchor: { parentId: string; nextSeq: number },
   reuse?: ReadonlyMap<number, string>,
-): Promise<{ headEventId: string; headSequence: number }> {
+): Promise<{ headEventId: string; headSequence: number; usageRows: EventUsageRow[] }> {
   let parentId = anchor.parentId;
   let nextSeq = anchor.nextSeq;
 
   const eventRows: EventInsert[] = [];
+  const usageRows: EventUsageRow[] = [];
   const bridgeRows: Array<{
     fSessionId: SessionId;
     fEventId: string;
@@ -1447,7 +1585,7 @@ async function appendEventTail(
         sourceEventSeqs?: unknown;
       };
       const { data, surfaceOp: _surfaceOp, sourceEventSeqs: _sourceEventSeqs, ...envelope } = raw;
-      eventRows.push({
+      const row: EventInsert = {
         fEventId: eventId,
         fParentId: parentId,
         fType: event.type,
@@ -1458,7 +1596,11 @@ async function appendEventTail(
         fEncoding: EVENT_ENCODING,
         fData: JSON.stringify({ ...envelope, data }),
         fCreatedAt: event.time,
-      });
+      };
+      eventRows.push(row);
+      // 用量行在这里一次折好（读侧维度一起物化），后端只负责插入，事务后旁路再据此累加汇总表。
+      const usageRow = usageRowOf(row, meta.origin === "subagent");
+      if (usageRow !== undefined) usageRows.push(usageRow);
     }
     const surfaceOp =
       (event as SessionEvent<SurfaceEventType>).surfaceOp === undefined
@@ -1473,13 +1615,13 @@ async function appendEventTail(
     parentId = eventId;
     nextSeq++;
   }
-  if (eventRows.length > 0) await tx.insertEvents(eventRows);
+  if (eventRows.length > 0) await tx.insertEvents(eventRows, usageRows);
   await tx.insertBridges(bridgeRows);
 
   if (events.some((event) => (event.type as string) === "session/title")) {
     await tx.refreshTitle(meta.id);
   }
-  return { headEventId: parentId, headSequence: nextSeq - 1 };
+  return { headEventId: parentId, headSequence: nextSeq - 1, usageRows };
 }
 
 export default SessionPersistenceRdb;

package/src/log.ts

@@ -4,6 +4,7 @@ import type { SessionFormatEvent, SessionFormatHeader } from "@deepseek-ai/dsh-s
 import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
 import type { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
 import type { EventRow, SessionRow } from "./backend.ts";
+import { localDayKey } from "./usage.ts";
 
 function normalizeSurfaceOp(value: unknown): SurfaceOp {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -469,15 +470,15 @@ export function renameLegacyPtcEvents(events: SessionEvent[]): void {
  *   （v4 起 system 消息只认这个 kind）；
  * - `tool/result` 的消息：v3 是 user 角色、结果块包在 `content[0]`；v4 是 `role: 'tool'` + 顶层
  *   `toolCallId` + `content` 就是结果块；
- * - 本仓库自己写过、上游已删除的事件类型（见 `LEGACY_OWN_EVENT_TYPES`）标 `ignorable: true`——v4 的
- *   校验对未知类型只接受可忽略信封。
+ * - **本仓库自造、上游不认识的事件类型**（见 `OWN_EVENT_TYPES`：历史遗留的与我们当前在写的）标
+ *   `ignorable: true`——v4 的校验对未知类型只接受可忽略信封。
  *
  * 只认这张白名单：**其它未知类型保持 fail loud**（那是「数据来自更新的 harness」的信号，不能吞掉）。
  */
 export function normalizeToCurrentShape(events: SessionEvent[]): void {
   for (const event of events) {
     const type = (event as { type: string }).type;
-    if (LEGACY_OWN_EVENT_TYPES.has(type)) {
+    if (OWN_EVENT_TYPES.has(type)) {
       (event as { ignorable?: true }).ignorable = true;
       continue;
     }
@@ -520,17 +521,45 @@ function liftToolResultMessage(message: unknown): void {
 }
 
 /**
- * 本仓库写过、后来连同机制一起删除的事件类型：读的时候标 `ignorable: true` 让校验跳过它们。
- * 新增历史类型时登记到这里——**不要**用「所有未知类型」代替（那会掩盖更新版本的未知事件）。
+ * 落库前给**本仓库自造的事件类型**补上 `ignorable: true` 信封。
+ *
+ * 上游的持久化校验（`validateStoredEvents`）只放行「已知类型」或「带可忽略信封的未知类型」，我们的类型
+ * 按构造就在已知表之外——不补的话连**写入**都会被拒（`appendBatch` 里那道校验）。上游 `Session.append`
+ * 没有承载这个信封的口子（第三个参数只服务 surface 事件），所以这一笔由持久化层补：canonical log 里的
+ * 形状不变，落库的那一份带上信封。
+ * @param events - 即将落库的批次（`materializeAppendBatch` 的 JSON 快照副本，可写）。
+ */
+export function sealOwnEvents(events: readonly SessionEvent[]): void {
+  for (const event of events) {
+    if (OWN_EVENT_TYPES.has((event as { type: string }).type)) {
+      (event as { ignorable?: true }).ignorable = true;
+    }
+  }
+}
+
+/**
+ * 本仓库自造、上游不认识的事件类型：读的时候标 `ignorable: true`，v4 的持久化校验才肯跳过它们
+ * （`validateStoredEvents` 只放行「已知类型」或「带可忽略信封的未知类型」）。
+ *
+ * 两类都在这张表里：
+ * - **历史遗留**：写过、后来连同机制一起删除的（`session-branch/version`）；
+ * - **当前在写**：本仓库的插件自己声明的事件类型（`session-mode/selected`）——上游的
+ *   `KNOWN_SESSION_EVENT_TYPES` 由上游仓库的声明生成，外部插件的事件按构造就在它之外。
+ *
+ * 新增自造事件类型时**必须**登记到这里，否则读路径 fail loud（真回归：`session-mode/selected` 漏登记，
+ * 会话打不开）。**不要**用「所有未知类型」代替（那会掩盖更新版本的未知事件——那种必须拒读）。
  */
-export const LEGACY_OWN_EVENT_TYPES: ReadonlySet<string> = new Set(["session-branch/version"]);
+export const OWN_EVENT_TYPES: ReadonlySet<string> = new Set([
+  "session-branch/version",
+  "session-mode/selected",
+]);
 
-/** 行里是否还带着旧代消息形状（`session-branch/version` 这类自造事件也算）——写路径曾把回退视图的结果
- * 以当前版本号落库，所以**版本号不可信**，读之前要按内容判一次。 */
-export function hasLegacyShape(events: readonly SessionEvent[]): boolean {
+/** 这批事件是否需要按当前形状归一（旧代消息形状，或尚未标 `ignorable` 的自造事件类型）——写路径曾把回退
+ * 视图的结果以当前版本号落库，所以**版本号不可信**，读之前要按内容判一次。 */
+export function needsShapeAdoption(events: readonly SessionEvent[]): boolean {
   for (const event of events) {
     const type = (event as { type: string }).type;
-    if (LEGACY_OWN_EVENT_TYPES.has(type)) return true;
+    if (OWN_EVENT_TYPES.has(type)) return true;
     if (type === "system/message") {
       const message = (event.data as unknown as Record<string, unknown>)["message"] as
         | Record<string, unknown>
@@ -716,12 +745,15 @@ export function titleOfEventData(data: string): string | undefined {
   }
 }
 
-/** 用量行的列（`t_event_usage`）。 */
+/** 用量行的列（`t_event_usage`）：读侧维度（本地日与两个归属标记）在写入时一起物化。 */
 export interface EventUsageRow {
   fEventId: string;
   fCreatedAt: number;
+  fDay: string;
   fProvider: string | null;
   fModel: string | null;
+  fReferenced: number;
+  fSubagent: number;
   fInputTokens: number;
   fOutputTokens: number;
   fCacheReadTokens: number;
@@ -740,15 +772,21 @@ function textField(value: unknown): string | null {
 /**
  * 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有）：写路径据此记录
  * `t_event_usage`，统计因此不必逐行解析 JSON。两种 `f_data` 结构（带信封 / 老格式）都认。
+ * 读侧维度一起物化：本地日由事件时间算，`f_referenced` 直接 1（这一批事件行与桥接行同事务，
+ * 提交即被引用），`f_subagent` 取写入它的会话是否子代理。
  * @param event - 待写入的事件行。
+ * @param subagent - 写入它的会话是否 `origin === 'subagent'`。
  * @returns 用量行，或该事件没有用量时的 undefined。
  */
-export function usageRowOf(event: {
-  fEventId: string;
-  fCreatedAt: number;
-  fType: string;
-  fData: string;
-}): EventUsageRow | undefined {
+export function usageRowOf(
+  event: {
+    fEventId: string;
+    fCreatedAt: number;
+    fType: string;
+    fData: string;
+  },
+  subagent: boolean,
+): EventUsageRow | undefined {
   if (event.fType !== "assistant/message") return undefined;
   let parsed: Record<string, unknown>;
   try {
@@ -763,8 +801,11 @@ export function usageRowOf(event: {
   const row: EventUsageRow = {
     fEventId: event.fEventId,
     fCreatedAt: event.fCreatedAt,
+    fDay: localDayKey(event.fCreatedAt),
     fProvider: textField(source?.["provider"]),
     fModel: textField(source?.["model"]),
+    fReferenced: 1,
+    fSubagent: subagent ? 1 : 0,
     fInputTokens: numericField((usage as Record<string, unknown>)["inputTokens"]),
     fOutputTokens: numericField((usage as Record<string, unknown>)["outputTokens"]),
     fCacheReadTokens: numericField((usage as Record<string, unknown>)["cacheReadTokens"]),