@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/do/contracts.ts

@@ -1,8 +1,26 @@
+import type {
+  TopicDeliverableCommand,
+  TopicDeliverableResult,
+} from '../tasks/topic-deliverables';
+import type {
+  ChannelIdentity,
+  ChannelTurnInput,
+  ChannelTurnOutcome,
+} from '../channels/contract';
+import type { TaskExecutionProfile } from '../core/execution-profile';
+import type { CapabilityRouterMode } from '@ixo/common/ai/decisions';
 import type { TranscriptPageOptions } from './transcript';
+import type { TurnUsage } from '../core/turn-budget';
 import type { BotStatus, EncryptedFileInfo } from '@ixo/matrix-bot-workers-sdk';
 import type { AttachmentInput } from '../attachments/types';
 import type { RealtimeStatus } from '../realtime/realtime-endpoint';
 import type { TierFlushResult, TierStatus } from '../sqlite/do-vfs';
+import type { OwnedArtifact } from '../artifacts/store';
+import type {
+  FeedbackReservation,
+  FeedbackSettlement,
+  FeedbackTarget,
+} from '../feedback/contract';
 /**
  * Cross-object contracts for the Workers runtime.
  *
@@ -25,6 +43,7 @@ import type { TierFlushResult, TierStatus } from '../sqlite/do-vfs';
 
 /** Bindings every oracle Worker must declare (see the example `wrangler.jsonc`). */
 export interface OracleWorkerEnv {
+  TOPIC_DELIVERABLES_ENABLED?: string;
   USER_ORACLE: DurableObjectNamespace<UserOracleObject>;
   MATRIX_GATEWAY: DurableObjectNamespace<MatrixGatewayObject>;
 
@@ -40,6 +59,12 @@ export interface OracleWorkerEnv {
   /** Blocksync GraphQL endpoint used to resolve `did:ixo` verification keys. */
   BLOCKSYNC_GRAPHQL_URL: string;
   UCAN_AUTH_MAX_TTL_SECONDS?: string;
+  /** `true` restores the legacy bare-delegation authentication (off by default). */
+  UCAN_ALLOW_BARE_DELEGATION_AUTH?: string;
+  CHANNEL_SERVICE_DID?: string;
+  AUTH_HUB?: Fetcher;
+  AUTH_HUB_URL?: string;
+  AUTH_HUB_CHANNEL_SERVICE_KEY?: string;
 
   // --- matrix -------------------------------------------------------------
   MATRIX_BASE_URL: string;
@@ -73,6 +98,34 @@ export interface OracleWorkerEnv {
   MATRIX_HOT_ROOMS?: string;
   /** Cap on events replayed per room after a restart (SDK default 0 = unbounded). */
   MATRIX_BACKFILL_MAX_EVENTS?: string;
+  /**
+   * Gateway memory guards (`@ixo/matrix-bot-workers-sdk` 0.5+): events per
+   * room per `/sync` batch (default 30), the largest `/sync` response held
+   * in memory (default 16 MiB; over it the batch is re-requested at timeline
+   * limit 1 and the rooms catch up through `/messages`), events per catch-up
+   * page (default 100), the largest catch-up page (default 10 MiB; a bigger
+   * one is fetched again smaller) and the largest ciphertext the bot will
+   * decrypt (default 0 = no cap). A cap of `0` switches that guard off.
+   */
+  MATRIX_SYNC_TIMELINE_LIMIT?: string;
+  MATRIX_SYNC_BYTES_CAP?: string;
+  MATRIX_CATCHUP_PAGE_SIZE?: string;
+  MATRIX_PAGE_BYTES_CAP?: string;
+  MATRIX_MAX_DECRYPT_BYTES?: string;
+  /**
+   * `true` restores every room key the account's key backup holds on a
+   * device's first start (SDK 0.6+), capped at `..._MAX_KEYS` (default
+   * 5,000; a larger backup is skipped and keys stay on demand). Off by
+   * default: the gateway reads keys from the backup one session at a time.
+   */
+  MATRIX_BACKUP_BULK_RESTORE?: string;
+  MATRIX_BACKUP_BULK_RESTORE_MAX_KEYS?: string;
+  /**
+   * Keep-alive fuse (SDK 0.7+): while the gateway object works, its alarm is
+   * re-armed this far ahead so a host drain brings it back within the fuse
+   * (default 10 s, floor 2 s, `0` = off).
+   */
+  MATRIX_KEEPALIVE_FUSE_MS?: string;
 
   // --- storage ------------------------------------------------------------
   /**
@@ -103,6 +156,22 @@ export interface OracleWorkerEnv {
   TIER_EVICT_AFTER_PERIODS?: string;
   /** Length of one access-tracking period in ms (default one day; tests shorten it). */
   TIER_PERIOD_MS?: string;
+  /**
+   * Artefacts (chat delivery): long replies on chat surfaces become documents
+   * behind a link. The R2 bucket holds only ciphertext share copies; absent
+   * bucket = artefacts off; a bucket without a public origin keeps stored
+   * artefacts readable and revocable but makes no new ones. Long replies are
+   * then split into messages instead.
+   */
+  ARTIFACT_BUCKET?: R2Bucket;
+  /** The oracle Worker's public origin; artefact links point at `/a/:id` under it. */
+  ORACLE_PUBLIC_URL?: string;
+  /** A shared viewer page (Qi.Space). Unset = the oracle's own `/a/:id` page. */
+  ARTIFACT_VIEWER_URL?: string;
+  /** Days an artefact link stays valid (default 30). */
+  ARTIFACT_LINK_TTL_DAYS?: string;
+  /** Hours between the cron's sweeps of expired share copies (default 24, 1–168). */
+  ARTIFACT_SWEEP_INTERVAL_HOURS?: string;
   /** IXO VFS worker base URL when `OWNER_STORE=vfs` (defaults per NETWORK). */
   VFS_BASE_URL?: string;
   /** UCAN store worker base URL when `OWNER_STORE=vfs` (defaults per NETWORK). */
@@ -121,6 +190,36 @@ export interface OracleWorkerEnv {
    * local harness and vitest pool, where the shell degrades to no limiting.
    */
   RATE_LIMIT?: RateLimit;
+  /**
+   * Optional rate-limit binding for anonymous feedback, keyed per client IP
+   * pseudonym (declare it with `simple: { limit: 3, period: 60 }`). Without
+   * it the per-IP check uses `RATE_LIMIT`'s limit under a feedback-only key.
+   */
+  FEEDBACK_RATE_LIMIT?: RateLimit;
+
+  // --- anonymous response feedback (docs/configuration.md) ------------------
+  // Read by the shell only (`src/feedback/config.ts`); never part of the
+  // validated config plugins receive. Off unless the key and secret are set.
+  /** Linear API key allowed to create issues in the feedback team. */
+  FEEDBACK_LINEAR_API_KEY?: string;
+  /** At least 32 characters; derives the user/session/message pseudonyms. */
+  FEEDBACK_HMAC_SECRET?: string;
+  /** Linear team (default: Studio). */
+  FEEDBACK_LINEAR_TEAM_ID?: string;
+  /** Linear project (default: "User Feedback from Portal"). */
+  FEEDBACK_LINEAR_PROJECT_ID?: string;
+  /** Optional comma-separated Linear label ids. */
+  FEEDBACK_LINEAR_LABEL_IDS?: string;
+  /** Linear GraphQL endpoint override (default `https://api.linear.app/graphql`). */
+  FEEDBACK_LINEAR_API_URL?: string;
+  /** Release or commit identifier shown in feedback issues (default `unknown`). */
+  QIFORGE_BUILD_VERSION?: string;
+  /**
+   * Workers AI binding. Optional: `DECISION_PROVIDER=cloudflare-jev` runs the
+   * Jev model through it instead of the account credentials. Declare it with
+   * `"ai": { "binding": "AI" }` in the wrangler config.
+   */
+  AI?: Ai;
 
   // --- llm ----------------------------------------------------------------
   OPEN_ROUTER_API_KEY: string;
@@ -130,6 +229,15 @@ export interface OracleWorkerEnv {
   MAIN_REASONING_EFFORT?: string;
   /** LangGraph steps one turn may take before `GraphRecursionError` (default 600; Node hard-codes 200). */
   TURN_RECURSION_LIMIT?: string;
+  /** Turn budget: cumulative model tokens (default 500000), tool attempts (120), deadline in ms (600000). */
+  TURN_MAX_TOKENS?: string;
+  TURN_MAX_TOOL_CALLS?: string;
+  TURN_TIMEOUT_MS?: string;
+  /** Repetition guard: identical successful writes (default 1) and reads (5) per turn. */
+  TURN_MAX_IDENTICAL_WRITES?: string;
+  TURN_MAX_IDENTICAL_READS?: string;
+  /** Time limit per request-admission handler in ms (default 2000). */
+  REQUEST_ADMISSION_TIMEOUT_MS?: string;
   /** Durable-run knobs (docs/plans/durable-runs.md); see `runDurabilityConfig`. */
   RUN_KEEPALIVE_MS?: string;
   RUN_SEGMENT_FLUSH_MS?: string;
@@ -155,6 +263,22 @@ export interface OracleWorkerEnv {
   /** Nebius Token Factory API key — required when `LLM_PROVIDER=nebius`. */
   NEBIUS_API_KEY?: string;
 
+  // --- decisions ----------------------------------------------------------
+  /** Bounded semantic Decision provider; unset leaves Decisions unconfigured. `openrouter-jev` reuses `OPEN_ROUTER_API_KEY`. */
+  DECISION_PROVIDER?: 'cloudflare-jev' | 'openrouter-jev';
+  /** Jev model id override (`typesafe/jev` on Workers AI, `typesafe/jev-1.13` on OpenRouter). */
+  DECISION_MODEL?: string;
+  /** Cloudflare account for `cloudflare-jev` over the REST API; not needed when the `AI` binding is declared. */
+  CLOUDFLARE_ACCOUNT_ID?: string;
+  /** Workers AI token for `cloudflare-jev` over the REST API; not needed when the `AI` binding is declared. */
+  CLOUDFLARE_API_TOKEN?: string;
+  /**
+   * Capability router (needs a `DECISION_PROVIDER`). `off` (default) never
+   * evaluates; `shadow` evaluates and logs the verdict without preloading;
+   * `on` preloads the predicted on-demand plugin's tools for the turn.
+   */
+  CAPABILITY_ROUTER?: CapabilityRouterMode;
+
   // --- langsmith tracing ---------------------------------------------------
   /** `'true'` traces every turn (explicit tracer — Workers has no env auto-attach). */
   LANGSMITH_TRACING?: string;
@@ -206,6 +330,7 @@ export type JsonString = string;
 
 /** Who is talking and through which transport. */
 export interface TurnIdentity {
+  channel?: ChannelIdentity;
   /** Validated user DID (from the UCAN signer or the Matrix sender mapping). */
   userDid: string;
   /** `@did-ixo-…:server` when known. */
@@ -219,10 +344,16 @@ export interface TurnIdentity {
 
 /** Request the shell / gateway sends to `UserOracleDO` to run one turn. */
 export interface TurnRequest {
+  channel?: {
+    provider: 'whatsapp';
+    bindingId: string;
+    remoteMessageRef: string;
+  };
+  executionProfile?: TaskExecutionProfile;
   identity: TurnIdentity;
   sessionId: string;
   message: string;
-  client: 'portal' | 'matrix';
+  client: 'portal' | 'matrix' | 'channel';
   /** Matrix room the turn arrived in (Matrix turns) or the user's DM room. */
   roomId?: string;
   /** Thread root when the user replied inside a thread. */
@@ -314,7 +445,7 @@ export interface RunSummary {
   runId: string;
   sessionId: string;
   requestId: string;
-  client: 'portal' | 'matrix';
+  client: 'portal' | 'matrix' | 'channel';
   status:
     | 'queued'
     | 'running'
@@ -370,16 +501,29 @@ export interface RunsStatus {
       nextAttemptAt: number | null;
       error: string | null;
       taskRunId: string | null;
+      /** The turn's budget usage, once the run ended (`TurnUsage`). */
+      usage: TurnUsage | null;
     }
   >;
+  /** Writes whose outcome is still unknown (tool-execution.ts); never their arguments. */
+  claims: Array<{
+    fingerprint: string;
+    toolName: string;
+    runId: string;
+    sessionId: string;
+    startedAt: string;
+    state: 'pending' | 'warned';
+  }>;
 }
 
 /** Non-streaming turn result. */
 export interface TurnResult {
   sessionId: string;
   requestId: string;
-  /** Final assistant text. */
+  /** The model's final text, on every surface (never a chat rendering). */
   text: string;
+  /** Chat-surface turns: the Reply Plan (JSON) to deliver part by part. */
+  plan?: JsonString;
   /** Id of the final assistant message, when one was produced. */
   messageId?: string;
   /** Tool calls made during the turn (name + summarized status), for logging. */
@@ -485,6 +629,16 @@ export interface StorageStatus {
  * piped straight to the client.
  */
 export interface UserOracleObject extends Rpc.DurableObjectBranded {
+  topicDeliverable(
+    identity: TurnIdentity,
+    operationId: string,
+    command: TopicDeliverableCommand,
+  ): Promise<TopicDeliverableResult>;
+  channelTurn(
+    identity: TurnIdentity,
+    input: ChannelTurnInput,
+    requestHash: string,
+  ): Promise<ChannelTurnOutcome>;
   /** Run a turn and return the final text (used by the Matrix gateway). */
   runTurn(req: TurnRequest): Promise<TurnResult>;
   /**
@@ -503,6 +657,13 @@ export interface UserOracleObject extends Rpc.DurableObjectBranded {
     opts?: { limit?: number; offset?: number },
   ): Promise<{ sessions: SessionSummary[]; total: number }>;
   deleteSession(identity: TurnIdentity, sessionId: string): Promise<boolean>;
+  /** `GET /artifacts/:id` — the owner's canonical copy, or null. */
+  artifact(
+    identity: TurnIdentity,
+    artifactId: string,
+  ): Promise<OwnedArtifact | null>;
+  /** `DELETE /artifacts/:id` — false when there is no such artefact. */
+  revokeArtifact(identity: TurnIdentity, artifactId: string): Promise<boolean>;
   /** JSON-encoded `MessageDto[]` for `GET /messages/:sessionId`. */
   listMessages(identity: TurnIdentity, sessionId: string): Promise<JsonString>;
   /**
@@ -517,6 +678,20 @@ export interface UserOracleObject extends Rpc.DurableObjectBranded {
   ): Promise<
     { ok: true; json: JsonString } | { ok: false; status: 400; message: string }
   >;
+  /**
+   * Anonymous feedback (src/feedback/): validate the target message in this
+   * user's database and reserve its idempotency marker. Never sees the text.
+   */
+  reserveMessageFeedback(
+    identity: TurnIdentity,
+    target: FeedbackTarget,
+  ): Promise<FeedbackReservation>;
+  /** Record the delivery, keep the earlier submission's, or release the reservation. */
+  settleMessageFeedback(
+    identity: TurnIdentity,
+    target: FeedbackTarget,
+    outcome: FeedbackSettlement,
+  ): Promise<void>;
   abortTurn(sessionId: string): Promise<boolean>;
   /** The session's active (queued/running/recovering) run, if any. */
   sessionRun(
@@ -567,9 +742,12 @@ export interface UserOracleObject extends Rpc.DurableObjectBranded {
   /**
    * Drop the working copy (pages + caches) so the next access re-imports from
    * the owner store. Simulates eviction/loss of the DO cache in tests and is
-   * the "user deleted their file upstream" path.
+   * the "user deleted their file upstream" path. `userDid` is the caller the
+   * shell authenticated, so an object that never booted boots for it.
    */
-  resetWorkingCopy(): Promise<{ reloadedFromOwnerStore: boolean }>;
+  resetWorkingCopy(
+    identity?: TurnIdentity,
+  ): Promise<{ reloadedFromOwnerStore: boolean }>;
   /** Run one R2 page-tier eviction pass now (debug routes; `force` ignores recency). */
   tierFlush(opts?: {
     force?: boolean;
@@ -630,6 +808,16 @@ export interface CreateRoomOptions {
   userDid: string;
 }
 
+/**
+ * Deadline for one gateway media download, from opening it to the last byte
+ * (the gateway's default applies when omitted). Only the timeout crosses the
+ * RPC: an `AbortSignal` cannot, so the caller stops a transfer early by
+ * cancelling the returned stream.
+ */
+export interface MediaDownloadDeadline {
+  timeoutMs?: number;
+}
+
 /**
  * RPC surface of `MatrixGatewayDO`. User objects call it for anything that
  * needs the bot identity (sending, media, room lookups); the shell calls
@@ -648,9 +836,13 @@ export interface MatrixGatewayObject extends Rpc.DurableObjectBranded {
   downloadEventMediaStream(
     roomId: string,
     eventId: string,
+    opts?: MediaDownloadDeadline,
   ): Promise<MediaStream | null>;
   /** Authenticated media download of an `mxc://` URI, as a stream. */
-  downloadMxcMediaStream(mxc: string): Promise<ReadableStream<Uint8Array>>;
+  downloadMxcMediaStream(
+    mxc: string,
+    opts?: MediaDownloadDeadline,
+  ): Promise<ReadableStream<Uint8Array>>;
   /** Forcibly reset the gateway object like a platform host drain (debug routes only). The call itself rejects. */
   debugAbortObject(): Promise<void>;
   /** Stop the bot (operator/debug; `ensureStarted`/cron brings it back). */

package/src/do/idle-eviction.ts

@@ -0,0 +1,38 @@
+/**
+ * Dropping an idle user's working copy. The object only drops it when the
+ * owner copy upstream is verified current, and that check awaits (the
+ * checksum reads the whole file, from R2 for tiered pages), and while an
+ * object awaits I/O other than its own storage a request can arrive. So
+ * whatever the tick decided before is re-read after the check, and the
+ * in-memory handles are dropped before the first await of the wipe: from
+ * then on a request boots afresh from the owner copy instead of reaching a
+ * database being deleted under it.
+ */
+export interface IdleEvictionSteps {
+  /** The owner copy matches the working copy (may await network I/O). */
+  ownerCopyIsCurrent(): Promise<boolean>;
+  /** Everything that decides idleness, read again: still no activity. */
+  stillIdle(): Promise<boolean>;
+  /** Forget the in-memory handles. Synchronous, so nothing interleaves. */
+  dropHandles(): void;
+  /** Delete the working copy. */
+  wipe(): Promise<void>;
+}
+
+export type IdleEvictionOutcome =
+  /** The working copy was deleted. */
+  | 'evicted'
+  /** The owner copy is not verified current: keep the working copy. */
+  | 'not-current'
+  /** Activity arrived while the owner copy was checked: keep it. */
+  | 'active';
+
+export async function evictIdleWorkingCopy(
+  steps: IdleEvictionSteps,
+): Promise<IdleEvictionOutcome> {
+  if (!(await steps.ownerCopyIsCurrent())) return 'not-current';
+  if (!(await steps.stillIdle())) return 'active';
+  steps.dropHandles();
+  await steps.wipe();
+  return 'evicted';
+}

package/src/do/matrix-turn-ledger.ts

@@ -29,6 +29,8 @@ export interface MatrixTurnRecord {
   startedAt: string;
   answeredAt: string | null;
   replyText: string | null;
+  /** The Reply Plan (JSON) a chat-style reply was delivered as. */
+  replyPlan?: string;
 }
 
 export type MatrixTurnDecision = 'run' | 'answered' | 'interrupted';
@@ -50,6 +52,7 @@ type LedgerRow = {
   started_at: string;
   answered_at: string | null;
   reply_text: string | null;
+  reply_plan: string | null;
 } & Record<string, string | null>;
 
 export class MatrixTurnLedger {
@@ -76,8 +79,14 @@ export class MatrixTurnLedger {
         request_id TEXT NOT NULL,
         started_at TEXT NOT NULL,
         answered_at TEXT,
-        reply_text TEXT
+        reply_text TEXT,
+        reply_plan TEXT
       )`);
+    const columns = await this.db.exec<{ name: string }>(
+      `PRAGMA table_info(matrix_turns)`,
+    );
+    if (!columns.some((c) => c.name === 'reply_plan'))
+      await this.db.run(`ALTER TABLE matrix_turns ADD COLUMN reply_plan TEXT`);
     await this.db.run(`DELETE FROM matrix_turns WHERE started_at < ?`, [
       new Date(this.now() - RETENTION_MS).toISOString(),
     ]);
@@ -86,7 +95,7 @@ export class MatrixTurnLedger {
   async get(eventId: string): Promise<MatrixTurnRecord | undefined> {
     await this.setup();
     const row = await this.db.get<LedgerRow>(
-      `SELECT event_id, session_id, request_id, started_at, answered_at, reply_text
+      `SELECT event_id, session_id, request_id, started_at, answered_at, reply_text, reply_plan
        FROM matrix_turns WHERE event_id = ?`,
       [eventId],
     );
@@ -98,6 +107,7 @@ export class MatrixTurnLedger {
       startedAt: row.started_at,
       answeredAt: row.answered_at,
       replyText: row.reply_text,
+      ...(row.reply_plan !== null ? { replyPlan: row.reply_plan } : {}),
     };
   }
 
@@ -116,11 +126,20 @@ export class MatrixTurnLedger {
   }
 
   /** Record the reply; from now on the event is answered, never re-run. */
-  async answer(eventId: string, replyText: string): Promise<void> {
+  async answer(
+    eventId: string,
+    replyText: string,
+    replyPlan?: string,
+  ): Promise<void> {
     await this.setup();
     await this.db.run(
-      `UPDATE matrix_turns SET reply_text = ?, answered_at = ? WHERE event_id = ?`,
-      [replyText, new Date(this.now()).toISOString(), eventId],
+      `UPDATE matrix_turns SET reply_text = ?, reply_plan = ?, answered_at = ? WHERE event_id = ?`,
+      [
+        replyText,
+        replyPlan ?? null,
+        new Date(this.now()).toISOString(),
+        eventId,
+      ],
     );
   }
 }

package/src/do/result-store-test-do.ts

@@ -22,13 +22,58 @@ export class ResultStoreTestDO extends DurableObject<{ TIER_TEST: R2Bucket }> {
 
   private withBucket = true;
 
-  private async resultStore(): Promise<ResultStore> {
+  /**
+   * How R2 deletes behave: `fail` throws (an outage during a sweep),
+   * `delete-then-fail` deletes and then throws (a lost response),
+   * `fail-first` throws on the first call only.
+   */
+  private deletes: 'ok' | 'fail' | 'delete-then-fail' | 'fail-first' = 'ok';
+
+  private deleteCalls = 0;
+
+  /** While set, an R2 delete waits for `release` (after signalling `reached`). */
+  private deleteHold: { reached: () => void; release: Promise<void> } | null =
+    null;
+
+  private async database(): Promise<DoSqliteDatabase> {
     if (!this.db || !this.db.isOpen) {
       this.db = await DoSqliteDatabase.open(this.ctx, 'results-test.db');
       this.store = undefined;
     }
-    this.store ??= new ResultStore(this.db, {
-      ...(this.withBucket ? { bucket: this.env.TIER_TEST } : {}),
+    return this.db;
+  }
+
+  private bucket(): R2Bucket {
+    const remove = async (keys: string | string[]): Promise<void> => {
+      this.deleteCalls += 1;
+      const hold = this.deleteHold;
+      if (hold) {
+        hold.reached();
+        await hold.release;
+      }
+      if (
+        this.deletes === 'fail' ||
+        (this.deletes === 'fail-first' && this.deleteCalls === 1)
+      )
+        throw new Error('R2 unavailable');
+      await this.env.TIER_TEST.delete(keys);
+      if (this.deletes === 'delete-then-fail')
+        throw new Error('R2 response lost');
+    };
+    return new Proxy(this.env.TIER_TEST, {
+      get: (target, property) => {
+        if (property === 'delete') return remove;
+        // The binding's methods only run on the binding itself.
+        const value: unknown = Reflect.get(target, property);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+  }
+
+  private async resultStore(): Promise<ResultStore> {
+    const db = await this.database();
+    this.store ??= new ResultStore(db, {
+      ...(this.withBucket ? { bucket: this.bucket() } : {}),
       prefix: `test-${this.ctx.id.toString()}`,
       ttlMs: 60 * 60 * 1000,
       r2MinBytes: this.r2MinBytes,
@@ -40,12 +85,101 @@ export class ResultStoreTestDO extends DurableObject<{ TIER_TEST: R2Bucket }> {
   async configure(opts: {
     r2MinBytes?: number;
     withBucket?: boolean;
+    failingDeletes?: boolean;
+    deletes?: 'ok' | 'fail' | 'delete-then-fail' | 'fail-first';
   }): Promise<void> {
     if (opts.r2MinBytes !== undefined) this.r2MinBytes = opts.r2MinBytes;
     if (opts.withBucket !== undefined) this.withBucket = opts.withBucket;
+    if (opts.failingDeletes !== undefined)
+      this.deletes = opts.failingDeletes ? 'fail' : 'ok';
+    if (opts.deletes !== undefined) this.deletes = opts.deletes;
+    this.deleteCalls = 0;
     this.store = undefined;
   }
 
+  /**
+   * Delete one session's results while another session stores the same
+   * content: the put starts while the delete waits on R2, and R2 answers
+   * after the put had time to finish. Returns how the result reads then.
+   */
+  async deleteWhilePutting(input: {
+    deleting: string;
+    putting: string;
+    content: string;
+  }): Promise<ReadResultOutcome> {
+    const store = await this.resultStore();
+    await store.setup();
+    let reached!: () => void;
+    const atDelete = new Promise<void>((resolve) => {
+      reached = resolve;
+    });
+    let release!: () => void;
+    this.deleteHold = {
+      reached,
+      release: new Promise<void>((resolve) => {
+        release = resolve;
+      }),
+    };
+    const deleting = store.deleteForSession(input.deleting);
+    await atDelete;
+    const putting = store.put({
+      sessionId: input.putting,
+      toolName: 't',
+      content: input.content,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    release();
+    const [, ref] = await Promise.all([deleting, putting]);
+    this.deleteHold = null;
+    if (!ref) throw new Error('the result was not stored');
+    return store.read(ref.id, 0, 5);
+  }
+
+  /**
+   * Rows as a store written before results were shared across sessions
+   * left them: the `tool_results` table alone. Call before any other method.
+   */
+  async seedLegacy(
+    rows: Array<{ id: string; sessionId: string; content: string }>,
+  ): Promise<void> {
+    const db = await this.database();
+    await db.run(`
+      CREATE TABLE IF NOT EXISTS tool_results (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        tool_name TEXT NOT NULL,
+        size INTEGER NOT NULL,
+        tier TEXT NOT NULL,
+        content TEXT,
+        created_at TEXT NOT NULL,
+        expires_at INTEGER NOT NULL
+      )`);
+    for (const row of rows)
+      await db.run(
+        `INSERT INTO tool_results VALUES (?, ?, 't', ?, 'sqlite', ?, ?, ?)`,
+        [
+          row.id,
+          row.sessionId,
+          new TextEncoder().encode(row.content).byteLength,
+          row.content,
+          new Date(this.nowMs).toISOString(),
+          this.nowMs + 60 * 60 * 1000,
+        ],
+      );
+  }
+
+  /** Re-open the store over the same database (the next boot). */
+  async reboot(): Promise<void> {
+    this.store = undefined;
+  }
+
+  async references(): Promise<Array<{ id: string; session_id: string }>> {
+    const db = await this.database();
+    return db.exec<{ id: string; session_id: string }>(
+      `SELECT id, session_id FROM tool_result_sessions ORDER BY id, session_id`,
+    );
+  }
+
   async setNow(ms: number): Promise<void> {
     this.nowMs = ms;
   }