or3-provider-sqlite 0.0.9 → 0.0.10

package/README.md

@@ -5,7 +5,7 @@ SQLite sync and workspace store provider for OR3 Chat. Provides a lightweight, s
 ## What it provides
 
 - **AuthWorkspaceStore** (`sqlite`) — user identity mapping, workspace CRUD, role resolution
-- **SyncGatewayAdapter** (`sqlite`) — push/pull sync, consistent materialized snapshot pages, LWW conflict resolution, and cursor tracking
+- **SyncGatewayAdapter** (`sqlite`) — push/pull sync, consistent materialized snapshot pages, LWW conflict resolution, cursor tracking, and canonical background-generation history on synchronous SQLite runtimes
 - **ConnectStore** (`sqlite`) — durable, atomic device enrollment and connected-computer records for OR3 Connect
 - **WebhookStore** (`sqlite`) — durable webhook registrations and delivery logs (local, Bun, and Turso runtimes)
 - **Admin stores** (`sqlite`) — workspace access/lifecycle, workspace settings, user search, and deployment-admin grants (local, Bun, and Turso runtimes)
@@ -142,6 +142,13 @@ Ordered migrations create and evolve all tables:
 - **009_or3_connect**: single-use device authorizations and connected computers
 - **017_background_jobs**: durable job status, workflow snapshots, cancellation,
   inactivity timestamps, and worker leases
+- **018–020**: durable pre-admission cancellation, reasoning/generation history
+  phases, and idempotent canonical generation-write receipts
+
+Background-job claims reset text and iteration progress back to the durable
+checkpoint when reclaiming an expired lease, matching the memory/Convex recovery
+contract. The provider implements `findJobByIdempotencyKey`, which lets the
+server cancel an admission before the client has received its job ID.
 
 Additional migrations (007–008, 010–016) evolve device-cursor ownership,
 upload intents, and Connect credential/lifecycle hardening and rate limits.
@@ -151,16 +158,24 @@ All tables use snake_case aligned with the sync wire format.
 ### Sync semantics
 
 - **Push**: validates ops (including a 256 KB serialized payload ceiling per operation) → checks `op_id` idempotency → allocates contiguous `server_version` block → writes change_log → applies LWW to materialized tables → upserts tombstones for deletes
-- **Pull**: returns ordered changes for `server_version > cursor` with limit/pagination and optional table filtering
-- **Snapshot**: captures canonical live rows and current tombstones at one `highWatermark`, then serves immutable, keyset-paginated pages ordered by `(tableName, pk, kind)`
+- **Pull**: returns ordered changes for `server_version > cursor` with limit/pagination, optional table filtering, `oldestRetainedVersion`, and `requiresSnapshot` when the cursor is behind retained history
+- **Snapshot**: captures canonical live rows and current tombstones at one `highWatermark`, then serves immutable, keyset-paginated pages ordered by `(tableName, pk, kind)`. Notification live rows are filtered to the session user.
 - **Cursor**: forward-only per-device cursor tracking
 - **Retention safety**: tombstone and `change_log` GC is enabled only under the explicit `snapshot-v1` capability and deletes old revisions acknowledged by every registered device
+- **Notifications**: push forces `payload.user_id` to the session user; foreign notification writes are rejected; pull/snapshot omit other users' rows
 
-LWW conflict resolution: incoming wins when `clock` is higher, or when clocks are equal and `hlc` is lexicographically greater.
+LWW conflict resolution: incoming wins when `clock` is higher, then when clocks are equal and `hlc` is lexicographically greater, then when `op_id` is greater. Tombstones use the same `(clock, hlc, op_id)` tuple. LWW losers return `applied: false` with the winning payload.
 
 Local, Bun, and Turso runtimes use `BEGIN IMMEDIATE` transactions. D1 uses its
 native atomic batch API for grouped writes.
 
+Canonical background generation history is advertised by the local, Bun, and
+Turso adapters. It writes admission rows, contiguous change-log versions,
+materialized state, and the receipt in one transaction, then commits a terminal
+snapshot only if its generation still owns the assistant row. D1 does not
+advertise this versioned capability, so background chat admission fails before
+model execution there; ordinary sync and other D1 features are unchanged.
+
 ### Workspace store
 
 - `getOrCreateUser` — maps `(provider, provider_user_id)` to internal user (idempotent)

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "or3-provider-sqlite",
   "configKey": "or3-provider-sqlite",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/server/background-jobs/sqlite-provider.d.ts

