@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/src/testing/contracts.ts

@@ -0,0 +1,882 @@
+import { randomUUID } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+
+import type {
+  SessionLock,
+  SubagentAwaitLease,
+  TreeBudget,
+  WakeChannel,
+} from '../ports/coordination.js';
+import {
+  type NewQuestion,
+  QuestionConflictError,
+  type QuestionStore,
+} from '../ports/question-store.js';
+import type { RunStore } from '../ports/run-store.js';
+import type { SessionStore } from '../ports/session-store.js';
+import type { StreamBus } from '../ports/stream-bus.js';
+import type {
+  VendorFileCache,
+  VendorFileRecord,
+} from '../ports/vendor-file-cache.js';
+import type { AgentEvent } from '../schema/agent-event.js';
+
+/**
+ * 端口的契约用例：进程内实现与各适配包（Redis 等）跑同一套，保证换实现不换语义。
+ * 每个用例用随机 id，适配器实现可以共用一个后端实例。
+ *
+ * 用法：`describeStreamBusContract('redis', () => makeBus())`。
+ * 工厂可以返回 `{ impl, cleanup }`，cleanup 在用例结束时调用。
+ */
+type Factory<T> = () =>
+  | T
+  | { impl: T; cleanup?: () => void | Promise<void> }
+  | Promise<T | { impl: T; cleanup?: () => void | Promise<void> }>;
+
+async function make<T extends object>(factory: Factory<T>) {
+  const made = await factory();
+  if ('impl' in made && typeof made.impl === 'object') {
+    return made as { impl: T; cleanup?: () => void | Promise<void> };
+  }
+  return { impl: made as T };
+}
+
+function withImpl<T extends object>(
+  factory: Factory<T>,
+  body: (impl: T) => Promise<void>
+) {
+  return async () => {
+    const { impl, cleanup } = await make(factory);
+    try {
+      await body(impl);
+    } finally {
+      await cleanup?.();
+    }
+  };
+}
+
+const id = () => randomUUID();
+
+function event(
+  streamId: string,
+  rootSessionId: string,
+  seq: number,
+  type: AgentEvent['type'] = 'text-delta'
+): AgentEvent {
+  return {
+    seq,
+    streamId,
+    rootSessionId,
+    sessionId: rootSessionId,
+    runId: streamId,
+    parentRunId: null,
+    depth: 0,
+    ts: Date.now(),
+    type,
+    payload: { seq },
+  };
+}
+
+async function take<T>(it: AsyncIterable<T>, n: number): Promise<T[]> {
+  const out: T[] = [];
+  if (n === 0) return out;
+  for await (const v of it) {
+    out.push(v);
+    if (out.length >= n) break;
+  }
+  return out;
+}
+
+export function describeStreamBusContract(
+  name: string,
+  factory: Factory<StreamBus>
+) {
+  describe(`StreamBus contract: ${name}`, () => {
+    it(
+      'open 分配从 1 起的 seq，重复 open 抛错',
+      withImpl(factory, async bus => {
+        const s = id();
+        const { nextSeq } = bus.open(s);
+        expect([nextSeq(), nextSeq()]).toEqual([1, 2]);
+        expect(() => bus.open(s)).toThrow();
+        bus.close(s);
+      })
+    );
+
+    it(
+      'subscribe 补发 fromSeq 起的历史再接活流，close 后结束',
+      withImpl(factory, async bus => {
+        const s = id();
+        const root = id();
+        bus.open(s);
+        bus.publish(event(s, root, 1));
+        bus.publish(event(s, root, 2));
+        const got = (async () => {
+          const out: number[] = [];
+          for await (const e of bus.subscribe(s, 2)) out.push(e.seq);
+          return out;
+        })();
+        await new Promise(r => setTimeout(r, 10));
+        bus.publish(event(s, root, 3));
+        bus.close(s);
+        expect(await got).toEqual([2, 3]);
+        expect(bus.isActive(s)).toBe(false);
+      })
+    );
+
+    it(
+      'close 之后 publish 被丢弃',
+      withImpl(factory, async bus => {
+        const s = id();
+        const root = id();
+        bus.open(s);
+        bus.publish(event(s, root, 1));
+        bus.close(s);
+        bus.publish(event(s, root, 2));
+        const seqs: number[] = [];
+        for await (const e of bus.subscribe(s)) seqs.push(e.seq);
+        expect(seqs).toEqual([1]);
+      })
+    );
+
+    it(
+      'subscribe 的 signal abort 让等待中的迭代结束',
+      withImpl(factory, async bus => {
+        const s = id();
+        bus.open(s);
+        const ac = new AbortController();
+        const done = (async () => {
+          for await (const _ of bus.subscribe(s, 1, ac.signal)) {
+            // 不会有事件
+          }
+          return 'ended';
+        })();
+        await new Promise(r => setTimeout(r, 10));
+        ac.abort();
+        expect(await done).toBe('ended');
+        bus.close(s);
+      })
+    );
+
+    it(
+      'abort 触发 signalOf 的信号',
+      withImpl(factory, async bus => {
+        const s = id();
+        bus.open(s);
+        const signal = bus.signalOf(s);
+        expect(signal?.aborted).toBe(false);
+        bus.abort(s);
+        expect(signal?.aborted).toBe(true);
+        bus.close(s);
+      })
+    );
+
+    it(
+      '会话面聚合同一根会话下的多条流与会话级事件，游标可续订',
+      withImpl(factory, async bus => {
+        const root = id();
+        const a = id();
+        const b = id();
+        bus.open(a);
+        bus.open(b);
+        const ac = new AbortController();
+        const first = take(bus.subscribeSession(root, undefined, ac.signal), 3);
+        await new Promise(r => setTimeout(r, 10));
+        bus.publish(event(a, root, 1));
+        bus.publish(event(b, root, 1));
+        bus.publishSessionEvent(event(root, root, 0, 'session-title'));
+        const entries = await first;
+        expect(entries.map(e => e.event.streamId)).toEqual([a, b, root]);
+        expect(entries[2].event.type).toBe('session-title');
+
+        // 从第一条之后续订：拿到后两条。
+        const ac2 = new AbortController();
+        const resumed = await take(
+          bus.subscribeSession(root, entries[0].id, ac2.signal),
+          2
+        );
+        expect(resumed.map(e => e.id)).toEqual([entries[1].id, entries[2].id]);
+        ac.abort();
+        ac2.abort();
+        bus.close(a);
+        bus.close(b);
+      })
+    );
+
+    it(
+      '别的根会话的事件不进来',
+      withImpl(factory, async bus => {
+        const root = id();
+        const other = id();
+        const s = id();
+        bus.open(s);
+        const ac = new AbortController();
+        const got = take(bus.subscribeSession(root, undefined, ac.signal), 1);
+        await new Promise(r => setTimeout(r, 10));
+        bus.publish({ ...event(s, other, 1) });
+        bus.publishSessionEvent(event(root, root, 0, 'session-title'));
+        const [entry] = await got;
+        expect(entry.event.rootSessionId).toBe(root);
+        ac.abort();
+        bus.close(s);
+      })
+    );
+  });
+}
+
+export function describeSessionLockContract(
+  name: string,
+  factory: Factory<SessionLock>
+) {
+  describe(`SessionLock contract: ${name}`, () => {
+    it(
+      '同一会话只有一个持有者；释放后可再抢',
+      withImpl(factory, async lock => {
+        const s = id();
+        const t1 = await lock.acquire(s);
+        expect(t1).toBeTypeOf('string');
+        expect(await lock.acquire(s)).toBeNull();
+        expect(await lock.isHeld(s)).toBe(true);
+        await lock.release(s, t1 as string);
+        expect(await lock.isHeld(s)).toBe(false);
+        const t2 = await lock.acquire(s);
+        expect(t2).not.toBeNull();
+        expect(t2).not.toBe(t1);
+        await lock.release(s, t2 as string);
+      })
+    );
+
+    it(
+      'token 不匹配时 renew 失败、release 不生效',
+      withImpl(factory, async lock => {
+        const s = id();
+        const t = (await lock.acquire(s)) as string;
+        expect(await lock.renew(s, 'not-the-token')).toBe(false);
+        await lock.release(s, 'not-the-token');
+        expect(await lock.isHeld(s)).toBe(true);
+        expect(await lock.renew(s, t)).toBe(true);
+        await lock.release(s, t);
+      })
+    );
+
+    it(
+      '不同会话互不影响',
+      withImpl(factory, async lock => {
+        const a = await lock.acquire(id());
+        const b = await lock.acquire(id());
+        expect(a).not.toBeNull();
+        expect(b).not.toBeNull();
+      })
+    );
+  });
+}
+
+export function describeWakeChannelContract(
+  name: string,
+  factory: Factory<WakeChannel>
+) {
+  describe(`WakeChannel contract: ${name}`, () => {
+    it(
+      '订阅者收到 wake 与 idle，各走各的频道；取消订阅后不再收到',
+      withImpl(factory, async ch => {
+        const s = id();
+        const wakes: string[] = [];
+        const idles: string[] = [];
+        const offWake = ch.onWake(x => wakes.push(x));
+        const offIdle = ch.onIdle(x => idles.push(x));
+        await ch.wake(s);
+        await ch.idle(s);
+        await waitFor(() => wakes.length === 1 && idles.length === 1);
+        expect(wakes).toEqual([s]);
+        expect(idles).toEqual([s]);
+        offWake();
+        offIdle();
+        await ch.wake(s);
+        await new Promise(r => setTimeout(r, 30));
+        expect(wakes).toEqual([s]);
+      })
+    );
+
+    it(
+      '投递是异步的：wake() 返回前处理函数不会被同步调用',
+      withImpl(factory, async ch => {
+        let called = false;
+        const off = ch.onWake(() => {
+          called = true;
+        });
+        const p = ch.wake(id());
+        expect(called).toBe(false);
+        await p;
+        await waitFor(() => called);
+        off();
+      })
+    );
+  });
+}
+
+export function describeSubagentAwaitLeaseContract(
+  name: string,
+  factory: Factory<SubagentAwaitLease>
+) {
+  describe(`SubagentAwaitLease contract: ${name}`, () => {
+    it(
+      'begin 后 isAwaited 为真且不消费；claim 恰好一方胜出',
+      withImpl(factory, async lease => {
+        const c = id();
+        expect(await lease.isAwaited(c)).toBe(false);
+        expect(await lease.begin(c)).toBe(true);
+        expect(await lease.isAwaited(c)).toBe(true);
+        expect(await lease.isAwaited(c)).toBe(true);
+        expect(await lease.claim(c, 'finalizer')).toBe(true);
+        expect(await lease.claim(c, 'parent')).toBe(false);
+        expect(await lease.isAwaited(c)).toBe(false);
+      })
+    );
+
+    it(
+      '没 begin 过：finalizer 抢不到（照常回投）',
+      withImpl(factory, async lease => {
+        expect(await lease.claim(id(), 'finalizer')).toBe(false);
+      })
+    );
+
+    it(
+      'renew 不会凭空建出租约',
+      withImpl(factory, async lease => {
+        const c = id();
+        await lease.renew(c);
+        expect(await lease.isAwaited(c)).toBe(false);
+      })
+    );
+  });
+}
+
+export function describeTreeBudgetContract(
+  name: string,
+  factory: Factory<TreeBudget>
+) {
+  describe(`TreeBudget contract: ${name}`, () => {
+    it(
+      '到上限即拒；释放后可再占；不留负值',
+      withImpl(factory, async budget => {
+        const r = id();
+        expect(await budget.tryIncr(r, 2)).toBe(true);
+        expect(await budget.tryIncr(r, 2)).toBe(true);
+        expect(await budget.tryIncr(r, 2)).toBe(false);
+        await budget.decr(r);
+        expect(await budget.tryIncr(r, 2)).toBe(true);
+        await budget.decr(r);
+        await budget.decr(r);
+        await budget.decr(r); // 多减一次
+        expect(await budget.tryIncr(r, 1)).toBe(true);
+        expect(await budget.tryIncr(r, 1)).toBe(false);
+      })
+    );
+
+    it(
+      '并发 tryIncr 不超发',
+      withImpl(factory, async budget => {
+        const r = id();
+        const results = await Promise.all(
+          Array.from({ length: 10 }, () => budget.tryIncr(r, 3))
+        );
+        expect(results.filter(Boolean)).toHaveLength(3);
+      })
+    );
+
+    it(
+      'set 覆盖计数',
+      withImpl(factory, async budget => {
+        const r = id();
+        await budget.set(r, 3);
+        expect(await budget.tryIncr(r, 3)).toBe(false);
+        await budget.set(r, 0);
+        expect(await budget.tryIncr(r, 3)).toBe(true);
+      })
+    );
+  });
+}
+
+export function describeRunStoreContract(
+  name: string,
+  factory: Factory<RunStore>,
+  /** 建一条能被 `findStaleRunning(0)` 看到的旧跑次所需的等待（毫秒），缺省 5。 */
+  staleDelayMs = 5
+) {
+  describe(`RunStore contract: ${name}`, () => {
+    const open = (
+      store: RunStore,
+      over: Partial<{
+        id: string;
+        sessionId: string | null;
+        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);
+    };
+
+    it(
+      'open 后可查会话与深度；缺记录给缺省值',
+      withImpl(factory, async store => {
+        const sessionId = id();
+        const runId = await open(store, { sessionId, depth: 2 });
+        expect(await store.getSessionId(runId)).toBe(sessionId);
+        expect(await store.getDepth(runId)).toBe(2);
+        expect(await store.getSessionId(id())).toBeNull();
+        expect(await store.getDepth(id())).toBe(0);
+      })
+    );
+
+    it(
+      'markInterrupted 只对 running 生效，且只成功一次',
+      withImpl(factory, async store => {
+        const runId = await open(store);
+        expect(await store.markInterrupted(runId, 'killed')).toBe(true);
+        expect(await store.markInterrupted(runId, 'killed')).toBe(false);
+
+        const done = await open(store);
+        await store.finish({
+          id: done,
+          status: 'completed',
+          stopReason: 'stop',
+          text: 'ok',
+          steps: [],
+        });
+        expect(await store.markInterrupted(done, 'killed')).toBe(false);
+      })
+    );
+
+    it(
+      'findStaleRunning 只出仍在 running 且够旧的',
+      withImpl(factory, async store => {
+        const running = await open(store);
+        const finished = await open(store);
+        await store.finish({
+          id: finished,
+          status: 'completed',
+          stopReason: 'stop',
+          text: '',
+          steps: [],
+        });
+        await new Promise(r => setTimeout(r, staleDelayMs));
+        const ids = (await store.findStaleRunning(0)).map(r => r.id);
+        expect(ids).toContain(running);
+        expect(ids).not.toContain(finished);
+        expect(
+          (await store.findStaleRunning(60 * 60_000)).map(r => r.id)
+        ).not.toContain(running);
+      })
+    );
+  });
+}
+
+/** 轮询等条件成立（契约用例不依赖 vitest 的 fake timers，适配器实现也能跑）。 */
+async function waitFor(cond: () => boolean, timeoutMs = 2000) {
+  const start = Date.now();
+  while (!cond()) {
+    if (Date.now() - start > timeoutMs) throw new Error('waitFor timed out');
+    await new Promise(r => setTimeout(r, 5));
+  }
+}
+
+/**
+ * `SessionStore` 契约（子会话行与里程碑游标）。`listSubagentSessionsForSweep` 要看消息与
+ * 更新时间，跟宿主的消息表绑在一起，不在这里测。
+ */
+export function describeSessionStoreContract(
+  name: string,
+  factory: Factory<SessionStore>
+) {
+  describe(`SessionStore contract: ${name}`, () => {
+    const child = (store: SessionStore, rootSessionId: string) =>
+      store.createSubSession({
+        rootSessionId,
+        parentRunId: id(),
+        subagentName: 'general-purpose',
+        userId: null,
+        title: 't',
+        metadata: { k: 'v' },
+        attrs: { a: 1 },
+      });
+
+    it(
+      '建子会话：存活（游标 null）、读回同一行；不存在的读回 null',
+      withImpl(factory, async store => {
+        const root = id();
+        const made = await child(store, root);
+        expect(made).toMatchObject({
+          kind: 'subagent',
+          rootSessionId: root,
+          subagentName: 'general-purpose',
+          lastMilestoneSeq: null,
+          metadata: { k: 'v' },
+          attrs: { a: 1 },
+        });
+        expect(await store.getSession(made.id)).toEqual(made);
+        expect(await store.getSession(id())).toBeNull();
+      })
+    );
+
+    it(
+      'advanceMilestone 是 CAS：只有期望值对上才写',
+      withImpl(factory, async store => {
+        const made = await child(store, id());
+        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);
+        expect(await store.advanceMilestone(made.id, 5, 9)).toBe(true);
+        expect((await store.getSession(made.id))?.lastMilestoneSeq).toBe(9);
+      })
+    );
+
+    it(
+      '并发推进同一个旧游标：恰好一个成功',
+      withImpl(factory, async store => {
+        const made = await child(store, id());
+        const results = await Promise.all(
+          Array.from({ length: 5 }, (_, i) =>
+            store.advanceMilestone(made.id, null, 10 + i)
+          )
+        );
+        expect(results.filter(Boolean)).toHaveLength(1);
+      })
+    );
+
+    it(
+      'countAliveSubsByRoot 只数游标为 null 的子会话',
+      withImpl(factory, async store => {
+        const r1 = id();
+        const r2 = id();
+        const a = await child(store, r1);
+        await child(store, r1);
+        await child(store, r2);
+        await store.advanceMilestone(a.id, null, 1);
+        const counts = new Map(
+          (await store.countAliveSubsByRoot()).map(c => [
+            c.rootSessionId,
+            c.count,
+          ])
+        );
+        expect(counts.get(r1)).toBe(1);
+        expect(counts.get(r2)).toBe(1);
+      })
+    );
+  });
+}
+
+export function describeQuestionStoreContract(
+  name: string,
+  factory: Factory<QuestionStore>
+) {
+  describe(`QuestionStore contract: ${name}`, () => {
+    const item = {
+      question: '用哪种开场？',
+      header: '开场',
+      options: [{ label: 'A' }, { label: 'B' }],
+      multiSelect: false,
+      defaultOption: 'A',
+    };
+    const input = (over: Partial<NewQuestion> = {}): NewQuestion => ({
+      sessionId: id(),
+      userId: id(),
+      runId: id(),
+      toolCallId: id(),
+      questions: [item],
+      ...over,
+    });
+
+    it(
+      '落一行 pending：期限按存储时钟从落行起算；不限时为 null；get / probe 读回同一行',
+      withImpl(factory, async store => {
+        const before = (await store.now()).getTime();
+        const { question, swept } = await store.open(
+          input({ timeoutSeconds: 300 })
+        );
+        const after = (await store.now()).getTime();
+        expect(swept).toEqual([]);
+        expect(question).toMatchObject({
+          status: 'pending',
+          answers: null,
+          resolvedAt: null,
+          questions: [item],
+        });
+        const created = question.createdAt.getTime();
+        expect(created).toBeGreaterThanOrEqual(before - 1000);
+        expect(created).toBeLessThanOrEqual(after + 1000);
+        expect(question.deadlineAt!.getTime() - created).toBe(300_000);
+        expect(await store.get(question.id)).toEqual(question);
+        expect(await store.probe(question.id, 3600)).toEqual({
+          question,
+          due: false,
+          overdue: false,
+        });
+
+        const untimed = await store.open(input());
+        expect(untimed.question.deadlineAt).toBeNull();
+      })
+    );
+
+    it(
+      'get 限定会话：别的会话当不存在；不存在的 get / probe 都是 null',
+      withImpl(factory, async store => {
+        const { question } = await store.open(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();
+        expect(await store.probe(id(), 60)).toBeNull();
+      })
+    );
+
+    it(
+      'probe：从落行起过了 maxWaitSeconds 即 overdue',
+      withImpl(factory, async store => {
+        const { question } = await store.open(input());
+        expect((await store.probe(question.id, 0))?.overdue).toBe(true);
+      })
+    );
+
+    it(
+      '同一会话同一轮已有 pending → QuestionConflictError，原行不动；别的轮次的 pending 作废让位并返回',
+      withImpl(factory, async store => {
+        const sessionId = id();
+        const runId = id();
+        const first = await store.open(input({ sessionId, runId }));
+        await expect(
+          store.open(input({ sessionId, runId }))
+        ).rejects.toBeInstanceOf(QuestionConflictError);
+        expect((await store.get(first.question.id))?.status).toBe('pending');
+
+        const next = await store.open(input({ sessionId }));
+        expect(next.swept.map(r => [r.id, r.status])).toEqual([
+          [first.question.id, 'cancelled'],
+        ]);
+        expect(next.swept[0].resolvedAt).not.toBeNull();
+        expect((await store.get(first.question.id))?.status).toBe('cancelled');
+
+        // 别的会话的 pending 不受影响。
+        const other = await store.open(input());
+        await store.open(input());
+        expect((await store.get(other.question.id))?.status).toBe('pending');
+      })
+    );
+
+    it(
+      'settle 是 CAS：只有第一个生效，之后返回 null 且不改写',
+      withImpl(factory, async store => {
+        const { question } = await store.open(input());
+        const answers = [{ header: '开场', labels: ['B'], other: null }];
+        const won = await store.settle(question.id, 'answered', answers);
+        expect(won).toMatchObject({ status: 'answered', answers });
+        expect(won?.resolvedAt).not.toBeNull();
+        expect(await store.settle(question.id, 'expired', null)).toBeNull();
+        expect(await store.get(question.id)).toEqual(won);
+        expect(await store.settle(id(), 'cancelled', null)).toBeNull();
+      })
+    );
+
+    it(
+      '并发 settle 恰有一个生效',
+      withImpl(factory, async store => {
+        const { question } = await store.open(input());
+        const results = await Promise.all([
+          store.settle(question.id, 'answered', []),
+          store.settle(question.id, 'expired', []),
+          store.settle(question.id, 'cancelled', null),
+        ]);
+        expect(results.filter(r => r !== null)).toHaveLength(1);
+      })
+    );
+
+    it(
+      'settleSession：只改这个会话的 pending（或只改点名的那一个），返回被改的行',
+      withImpl(factory, async store => {
+        const sessionId = id();
+        const done = await store.open(input({ sessionId }));
+        await store.settle(done.question.id, 'answered', []);
+        const live = await store.open(input({ sessionId }));
+        const elsewhere = await store.open(input());
+
+        expect(
+          await store.settleSession(sessionId, 'superseded', id())
+        ).toEqual([]);
+        const changed = await store.settleSession(sessionId, 'cancelled');
+        expect(changed.map(r => [r.id, r.status])).toEqual([
+          [live.question.id, 'cancelled'],
+        ]);
+        expect((await store.get(done.question.id))?.status).toBe('answered');
+        expect((await store.get(elsewhere.question.id))?.status).toBe(
+          'pending'
+        );
+        expect(await store.settleSession(sessionId, 'cancelled')).toEqual([]);
+      })
+    );
+
+    it(
+      'hold：仅 pending 且有期限时摘掉期限；不满足（不限时、已停表、已有结局、别的会话）返回 null',
+      withImpl(factory, async store => {
+        const sessionId = id();
+        const { question } = await store.open(
+          input({ sessionId, timeoutSeconds: 60 })
+        );
+        expect(await store.hold(question.id, id())).toBeNull();
+        expect(await store.hold(question.id, sessionId)).toMatchObject({
+          status: 'pending',
+          deadlineAt: null,
+        });
+        expect(await store.hold(question.id, sessionId)).toBeNull();
+        expect((await store.probe(question.id, 3600))?.due).toBe(false);
+
+        const untimed = await store.open(input());
+        expect(
+          await store.hold(untimed.question.id, untimed.question.sessionId)
+        ).toBeNull();
+      })
+    );
+
+    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());
+        expect(
+          (await store.list(sessionId)).map(r => [r.id, r.status])
+        ).toEqual([
+          [a.question.id, 'cancelled'],
+          [b.question.id, 'pending'],
+        ]);
+        expect(await store.list(id())).toEqual([]);
+      })
+    );
+  });
+}
+
+export function describeVendorFileCacheContract(
+  name: string,
+  factory: Factory<VendorFileCache>
+) {
+  describe(`VendorFileCache contract: ${name}`, () => {
+    const record = (
+      over: Partial<VendorFileRecord> = {}
+    ): VendorFileRecord => ({
+      vendor: `v-${id()}`,
+      account: 'k1',
+      contentHash: id(),
+      fileId: `file-${id()}`,
+      src: null,
+      mediaType: 'image/png',
+      bytes: 3,
+      expiresAt: null,
+      lastUsedAt: new Date(1_000),
+      ...over,
+    });
+
+    it(
+      'find 按厂商 + 字节查，跨账号都给；别家厂商的不给',
+      withImpl(factory, async cache => {
+        const a = record();
+        const b = record({
+          vendor: a.vendor,
+          contentHash: a.contentHash,
+          account: 'k2',
+        });
+        const other = record({ contentHash: a.contentHash });
+        await cache.put(a);
+        await cache.put(b);
+        await cache.put(other);
+        const found = await cache.find(a.vendor, [a.contentHash, id()]);
+        expect(found.map(r => r.account).sort()).toEqual(['k1', 'k2']);
+        expect(found.find(r => r.account === 'k1')).toEqual(a);
+        expect(await cache.find(a.vendor, [])).toEqual([]);
+      })
+    );
+
+    it(
+      'put 按 (厂商, 账号, 字节) 覆盖',
+      withImpl(factory, async cache => {
+        const a = record();
+        await cache.put(a);
+        await cache.put({
+          ...a,
+          fileId: 'file-new',
+          expiresAt: new Date(5_000),
+        });
+        const found = await cache.find(a.vendor, [a.contentHash]);
+        expect(found).toHaveLength(1);
+        expect(found[0]).toMatchObject({
+          fileId: 'file-new',
+          expiresAt: new Date(5_000),
+        });
+      })
+    );
+
+    it(
+      'touch 只改 lastUsedAt；记录不在不报错',
+      withImpl(factory, async cache => {
+        const a = record();
+        await cache.put(a);
+        await cache.touch(a, new Date(9_000));
+        const [found] = await cache.find(a.vendor, [a.contentHash]);
+        expect(found.lastUsedAt).toEqual(new Date(9_000));
+        expect(found.fileId).toBe(a.fileId);
+        await cache.touch(record(), new Date(9_000));
+      })
+    );
+
+    it(
+      'forget 只删这个账号下点名的 file id',
+      withImpl(factory, async cache => {
+        const a = record();
+        const b = record({
+          vendor: a.vendor,
+          account: 'k2',
+          contentHash: a.contentHash,
+        });
+        const c = record({ vendor: a.vendor });
+        await cache.put(a);
+        await cache.put(b);
+        await cache.put(c);
+        await cache.forget(a.vendor, 'k1', [a.fileId, b.fileId]);
+        const left = await cache.find(a.vendor, [a.contentHash, c.contentHash]);
+        expect(left.map(r => r.fileId).sort()).toEqual(
+          [b.fileId, c.fileId].sort()
+        );
+      })
+    );
+
+    it(
+      'sweepExpired 删到期的，永久的与未到期的留下',
+      withImpl(factory, async cache => {
+        const vendor = `v-${id()}`;
+        const expired = record({ vendor, expiresAt: new Date(1_000) });
+        const live = record({ vendor, expiresAt: new Date(10_000) });
+        const forever = record({ vendor });
+        for (const r of [expired, live, forever]) await cache.put(r);
+        expect(
+          await cache.sweepExpired(new Date(5_000))
+        ).toBeGreaterThanOrEqual(1);
+        const left = await cache.find(vendor, [
+          expired.contentHash,
+          live.contentHash,
+          forever.contentHash,
+        ]);
+        expect(left.map(r => r.fileId).sort()).toEqual(
+          [live.fileId, forever.fileId].sort()
+        );
+      })
+    );
+  });
+}