@qjp88995/agent-runtime 0.1.0 → 0.1.2

package/src/testing/contracts.ts

@@ -1,6 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { describe, expect, it } from 'vitest';
 
+import type {
+  ConversationStore,
+  InboxItem,
+} from '../ports/conversation-store.js';
 import type {
   SessionLock,
   SubagentAwaitLease,
@@ -20,6 +24,7 @@ import type {
   VendorFileRecord,
 } from '../ports/vendor-file-cache.js';
 import type { AgentEvent } from '../schema/agent-event.js';
+import { COMPACTION_CHECKPOINT_KIND } from '../schema/index.js';
 
 /**
  * 端口的契约用例：进程内实现与各适配包（Redis 等）跑同一套，保证换实现不换语义。
@@ -57,6 +62,48 @@ function withImpl<T extends object>(
 
 const id = () => randomUUID();
 
+/**
+ * 宿主库的建行办法。数据库实现的表通常有外键与约束（消息、问题、跑次指向会话，问题指向
+ * 用户，子会话指向父跑次），契约用例里的这些 id 就不能是随机串——由宿主给出建一行、
+ * 返回 id 的办法，清理也归宿主（例如在 `afterAll` 里删掉自己建过的行）。
+ *
+ * 全部可选，缺省是随机 uuid 与示例值（进程内实现、无外键的后端）。
+ */
+export interface ContractFixtures {
+  /** 建一个根会话，返回 id。 */
+  rootSession?(): Promise<string>;
+  /** 建一个用户，返回 id。 */
+  user?(): Promise<string>;
+  /** 在这个会话里建一条跑次，返回 id（子会话的 `parentRunId` 指向它）。 */
+  run?(sessionId: string): Promise<string>;
+  /**
+   * `RunOpenInput.attrs`：宿主把附加信息存成列、列上有非空或 CHECK 约束时，给一组能落库的值。
+   */
+  runAttrs?: Readonly<Record<string, unknown>>;
+  /** `NewSubSession.attrs`：要能**原样读回**（用例按 `toMatchObject` 比）。缺省 `{ a: 1 }`。 */
+  sessionAttrs?: Readonly<Record<string, unknown>>;
+  /** `NewSubSession.metadata`：同上，要能原样读回。缺省 `{ k: 'v' }`。 */
+  sessionMetadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface ContractOptions {
+  fixtures?: ContractFixtures;
+}
+
+function fixturesOf(options: ContractOptions | undefined) {
+  const f = options?.fixtures ?? {};
+  return {
+    rootSession: () =>
+      f.rootSession ? f.rootSession() : Promise.resolve(id()),
+    user: () => (f.user ? f.user() : Promise.resolve(id())),
+    run: (sessionId: string) =>
+      f.run ? f.run(sessionId) : Promise.resolve(id()),
+    runAttrs: f.runAttrs,
+    sessionAttrs: f.sessionAttrs ?? { a: 1 },
+    sessionMetadata: f.sessionMetadata ?? { k: 'v' },
+  };
+}
+
 function event(
   streamId: string,
   rootSessionId: string,
@@ -400,37 +447,44 @@ export function describeTreeBudgetContract(
 export function describeRunStoreContract(
   name: string,
   factory: Factory<RunStore>,
-  /** 建一条能被 `findStaleRunning(0)` 看到的旧跑次所需的等待（毫秒），缺省 5。 */
-  staleDelayMs = 5
+  /**
+   * 数字 = 旧写法的 `staleDelayMs`。`staleDelayMs`：建一条能被 `findStaleRunning(0)`
+   * 看到的旧跑次所需的等待（毫秒），缺省 5。
+   */
+  options: number | (ContractOptions & { staleDelayMs?: number }) = {}
 ) {
+  const opts =
+    typeof options === 'number' ? { staleDelayMs: options } : options;
+  const staleDelayMs = opts.staleDelayMs ?? 5;
+  const fx = fixturesOf(opts);
   describe(`RunStore contract: ${name}`, () => {
-    const open = (
+    const open = async (
       store: RunStore,
       over: Partial<{
         id: string;
-        sessionId: string | null;
+        sessionId: string;
         parentRunId: string | null;
         depth: number;
       }> = {}
     ) => {
       const runId = over.id ?? id();
-      return store
-        .open({
-          id: runId,
-          streamId: runId,
-          parentRunId: over.parentRunId ?? null,
-          depth: over.depth ?? 0,
-          sessionId: over.sessionId === undefined ? id() : over.sessionId,
-          prompt: null,
-          model: { modelId: 'm', label: 'v / m', reasoningEffort: 'medium' },
-        })
-        .then(() => runId);
+      await store.open({
+        id: runId,
+        streamId: runId,
+        parentRunId: over.parentRunId ?? null,
+        depth: over.depth ?? 0,
+        sessionId: over.sessionId ?? (await fx.rootSession()),
+        prompt: null,
+        model: { modelId: 'm', label: 'v / m', reasoningEffort: 'medium' },
+        ...(fx.runAttrs ? { attrs: fx.runAttrs } : {}),
+      });
+      return runId;
     };
 
     it(
       'open 后可查会话与深度；缺记录给缺省值',
       withImpl(factory, async store => {
-        const sessionId = id();
+        const sessionId = await fx.rootSession();
         const runId = await open(store, { sessionId, depth: 2 });
         expect(await store.getSessionId(runId)).toBe(sessionId);
         expect(await store.getDepth(runId)).toBe(2);
@@ -497,32 +551,34 @@ async function waitFor(cond: () => boolean, timeoutMs = 2000) {
  */
 export function describeSessionStoreContract(
   name: string,
-  factory: Factory<SessionStore>
+  factory: Factory<SessionStore>,
+  options: ContractOptions = {}
 ) {
+  const fx = fixturesOf(options);
   describe(`SessionStore contract: ${name}`, () => {
-    const child = (store: SessionStore, rootSessionId: string) =>
+    const child = async (store: SessionStore, rootSessionId: string) =>
       store.createSubSession({
         rootSessionId,
-        parentRunId: id(),
+        parentRunId: await fx.run(rootSessionId),
         subagentName: 'general-purpose',
         userId: null,
         title: 't',
-        metadata: { k: 'v' },
-        attrs: { a: 1 },
+        metadata: fx.sessionMetadata,
+        attrs: fx.sessionAttrs,
       });
 
     it(
       '建子会话：存活（游标 null）、读回同一行；不存在的读回 null',
       withImpl(factory, async store => {
-        const root = id();
+        const root = await fx.rootSession();
         const made = await child(store, root);
         expect(made).toMatchObject({
           kind: 'subagent',
           rootSessionId: root,
           subagentName: 'general-purpose',
           lastMilestoneSeq: null,
-          metadata: { k: 'v' },
-          attrs: { a: 1 },
+          metadata: fx.sessionMetadata,
+          attrs: fx.sessionAttrs,
         });
         expect(await store.getSession(made.id)).toEqual(made);
         expect(await store.getSession(id())).toBeNull();
@@ -532,7 +588,7 @@ export function describeSessionStoreContract(
     it(
       'advanceMilestone 是 CAS：只有期望值对上才写',
       withImpl(factory, async store => {
-        const made = await child(store, id());
+        const made = await child(store, await fx.rootSession());
         expect(await store.advanceMilestone(made.id, 3, 5)).toBe(false);
         expect(await store.advanceMilestone(made.id, null, 5)).toBe(true);
         expect(await store.advanceMilestone(made.id, null, 6)).toBe(false);
@@ -544,7 +600,7 @@ export function describeSessionStoreContract(
     it(
       '并发推进同一个旧游标：恰好一个成功',
       withImpl(factory, async store => {
-        const made = await child(store, id());
+        const made = await child(store, await fx.rootSession());
         const results = await Promise.all(
           Array.from({ length: 5 }, (_, i) =>
             store.advanceMilestone(made.id, null, 10 + i)
@@ -557,8 +613,8 @@ export function describeSessionStoreContract(
     it(
       'countAliveSubsByRoot 只数游标为 null 的子会话',
       withImpl(factory, async store => {
-        const r1 = id();
-        const r2 = id();
+        const r1 = await fx.rootSession();
+        const r2 = await fx.rootSession();
         const a = await child(store, r1);
         await child(store, r1);
         await child(store, r2);
@@ -578,8 +634,10 @@ export function describeSessionStoreContract(
 
 export function describeQuestionStoreContract(
   name: string,
-  factory: Factory<QuestionStore>
+  factory: Factory<QuestionStore>,
+  options: ContractOptions = {}
 ) {
+  const fx = fixturesOf(options);
   describe(`QuestionStore contract: ${name}`, () => {
     const item = {
       question: '用哪种开场？',
@@ -588,9 +646,12 @@ export function describeQuestionStoreContract(
       multiSelect: false,
       defaultOption: 'A',
     };
-    const input = (over: Partial<NewQuestion> = {}): NewQuestion => ({
-      sessionId: id(),
-      userId: id(),
+    // 会话与用户在宿主库里多半是外键：每次现建（缺省随机 id）。
+    const input = async (
+      over: Partial<NewQuestion> = {}
+    ): Promise<NewQuestion> => ({
+      sessionId: over.sessionId ?? (await fx.rootSession()),
+      userId: over.userId ?? (await fx.user()),
       runId: id(),
       toolCallId: id(),
       questions: [item],
@@ -602,7 +663,7 @@ export function describeQuestionStoreContract(
       withImpl(factory, async store => {
         const before = (await store.now()).getTime();
         const { question, swept } = await store.open(
-          input({ timeoutSeconds: 300 })
+          await input({ timeoutSeconds: 300 })
         );
         const after = (await store.now()).getTime();
         expect(swept).toEqual([]);
@@ -623,7 +684,7 @@ export function describeQuestionStoreContract(
           overdue: false,
         });
 
-        const untimed = await store.open(input());
+        const untimed = await store.open(await input());
         expect(untimed.question.deadlineAt).toBeNull();
       })
     );
@@ -631,7 +692,7 @@ export function describeQuestionStoreContract(
     it(
       'get 限定会话：别的会话当不存在；不存在的 get / probe 都是 null',
       withImpl(factory, async store => {
-        const { question } = await store.open(input());
+        const { question } = await store.open(await input());
         expect(await store.get(question.id, question.sessionId)).not.toBeNull();
         expect(await store.get(question.id, id())).toBeNull();
         expect(await store.get(id())).toBeNull();
@@ -642,7 +703,7 @@ export function describeQuestionStoreContract(
     it(
       'probe：从落行起过了 maxWaitSeconds 即 overdue',
       withImpl(factory, async store => {
-        const { question } = await store.open(input());
+        const { question } = await store.open(await input());
         expect((await store.probe(question.id, 0))?.overdue).toBe(true);
       })
     );
@@ -650,15 +711,15 @@ export function describeQuestionStoreContract(
     it(
       '同一会话同一轮已有 pending → QuestionConflictError，原行不动；别的轮次的 pending 作废让位并返回',
       withImpl(factory, async store => {
-        const sessionId = id();
+        const sessionId = await fx.rootSession();
         const runId = id();
-        const first = await store.open(input({ sessionId, runId }));
+        const first = await store.open(await input({ sessionId, runId }));
         await expect(
-          store.open(input({ sessionId, runId }))
+          store.open(await input({ sessionId, runId }))
         ).rejects.toBeInstanceOf(QuestionConflictError);
         expect((await store.get(first.question.id))?.status).toBe('pending');
 
-        const next = await store.open(input({ sessionId }));
+        const next = await store.open(await input({ sessionId }));
         expect(next.swept.map(r => [r.id, r.status])).toEqual([
           [first.question.id, 'cancelled'],
         ]);
@@ -666,8 +727,8 @@ export function describeQuestionStoreContract(
         expect((await store.get(first.question.id))?.status).toBe('cancelled');
 
         // 别的会话的 pending 不受影响。
-        const other = await store.open(input());
-        await store.open(input());
+        const other = await store.open(await input());
+        await store.open(await input());
         expect((await store.get(other.question.id))?.status).toBe('pending');
       })
     );
@@ -675,7 +736,7 @@ export function describeQuestionStoreContract(
     it(
       'settle 是 CAS：只有第一个生效，之后返回 null 且不改写',
       withImpl(factory, async store => {
-        const { question } = await store.open(input());
+        const { question } = await store.open(await input());
         const answers = [{ header: '开场', labels: ['B'], other: null }];
         const won = await store.settle(question.id, 'answered', answers);
         expect(won).toMatchObject({ status: 'answered', answers });
@@ -689,7 +750,7 @@ export function describeQuestionStoreContract(
     it(
       '并发 settle 恰有一个生效',
       withImpl(factory, async store => {
-        const { question } = await store.open(input());
+        const { question } = await store.open(await input());
         const results = await Promise.all([
           store.settle(question.id, 'answered', []),
           store.settle(question.id, 'expired', []),
@@ -702,11 +763,11 @@ export function describeQuestionStoreContract(
     it(
       'settleSession：只改这个会话的 pending（或只改点名的那一个），返回被改的行',
       withImpl(factory, async store => {
-        const sessionId = id();
-        const done = await store.open(input({ sessionId }));
+        const sessionId = await fx.rootSession();
+        const done = await store.open(await input({ sessionId }));
         await store.settle(done.question.id, 'answered', []);
-        const live = await store.open(input({ sessionId }));
-        const elsewhere = await store.open(input());
+        const live = await store.open(await input({ sessionId }));
+        const elsewhere = await store.open(await input());
 
         expect(
           await store.settleSession(sessionId, 'superseded', id())
@@ -726,9 +787,9 @@ export function describeQuestionStoreContract(
     it(
       'hold：仅 pending 且有期限时摘掉期限；不满足（不限时、已停表、已有结局、别的会话）返回 null',
       withImpl(factory, async store => {
-        const sessionId = id();
+        const sessionId = await fx.rootSession();
         const { question } = await store.open(
-          input({ sessionId, timeoutSeconds: 60 })
+          await input({ sessionId, timeoutSeconds: 60 })
         );
         expect(await store.hold(question.id, id())).toBeNull();
         expect(await store.hold(question.id, sessionId)).toMatchObject({
@@ -738,7 +799,7 @@ export function describeQuestionStoreContract(
         expect(await store.hold(question.id, sessionId)).toBeNull();
         expect((await store.probe(question.id, 3600))?.due).toBe(false);
 
-        const untimed = await store.open(input());
+        const untimed = await store.open(await input());
         expect(
           await store.hold(untimed.question.id, untimed.question.sessionId)
         ).toBeNull();
@@ -748,10 +809,10 @@ export function describeQuestionStoreContract(
     it(
       'list：这个会话的全部问题，按落行顺序',
       withImpl(factory, async store => {
-        const sessionId = id();
-        const a = await store.open(input({ sessionId }));
-        const b = await store.open(input({ sessionId }));
-        await store.open(input());
+        const sessionId = await fx.rootSession();
+        const a = await store.open(await input({ sessionId }));
+        const b = await store.open(await input({ sessionId }));
+        await store.open(await input());
         expect(
           (await store.list(sessionId)).map(r => [r.id, r.status])
         ).toEqual([
@@ -880,3 +941,406 @@ export function describeVendorFileCacheContract(
     );
   });
 }
+
+/**
+ * `ConversationStore` 契约（消息、inbox、两个上下文指针）。
+ *
+ * 只认端口上看得见的东西：`seq` 只要求会话内单调（数据库实现常是全表一条序列），
+ * 「有了新动静」记没记、记在哪是实现细节，不在这里测。
+ */
+export function describeConversationStoreContract(
+  name: string,
+  factory: Factory<ConversationStore>,
+  options: ContractOptions = {}
+) {
+  const fx = fixturesOf(options);
+  const text = (t: string) => [{ type: 'text' as const, text: t }];
+
+  describe(`ConversationStore contract: ${name}`, () => {
+    const item = (sessionId: string, t: string, userId: string | null) => ({
+      sessionId,
+      kind: 'user_message' as const,
+      sourceKind: 'user' as const,
+      sourceUserId: userId,
+      source: null,
+      parts: text(t),
+      messageId: id(),
+    });
+    const asUser = (i: InboxItem) => ({
+      id: i.messageId,
+      sessionId: i.sessionId,
+      role: 'user' as const,
+      parts: i.parts,
+    });
+
+    it(
+      'seq 在会话内单调递增；listMessages 按 seq 升序',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const a = await store.appendMessage({
+          sessionId: s,
+          role: 'user',
+          parts: text('1'),
+        });
+        const b = await store.appendMessage({
+          sessionId: s,
+          role: 'assistant',
+          parts: text('2'),
+          metadata: { k: 'v' },
+          tokenUsage: { inputTokens: 3 },
+        });
+        expect(b.seq).toBeGreaterThan(a.seq);
+        expect(b).toMatchObject({
+          sessionId: s,
+          role: 'assistant',
+          parts: text('2'),
+          metadata: { k: 'v' },
+          tokenUsage: { inputTokens: 3 },
+        });
+        expect((await store.listMessages(s)).map(m => m.id)).toEqual([
+          a.id,
+          b.id,
+        ]);
+      })
+    );
+
+    it(
+      'appendMessage 按 id 幂等：撞主键返回已存在的那一行',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const mid = id();
+        const first = await store.appendMessage({
+          id: mid,
+          sessionId: s,
+          role: 'user',
+          parts: text('1'),
+        });
+        const again = await store.appendMessage({
+          id: mid,
+          sessionId: s,
+          role: 'user',
+          parts: text('2'),
+        });
+        expect(first.id).toBe(mid);
+        expect(again).toEqual(first);
+        expect(await store.listMessages(s)).toHaveLength(1);
+      })
+    );
+
+    it(
+      '基线取最后一条 metadata 带 contextTokens 的 assistant 行',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const add = (role: 'user' | 'assistant', contextTokens?: number) =>
+          store.appendMessage({
+            sessionId: s,
+            role,
+            parts: text('x'),
+            ...(contextTokens !== undefined
+              ? { metadata: { contextTokens } }
+              : {}),
+          });
+        await add('assistant', 10);
+        await add('assistant', 20);
+        await add('assistant');
+        await add('user');
+        const inputs = await store.loadContextInputs(s);
+        expect(inputs.baselineContextTokens).toBe(20);
+        expect(inputs.rows).toHaveLength(4);
+        const empty = await store.loadContextInputs(await fx.rootSession());
+        expect(empty).toEqual({
+          rows: [],
+          prunedUptoSeq: null,
+          compactedUptoSeq: null,
+          baselineContextTokens: null,
+        });
+      })
+    );
+
+    it(
+      '裁剪指针只增不减：晚到的较小切点不许把它拉回去',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        await store.advancePrunedUpto(s, 5);
+        await store.advancePrunedUpto(s, 3);
+        expect((await store.loadContextInputs(s)).prunedUptoSeq).toBe(5);
+      })
+    );
+
+    it(
+      'checkpoint 行与压缩指针一起落下、kind 摊平到行上；压缩指针只增不减',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const rows = [];
+        for (let i = 0; i < 4; i++) {
+          rows.push(
+            await store.appendMessage({
+              sessionId: s,
+              role: 'user',
+              parts: text(String(i)),
+            })
+          );
+        }
+        const cut = rows[2].seq;
+        const row = await store.appendCheckpoint({
+          sessionId: s,
+          seq: cut,
+          summary: '摘要',
+        });
+        expect(row).toMatchObject({
+          role: 'user',
+          kind: COMPACTION_CHECKPOINT_KIND,
+          parts: text('摘要'),
+        });
+        expect(row.seq).toBeGreaterThan(rows[3].seq);
+        await store.appendCheckpoint({
+          sessionId: s,
+          seq: rows[1].seq,
+          summary: '旧',
+        });
+        const inputs = await store.loadContextInputs(s);
+        expect(inputs.compactedUptoSeq).toBe(cut);
+        expect(inputs.rows.at(-2)).toMatchObject({
+          seq: row.seq,
+          kind: COMPACTION_CHECKPOINT_KIND,
+        });
+        expect(inputs.rows[0].kind ?? null).toBeNull();
+      })
+    );
+
+    it(
+      'loadContextInputs 给的是快照：之后的追加不漂进去',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        await store.appendMessage({
+          sessionId: s,
+          role: 'user',
+          parts: text('1'),
+        });
+        const snap = await store.loadContextInputs(s);
+        await store.appendMessage({
+          sessionId: s,
+          role: 'user',
+          parts: text('2'),
+        });
+        expect(snap.rows).toHaveLength(1);
+      })
+    );
+
+    it(
+      'takeInbox：按投递序取出本会话的全部、落成消息，别的会话不动',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const t = await fx.rootSession();
+        const u = await fx.user();
+        const a = item(s, 'a', u);
+        const x = item(t, 'x', u);
+        const b = item(s, 'b', u);
+        await store.enqueue(a);
+        await store.enqueue(x);
+        await store.enqueue(b);
+        expect(await store.listSessionIdsWithPending()).toEqual(
+          expect.arrayContaining([s, t])
+        );
+        const pending = await store.listPending(s);
+        expect(pending.map(p => p.messageId)).toEqual([
+          a.messageId,
+          b.messageId,
+        ]);
+        expect(pending[1].seq).toBeGreaterThan(pending[0].seq);
+        expect(pending[0]).toMatchObject({
+          sessionId: s,
+          kind: 'user_message',
+          sourceKind: 'user',
+          sourceUserId: u,
+          source: null,
+          parts: text('a'),
+        });
+
+        const taken = await store.takeInbox(s, asUser);
+        expect(taken.map(e => e.message.id)).toEqual([
+          a.messageId,
+          b.messageId,
+        ]);
+        expect(taken[0].item).toEqual(pending[0]);
+        expect(await store.hasPending(s)).toBe(false);
+        expect(await store.hasPending(t)).toBe(true);
+        expect((await store.listMessages(s)).map(m => m.id)).toEqual([
+          a.messageId,
+          b.messageId,
+        ]);
+        const withPending = await store.listSessionIdsWithPending();
+        expect(withPending).toContain(t);
+        expect(withPending).not.toContain(s);
+        expect(await store.takeInbox(s, asUser)).toEqual([]);
+      })
+    );
+
+    it(
+      'takeInbox：换算抛错 = 整批不取（同事务回滚）',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        await store.enqueue(item(s, 'a', await fx.user()));
+        await expect(
+          store.takeInbox(s, () => {
+            throw new Error('bad row');
+          })
+        ).rejects.toThrow('bad row');
+        expect(await store.hasPending(s)).toBe(true);
+        expect(await store.listMessages(s)).toEqual([]);
+      })
+    );
+
+    it(
+      'enqueue 带结构化来源、系统来源无发送人',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        await store.enqueue({
+          sessionId: s,
+          kind: 'system_reminder',
+          sourceKind: 'system',
+          sourceUserId: null,
+          source: { kind: 'probe' },
+          parts: text('r'),
+          messageId: id(),
+        });
+        const [p] = await store.listPending(s);
+        expect(p).toMatchObject({
+          kind: 'system_reminder',
+          sourceKind: 'system',
+          sourceUserId: null,
+          source: { kind: 'probe' },
+        });
+      })
+    );
+
+    it(
+      'withdraw 只删自己的、还没被取走的',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const u = await fx.user();
+        const queued = item(s, 'a', u);
+        await store.enqueue(queued);
+        const [pending] = await store.listPending(s);
+        expect(await store.withdraw(pending.id, id())).toBeNull();
+        expect(await store.withdraw(pending.id, u)).toMatchObject({
+          id: pending.id,
+          messageId: queued.messageId,
+        });
+        expect(await store.hasPending(s)).toBe(false);
+        expect(await store.withdraw(pending.id, u)).toBeNull();
+      })
+    );
+
+    it(
+      'assistant 段：首次建行、之后追加 parts 并合并 metadata；收尾整体重写',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const r = id();
+        await store.appendAssistantStep({
+          messageId: r,
+          runId: r,
+          sessionId: s,
+          parts: text('a'),
+          metadataPatch: { flushedSeq: 1 },
+        });
+        await store.appendAssistantStep({
+          messageId: r,
+          runId: r,
+          sessionId: s,
+          parts: text('b'),
+          metadataPatch: { flushedSeq: 3 },
+        });
+        let [row] = await store.listMessages(s);
+        expect(row.role).toBe('assistant');
+        expect(row.parts).toEqual([...text('a'), ...text('b')]);
+        expect(row.metadata).toEqual({ runId: r, flushedSeq: 3 });
+        await store.finalizeAssistantTurn({
+          messageId: r,
+          runId: r,
+          metadata: { status: 'completed' },
+          usage: { inputTokens: 1 },
+        });
+        [row] = await store.listMessages(s);
+        expect(row.metadata).toEqual({ runId: r, status: 'completed' });
+        expect(row.tokenUsage).toEqual({ inputTokens: 1 });
+      })
+    );
+
+    it(
+      'finalizeInterruptedTurn 只补没有终态的段、只认 metadata.runId',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        const r = id();
+        const seg1 = id();
+        const seg2 = id();
+        await store.appendMessage({
+          id: seg1,
+          sessionId: s,
+          role: 'assistant',
+          parts: text('1'),
+          metadata: { runId: r, status: 'completed' },
+        });
+        await store.appendMessage({
+          id: seg2,
+          sessionId: s,
+          role: 'assistant',
+          parts: text('2'),
+          metadata: { runId: r },
+        });
+        await store.appendMessage({
+          sessionId: s,
+          role: 'assistant',
+          parts: text('3'),
+          metadata: { runId: id() },
+        });
+        expect(await store.listTurnSegmentIds(r)).toEqual([seg1, seg2]);
+        expect(await store.finalizeInterruptedTurn(r)).toEqual([seg2]);
+        expect(await store.finalizeInterruptedTurn(r)).toEqual([]);
+        const rows = await store.listMessages(s);
+        expect(rows.map(m => m.metadata?.status)).toEqual([
+          'completed',
+          'aborted',
+          undefined,
+        ]);
+        expect(rows[1].metadata).toEqual({
+          runId: r,
+          status: 'aborted',
+          stopReason: 'aborted',
+        });
+      })
+    );
+
+    it(
+      'listMessages 按角色与 seq 过滤；reserveSeq 取走的号不再分配给任何行',
+      withImpl(factory, async store => {
+        const s = await fx.rootSession();
+        await store.appendMessage({
+          sessionId: s,
+          role: 'user',
+          parts: text('q'),
+        });
+        const a1 = await store.appendMessage({
+          sessionId: s,
+          role: 'assistant',
+          parts: text('a1'),
+        });
+        const reserved = await store.reserveSeq(s);
+        expect(reserved).toBeGreaterThan(a1.seq);
+        const a2 = await store.appendMessage({
+          sessionId: s,
+          role: 'assistant',
+          parts: text('a2'),
+        });
+        expect(a2.seq).toBeGreaterThan(reserved);
+        expect(
+          (await store.listMessages(s, { role: 'assistant' })).map(m => m.id)
+        ).toEqual([a1.id, a2.id]);
+        expect(
+          (await store.listMessages(s, { afterSeq: reserved })).map(m => m.id)
+        ).toEqual([a2.id]);
+        expect(await store.listMessages(s, { afterSeq: null })).toHaveLength(3);
+      })
+    );
+  });
+}