@@ -1,8 +1,10 @@
-import type { BackgroundJob, BackgroundJobExecution, BackgroundJobProvider, CreateJobParams, JobUpdate } from '~~/server/utils/background-jobs/types';
+import type { BackgroundJob, BackgroundJobExecution, BackgroundJobProvider, CreateJobParams, JobUpdate, AdmissionCancellationResult, GenerationHistoryPhase, TerminalGenerationSnapshot } from '~~/server/utils/background-jobs/types';
 export declare class SqliteBackgroundJobProvider implements BackgroundJobProvider {
     readonly name = "sqlite";
     createJob(params: CreateJobParams): Promise<string>;
     getJob(jobId: string, userId: string): Promise<BackgroundJob | null>;
+    findJobByIdempotencyKey(idempotencyKey: string, userId: string): Promise<BackgroundJob | null>;
+    cancelAdmission(userId: string, admissionId: string): Promise<AdmissionCancellationResult>;
     updateJob(jobId: string, update: JobUpdate): Promise<void>;
     completeJob(jobId: string, finalContent: string, leaseOwner?: string): Promise<void>;
     failJob(jobId: string, error: string, leaseOwner?: string): Promise<void>;
@@ -14,6 +16,11 @@ export declare class SqliteBackgroundJobProvider implements BackgroundJobProvide
     claimNextJob(leaseOwner: string, now: number, leaseExpiresAt: number): Promise<BackgroundJob | null>;
     renewJobLease(jobId: string, leaseOwner: string, _now: number, leaseExpiresAt: number): Promise<boolean>;
     updateJobExecution(jobId: string, execution: BackgroundJobExecution, leaseOwner: string): Promise<boolean>;
+    saveTerminalSnapshot(jobId: string, snapshot: TerminalGenerationSnapshot, leaseOwner?: string): Promise<boolean>;
+    setHistoryPhase(jobId: string, phase: GenerationHistoryPhase, options?: {
+        from?: GenerationHistoryPhase[];
+    }): Promise<boolean>;
+    getPendingHistoryJobs(limit: number): Promise<BackgroundJob[]>;
     cleanupExpired(): Promise<number>;
     getActiveJobCount(): Promise<number>;
 }

package/dist/runtime/server/background-jobs/sqlite-provider.js

@@ -19,6 +19,10 @@ function toJob(row) {
     kind: row.kind ?? void 0,
     status: row.status,
     content: row.content,
+    reasoning: row.reasoning ?? "",
+    generationId: row.generation_id ?? void 0,
+    historyPhase: row.history_phase ?? void 0,
+    syncProviderId: row.sync_provider_id ?? void 0,
     chunksReceived: row.chunks_received,
     startedAt: row.started_at,
     lastActivityAt: row.last_activity_at,
@@ -54,6 +58,24 @@ function leaseLost() {
   error.name = "BackgroundJobLeaseLostError";
   return error;
 }
+const ADMISSION_CANCEL_TTL_MS = 10 * 60 * 1e3;
+function admissionCancelled(admissionId) {
+  const error = new Error(
+    `Background admission ${admissionId} was cancelled`
+  );
+  error.name = "AdmissionCancelledError";
+  return error;
+}
+async function isAdmissionCancelled(userId, admissionId, now) {
+  const row = await one(
+    `SELECT 1 AS hit FROM background_admission_cancels
+         WHERE user_id = ? AND admission_id = ? AND expires_at > ?`,
+    userId,
+    admissionId,
+    now
+  );
+  return row !== void 0;
+}
 function insertParameters(id, params, now) {
   return [
     id,
@@ -62,6 +84,11 @@ function insertParameters(id, params, now) {
     params.messageId,
     params.model,
     params.kind ?? null,
+    params.initialContent ?? "",
+    params.initialReasoning ?? "",
+    params.generationId ?? null,
+    params.historyPhase ?? "ready",
+    params.syncProviderId ?? null,
     now,
     now,
     json(params.tool_calls),
@@ -72,16 +99,22 @@ function insertParameters(id, params, now) {
 }
 const INSERT_JOB = `INSERT INTO background_jobs (
     id, user_id, thread_id, message_id, model, kind, status, content,
+    reasoning, generation_id, history_phase, sync_provider_id,
     chunks_received, started_at, last_activity_at, tool_calls_json,
     workflow_state_json, execution_json, idempotency_key, attempts
-) VALUES (?, ?, ?, ?, ?, ?, 'streaming', '', 0, ?, ?, ?, ?, ?, ?, 0)`;
+) VALUES (?, ?, ?, ?, ?, ?, 'streaming', ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, 0)`;
 const INSERT_JOB_IF_CAPACITY = `INSERT INTO background_jobs (
     id, user_id, thread_id, message_id, model, kind, status, content,
+    reasoning, generation_id, history_phase, sync_provider_id,
     chunks_received, started_at, last_activity_at, tool_calls_json,
     workflow_state_json, execution_json, idempotency_key, attempts
-) SELECT ?, ?, ?, ?, ?, ?, 'streaming', '', 0, ?, ?, ?, ?, ?, ?, 0
+) SELECT ?, ?, ?, ?, ?, ?, 'streaming', ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, 0
   WHERE (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming') < ?
     AND (SELECT COUNT(*) FROM background_jobs WHERE status = 'streaming' AND user_id = ?) < ?
+    AND NOT EXISTS (
+        SELECT 1 FROM background_admission_cancels
+        WHERE user_id = ? AND admission_id = ? AND expires_at > ?
+    )
   ON CONFLICT(idempotency_key) DO NOTHING
   RETURNING id`;
 export class SqliteBackgroundJobProvider {
@@ -97,13 +130,23 @@ export class SqliteBackgroundJobProvider {
           params.idempotencyKey
         );
         if (existing) return existing.id;
+        if (await isAdmissionCancelled(
+          params.userId,
+          params.idempotencyKey,
+          now
+        )) {
+          throw admissionCancelled(params.idempotencyKey);
+        }
       }
       const inserted = await all(
         INSERT_JOB_IF_CAPACITY,
         ...insertParameters(id, params, now),
         config.maxConcurrentJobs,
         params.userId,
-        config.maxConcurrentJobsPerUser
+        config.maxConcurrentJobsPerUser,
+        params.userId,
+        params.idempotencyKey ?? "",
+        now
       );
       if (inserted[0]) return inserted[0].id;
       if (params.idempotencyKey) {
@@ -112,6 +155,13 @@ export class SqliteBackgroundJobProvider {
           params.idempotencyKey
         );
         if (existing) return existing.id;
+        if (await isAdmissionCancelled(
+          params.userId,
+          params.idempotencyKey,
+          now
+        )) {
+          throw admissionCancelled(params.idempotencyKey);
+        }
       }
       throw new Error("Maximum concurrent background jobs reached");
     }
@@ -122,6 +172,18 @@ export class SqliteBackgroundJobProvider {
           "SELECT id FROM background_jobs WHERE idempotency_key = ?"
         ).get(params.idempotencyKey);
         if (existing) return existing.id;
+        const cancelled = raw.prepare(
+          `SELECT 1 AS hit FROM background_admission_cancels
+                             WHERE user_id = ? AND admission_id = ?
+                               AND expires_at > ?`
+        ).get(
+          params.userId,
+          params.idempotencyKey,
+          now
+        );
+        if (cancelled) {
+          throw admissionCancelled(params.idempotencyKey);
+        }
       }
       const active = raw.prepare(
         `SELECT COUNT(*) AS total,
@@ -146,6 +208,89 @@ export class SqliteBackgroundJobProvider {
     );
     return row ? toJob(row) : null;
   }
+  async findJobByIdempotencyKey(idempotencyKey, userId) {
+    const row = await one(
+      "SELECT * FROM background_jobs WHERE idempotency_key = ? AND user_id = ?",
+      idempotencyKey,
+      userId
+    );
+    return row ? toJob(row) : null;
+  }
+  async cancelAdmission(userId, admissionId) {
+    const now = Date.now();
+    const expiresAt = now + ADMISSION_CANCEL_TTL_MS;
+    const upsertMarker = `INSERT INTO background_admission_cancels
+                (user_id, admission_id, expires_at)
+             VALUES (?, ?, ?)
+             ON CONFLICT(user_id, admission_id)
+             DO UPDATE SET expires_at = excluded.expires_at`;
+    const abortJob = `UPDATE background_jobs SET status = 'aborted',
+                completed_at = ?, last_activity_at = ?, error = ?,
+                lease_owner = NULL, lease_expires_at = NULL,
+                history_phase = CASE
+                    WHEN generation_id IS NOT NULL
+                      AND COALESCE(history_phase, 'ready') = 'ready'
+                    THEN 'finalization_pending'
+                    ELSE history_phase END
+             WHERE id = ? AND status = 'streaming'`;
+    if (!isD1Driver()) {
+      const raw = getRawDb();
+      return raw.transaction(() => {
+        raw.prepare(
+          "DELETE FROM background_admission_cancels WHERE expires_at <= ?"
+        ).run(now);
+        raw.prepare(upsertMarker).run(userId, admissionId, expiresAt);
+        const job2 = raw.prepare(
+          "SELECT id, status FROM background_jobs WHERE user_id = ? AND idempotency_key = ?"
+        ).get(userId, admissionId);
+        if (!job2) {
+          return { aborted: false, pending: true };
+        }
+        if (job2.status === "streaming") {
+          const changes = raw.prepare(abortJob).run(
+            now,
+            now,
+            "Cancelled by user",
+            job2.id
+          ).changes;
+          return {
+            aborted: changes > 0,
+            jobId: job2.id,
+            pending: false
+          };
+        }
+        return { aborted: false, jobId: job2.id, pending: false };
+      }).immediate();
+    }
+    await run(
+      "DELETE FROM background_admission_cancels WHERE expires_at <= ?",
+      now
+    );
+    await run(upsertMarker, userId, admissionId, expiresAt);
+    const job = await one(
+      "SELECT id, status FROM background_jobs WHERE user_id = ? AND idempotency_key = ?",
+      userId,
+      admissionId
+    );
+    if (!job) {
+      return { aborted: false, pending: true };
+    }
+    if (job.status === "streaming") {
+      const changes = await run(
+        abortJob,
+        now,
+        now,
+        "Cancelled by user",
+        job.id
+      );
+      return {
+        aborted: changes > 0,
+        jobId: job.id,
+        pending: false
+      };
+    }
+    return { aborted: false, jobId: job.id, pending: false };
+  }
   async updateJob(jobId, update) {
     const sets = ["last_activity_at = ?"];
     const values = [Date.now()];
@@ -153,6 +298,10 @@ export class SqliteBackgroundJobProvider {
       sets.push("content = content || ?");
       values.push(update.contentChunk);
     }
+    if (update.reasoningChunk !== void 0) {
+      sets.push("reasoning = reasoning || ?");
+      values.push(update.reasoningChunk);
+    }
     if (update.chunksReceived !== void 0) {
       sets.push("chunks_received = ?");
       values.push(update.chunksReceived);
@@ -168,8 +317,9 @@ export class SqliteBackgroundJobProvider {
     values.push(jobId);
     let where = "id = ? AND status = 'streaming'";
     if (update.leaseOwner) {
-      where += " AND lease_owner = ?";
+      where += " AND lease_owner = ? AND lease_expires_at > ?";
       values.push(update.leaseOwner);
+      values.push(Date.now());
     }
     const changes = await run(
       `UPDATE background_jobs SET ${sets.join(", ")} WHERE ${where}`,
@@ -206,7 +356,12 @@ export class SqliteBackgroundJobProvider {
     const now = Date.now();
     return await run(
       `UPDATE background_jobs SET status = 'aborted', completed_at = ?,
-                last_activity_at = ?, lease_owner = NULL, lease_expires_at = NULL
+                last_activity_at = ?, lease_owner = NULL, lease_expires_at = NULL,
+                history_phase = CASE
+                    WHEN generation_id IS NOT NULL
+                      AND COALESCE(history_phase, 'ready') = 'ready'
+                    THEN 'finalization_pending'
+                    ELSE history_phase END
              WHERE id = ? AND user_id = ? AND status = 'streaming'`,
       now,
       now,
@@ -226,12 +381,25 @@ export class SqliteBackgroundJobProvider {
   }
   async claimJob(jobId, leaseOwner, now, leaseExpiresAt) {
     const row = await one(
-      `UPDATE background_jobs SET lease_owner = ?, lease_expires_at = ?, attempts = attempts + 1
+      `UPDATE background_jobs SET
+                lease_owner = ?,
+                lease_expires_at = ?,
+                last_activity_at = ?,
+                content = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.contentBase'), '')
+                    ELSE content END,
+                reasoning = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.reasoningBase'), '')
+                    ELSE reasoning END,
+                chunks_received = CASE WHEN attempts > 0 THEN 0 ELSE chunks_received END,
+                attempts = attempts + 1
              WHERE id = ? AND status = 'streaming' AND execution_json IS NOT NULL
+               AND COALESCE(history_phase, 'ready') = 'ready'
                AND (lease_owner IS NULL OR lease_expires_at <= ?)
              RETURNING *`,
       leaseOwner,
       leaseExpiresAt,
+      now,
       jobId,
       now
     );
@@ -239,15 +407,28 @@ export class SqliteBackgroundJobProvider {
   }
   async claimNextJob(leaseOwner, now, leaseExpiresAt) {
     const row = await one(
-      `UPDATE background_jobs SET lease_owner = ?, lease_expires_at = ?, attempts = attempts + 1
+      `UPDATE background_jobs SET
+                lease_owner = ?,
+                lease_expires_at = ?,
+                last_activity_at = ?,
+                content = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.contentBase'), '')
+                    ELSE content END,
+                reasoning = CASE WHEN attempts > 0
+                    THEN COALESCE(json_extract(execution_json, '$.reasoningBase'), '')
+                    ELSE reasoning END,
+                chunks_received = CASE WHEN attempts > 0 THEN 0 ELSE chunks_received END,
+                attempts = attempts + 1
              WHERE id = (
                 SELECT id FROM background_jobs
                 WHERE status = 'streaming' AND execution_json IS NOT NULL
+                  AND COALESCE(history_phase, 'ready') = 'ready'
                   AND (lease_owner IS NULL OR lease_expires_at <= ?)
                 ORDER BY started_at ASC LIMIT 1
              ) RETURNING *`,
       leaseOwner,
       leaseExpiresAt,
+      now,
       now
     );
     return row ? toJob(row) : null;
@@ -255,11 +436,13 @@ export class SqliteBackgroundJobProvider {
   async renewJobLease(jobId, leaseOwner, _now, leaseExpiresAt) {
     return await run(
       `UPDATE background_jobs SET lease_expires_at = ?, last_activity_at = ?
-             WHERE id = ? AND status = 'streaming' AND lease_owner = ?`,
+             WHERE id = ? AND status = 'streaming' AND lease_owner = ?
+               AND lease_expires_at > ?`,
       leaseExpiresAt,
       Date.now(),
       jobId,
-      leaseOwner
+      leaseOwner,
+      Date.now()
     ) > 0;
   }
   async updateJobExecution(jobId, execution, leaseOwner) {
@@ -272,19 +455,73 @@ export class SqliteBackgroundJobProvider {
       leaseOwner
     ) > 0;
   }
+  async saveTerminalSnapshot(jobId, snapshot, leaseOwner) {
+    const values = [
+      snapshot.status,
+      snapshot.content,
+      snapshot.reasoning,
+      json(snapshot.toolCalls),
+      snapshot.error ?? null,
+      snapshot.completedAt,
+      snapshot.completedAt
+    ];
+    let where = "id = ? AND status = 'streaming'";
+    values.push(jobId);
+    if (leaseOwner) {
+      where += " AND lease_owner = ? AND lease_expires_at > ?";
+      values.push(leaseOwner, Date.now());
+    }
+    return await run(
+      `UPDATE background_jobs SET status = ?, content = ?, reasoning = ?,
+                    tool_calls_json = ?, error = ?, completed_at = ?,
+                    history_phase = 'finalization_pending',
+                    last_activity_at = ?, lease_owner = NULL, lease_expires_at = NULL
+                 WHERE ${where}`,
+      ...values
+    ) > 0;
+  }
+  async setHistoryPhase(jobId, phase, options) {
+    const values = [phase, jobId];
+    let where = "id = ?";
+    if (options?.from && options.from.length > 0) {
+      const placeholders = options.from.map(() => "?").join(", ");
+      where += ` AND COALESCE(history_phase, 'ready') IN (${placeholders})`;
+      values.push(...options.from);
+    }
+    return await run(`UPDATE background_jobs SET history_phase = ? WHERE ${where}`, ...values) > 0;
+  }
+  async getPendingHistoryJobs(limit) {
+    const rows = await all(
+      `SELECT * FROM background_jobs
+             WHERE history_phase IN ('admission_pending', 'finalization_pending')
+             ORDER BY started_at ASC
+             LIMIT ?`,
+      Math.max(1, Math.min(100, Math.floor(limit)))
+    );
+    return rows.map(toJob);
+  }
   async cleanupExpired() {
     const config = getJobConfig();
     const now = Date.now();
     const timedOut = await run(
       `UPDATE background_jobs SET status = 'error', error = 'Job timed out',
-                completed_at = ?, lease_owner = NULL, lease_expires_at = NULL
+                completed_at = ?, lease_owner = NULL, lease_expires_at = NULL,
+                history_phase = CASE
+                    WHEN generation_id IS NOT NULL
+                      AND COALESCE(history_phase, 'ready') = 'ready'
+                    THEN 'finalization_pending'
+                    ELSE history_phase END
              WHERE status = 'streaming' AND last_activity_at <= ?`,
       now,
       now - config.jobTimeoutMs
     );
     const removed = await run(
       `DELETE FROM background_jobs
-             WHERE status != 'streaming' AND completed_at IS NOT NULL AND completed_at <= ?`,
+             WHERE status != 'streaming' AND completed_at IS NOT NULL AND completed_at <= ?
+               AND (
+                 history_phase IS NULL
+                 OR history_phase IN ('ready', 'committed', 'superseded')
+               )`,
       now - config.completedJobRetentionMs
     );
     return timedOut + removed;

package/dist/runtime/server/db/migrate.js

@@ -16,6 +16,9 @@ import * as m014 from "./migrations/014_connect_retention_activation.js";
 import * as m015 from "./migrations/015_rate_limits.js";
 import * as m016 from "./migrations/016_connect_runtime_binding.js";
 import * as m017 from "./migrations/017_background_jobs.js";
+import * as m018 from "./migrations/018_background_admission_cancels.js";
+import * as m019 from "./migrations/019_background_generation_history.js";
+import * as m020 from "./migrations/020_background_generation_receipts.js";
 const REQUIRED_SCHEMA_TABLES = [
   "users",
   "auth_accounts",
@@ -41,7 +44,9 @@ const REQUIRED_SCHEMA_TABLES = [
   "connect_device_authorizations",
   "connect_environments",
   "rate_limits",
-  "background_jobs"
+  "background_jobs",
+  "background_admission_cancels",
+  "background_generation_receipts"
 ];
 const migrations = {
   "001_init": m001,
@@ -60,7 +65,10 @@ const migrations = {
   "014_connect_retention_activation": m014,
   "015_rate_limits": m015,
   "016_connect_runtime_binding": m016,
-  "017_background_jobs": m017
+  "017_background_jobs": m017,
+  "018_background_admission_cancels": m018,
+  "019_background_generation_history": m019,
+  "020_background_generation_receipts": m020
 };
 class StaticMigrationProvider {
   async getMigrations() {

package/dist/runtime/server/db/migrations/018_background_admission_cancels.d.ts

@@ -0,0 +1,7 @@
+import { type Kysely } from 'kysely';
+/**
+ * Durable admission cancellations. Creation and cancellation both check this
+ * table so a Stop that arrives before the job row commits cannot launch work.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/runtime/server/db/migrations/018_background_admission_cancels.js

@@ -0,0 +1,18 @@
+import { sql } from "kysely";
+export async function up(db) {
+  await sql`
+        CREATE TABLE IF NOT EXISTS background_admission_cancels (
+            user_id TEXT NOT NULL,
+            admission_id TEXT NOT NULL,
+            expires_at INTEGER NOT NULL,
+            PRIMARY KEY (user_id, admission_id)
+        )
+    `.execute(db);
+  await sql`
+        CREATE INDEX IF NOT EXISTS background_admission_cancels_expiry
+        ON background_admission_cancels(expires_at)
+    `.execute(db);
+}
+export async function down(db) {
+  await sql`DROP TABLE IF EXISTS background_admission_cancels`.execute(db);
+}

package/dist/runtime/server/db/migrations/019_background_generation_history.d.ts

@@ -0,0 +1,7 @@
+import { type Kysely } from 'kysely';
+/**
+ * Generation identity, durable history phase, and accumulated reasoning on
+ * background jobs. Reasoning is kept distinct from request reasoning config.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/runtime/server/db/migrations/019_background_generation_history.js

@@ -0,0 +1,25 @@
+import { sql } from "kysely";
+export async function up(db) {
+  await sql`
+        ALTER TABLE background_jobs
+        ADD COLUMN reasoning TEXT NOT NULL DEFAULT ''
+    `.execute(db);
+  await sql`
+        ALTER TABLE background_jobs
+        ADD COLUMN generation_id TEXT
+    `.execute(db);
+  await sql`
+        ALTER TABLE background_jobs
+        ADD COLUMN history_phase TEXT
+    `.execute(db);
+  await sql`
+        ALTER TABLE background_jobs
+        ADD COLUMN sync_provider_id TEXT
+    `.execute(db);
+}
+export async function down(db) {
+  await sql`ALTER TABLE background_jobs DROP COLUMN sync_provider_id`.execute(db);
+  await sql`ALTER TABLE background_jobs DROP COLUMN history_phase`.execute(db);
+  await sql`ALTER TABLE background_jobs DROP COLUMN generation_id`.execute(db);
+  await sql`ALTER TABLE background_jobs DROP COLUMN reasoning`.execute(db);
+}

package/dist/runtime/server/db/migrations/020_background_generation_receipts.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+/** Durable replay receipts for canonical background-history transactions. */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/runtime/server/db/migrations/020_background_generation_receipts.js

@@ -0,0 +1,19 @@
+import { sql } from "kysely";
+export async function up(db) {
+  await sql`
+        CREATE TABLE background_generation_receipts (
+            id TEXT PRIMARY KEY,
+            workspace_id TEXT NOT NULL,
+            generation_id TEXT NOT NULL,
+            stage TEXT NOT NULL CHECK(stage IN ('admission', 'finalization')),
+            fingerprint TEXT NOT NULL,
+            outcome TEXT NOT NULL,
+            server_version INTEGER,
+            created_at INTEGER NOT NULL,
+            UNIQUE(workspace_id, generation_id, stage)
+        )
+    `.execute(db);
+}
+export async function down(db) {
+  await sql`DROP TABLE IF EXISTS background_generation_receipts`.execute(db);
+}

package/dist/runtime/server/db/schema.d.ts

@@ -197,6 +197,10 @@ export interface BackgroundJobsTable {
     kind: string | null;
     status: 'streaming' | 'complete' | 'error' | 'aborted';
     content: string;
+    reasoning: string;
+    generation_id: string | null;
+    history_phase: string | null;
+    sync_provider_id: string | null;
     chunks_received: number;
     started_at: number;
     last_activity_at: number;
@@ -210,6 +214,16 @@ export interface BackgroundJobsTable {
     lease_expires_at: number | null;
     attempts: number;
 }
+export interface BackgroundGenerationReceiptsTable {
+    id: string;
+    workspace_id: string;
+    generation_id: string;
+    stage: 'admission' | 'finalization';
+    fingerprint: string;
+    outcome: string;
+    server_version: number | null;
+    created_at: number;
+}
 export interface AdminUsersTable {
     user_id: string;
     created_at: number;
@@ -239,6 +253,7 @@ export interface Or3SqliteDb {
     connect_environments: ConnectEnvironmentsTable;
     rate_limits: RateLimitsTable;
     background_jobs: BackgroundJobsTable;
+    background_generation_receipts: BackgroundGenerationReceiptsTable;
     s_threads: SyncedEntityTable;
     s_messages: SyncedEntityTable;
     s_projects: SyncedEntityTable;

package/dist/runtime/server/sync/history-gc-policy.d.ts

@@ -11,3 +11,11 @@ export declare const SYNC_HISTORY_GC_POLICY: Readonly<{
     reason: "SQLite history GC is guarded by the verified snapshot-v1 retention contract.";
 }>;
 export declare function canRunSyncHistoryGc(): boolean;
+export declare function computePullRetention(input: {
+    cursor: number;
+    oldestLogVersion: number | null;
+    highWatermark: number;
+}): {
+    oldestRetainedVersion: number;
+    requiresSnapshot: boolean;
+};

package/dist/runtime/server/sync/history-gc-policy.js

@@ -6,3 +6,10 @@ export const SYNC_HISTORY_GC_POLICY = Object.freeze({
 export function canRunSyncHistoryGc() {
   return SYNC_HISTORY_GC_POLICY.enabled && SYNC_HISTORY_GC_POLICY.snapshotBootstrapVerified;
 }
+export function computePullRetention(input) {
+  const oldestRetainedVersion = input.oldestLogVersion ?? Math.max(0, input.highWatermark) + 1;
+  return {
+    oldestRetainedVersion,
+    requiresSnapshot: oldestRetainedVersion > 0 && input.cursor < Math.max(0, oldestRetainedVersion - 1)
+  };
+}