@gmickel/gno 1.20.0 → 1.21.0

package/src/mcp/tools/changes.ts

@@ -0,0 +1,80 @@
+/** Read-only MCP adapters for knowledge change, diff, and impact services. */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+} from "../../core/knowledge-delta";
+import { runTool, type ToolResult } from "./index";
+
+export const changesInputSchema = z.object({
+  since: z.string().trim().min(1).max(512).optional(),
+  collection: z.string().trim().min(1).max(256).optional(),
+  limit: z.number().int().min(1).max(1000).default(100),
+});
+
+export const diffInputSchema = z.object({
+  ref: z.string().trim().min(1).max(4096),
+  change: z.string().trim().min(1).max(512).optional(),
+});
+
+export const impactInputSchema = z.object({
+  ref: z.string().trim().min(1).max(4096),
+  maxDepth: z.number().int().min(1).max(6).default(3),
+  maxNodes: z.number().int().min(1).max(1000).default(100),
+  maxEdges: z.number().int().min(1).max(5000).default(250),
+  frontierLimit: z.number().int().min(1).max(1000).default(100),
+  visitedLimit: z.number().int().min(1).max(5000).default(500),
+});
+
+const unwrap = <T>(
+  result:
+    | { success: true; data: T }
+    | { success: false; error: string; isValidation?: boolean }
+): T => {
+  if (result.success) return result.data;
+  throw new Error(
+    `${result.isValidation ? "VALIDATION" : "RUNTIME"}: ${result.error}`
+  );
+};
+
+export const handleChanges = (
+  args: z.infer<typeof changesInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_changes",
+    async () => unwrap(await listKnowledgeChanges(ctx.store, args)),
+    (data) =>
+      `${data.changes.length} retained document changes${data.page.truncated ? " (more available)" : ""}`
+  );
+
+export const handleDiff = (
+  args: z.infer<typeof diffInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_diff",
+    async () =>
+      unwrap(await getKnowledgeDiff(ctx.store, args.ref, args.change)),
+    (data) =>
+      `Structural diff for ${data.document.uri}: ${data.status}; history ${data.history.status}; source bodies not retained`
+  );
+
+export const handleImpact = (
+  args: z.infer<typeof impactInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_impact",
+    async () => unwrap(await analyzeKnowledgeImpact(ctx.store, args.ref, args)),
+    (data) =>
+      `${data.impacted.length} documents depend on ${data.root.uri}${data.meta.truncated ? " (truncated)" : ""}`
+  );

package/src/mcp/tools/index.ts

@@ -21,6 +21,14 @@ import { normalizeTag } from "../../core/tags";
 import { handleAddCollection } from "./add-collection";
 import { askInputSchema, handleAsk } from "./ask";
 import { handleCapture } from "./capture";
+import {
+  changesInputSchema,
+  diffInputSchema,
+  handleChanges,
+  handleDiff,
+  handleImpact,
+  impactInputSchema,
+} from "./changes";
 import { handleClearCollectionEmbeddings } from "./clear-collection-embeddings";
 import { handleContext, handleContextVerify } from "./context";
 import { handleEmbed } from "./embed";
@@ -1036,6 +1044,27 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleStatus(args, ctx)
   );
 
+  server.tool(
+    "gno_changes",
+    "List retained metadata-only document changes with opaque cursor pagination and retention disclosure.",
+    changesInputSchema.shape,
+    (args) => handleChanges(args, ctx)
+  );
+
+  server.tool(
+    "gno_diff",
+    "Inspect one retained metadata-only structural document change. Source bodies are never returned.",
+    diffInputSchema.shape,
+    (args) => handleDiff(args, ctx)
+  );
+
+  server.tool(
+    "gno_impact",
+    "Find bounded inbound typed, wiki, and Markdown dependencies with deterministic evidence paths.",
+    impactInputSchema.shape,
+    (args) => handleImpact(args, ctx)
+  );
+
   server.tool(
     "gno_trace_list",
     "List bounded metadata-only summaries of private local retrieval traces. Raw replay queries are omitted from history.",

package/src/sdk/client.ts

@@ -40,6 +40,11 @@ import type {
   GnoRenameNoteOptions,
   GnoUpdateOptions,
   GnoVectorSearchOptions,
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
 } from "./types";
 
 import {
@@ -84,6 +89,12 @@ import {
   planRenameRefactor,
 } from "../core/file-refactors";
 import { resolveEffectiveIndex } from "../core/indexed-reference";
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+  type KnowledgeDeltaServiceResult,
+} from "../core/knowledge-delta";
 import { resolveNoteCreatePlan } from "../core/note-creation";
 import { resolveNotePreset } from "../core/note-presets";
 import { RetrievalTraceManagementService } from "../core/retrieval-trace-management";
@@ -174,6 +185,11 @@ function unwrapTraceStore<T>(result: StoreResult<T>): T {
   });
 }
 
+function unwrapKnowledgeDelta<T>(result: KnowledgeDeltaServiceResult<T>): T {
+  if (result.success) return result.data;
+  throw sdkError(result.isValidation ? "VALIDATION" : "STORE", result.error);
+}
+
 async function resolveClientState(
   options: GnoClientInitOptions = {}
 ): Promise<OpenedClientState> {
@@ -1067,6 +1083,32 @@ class GnoClientImpl implements GnoClient {
     };
   }
 
+  async changes(
+    options: ListKnowledgeChangesInput = {}
+  ): Promise<KnowledgeChangesResult> {
+    this.assertOpen();
+    return unwrapKnowledgeDelta(
+      await listKnowledgeChanges(this.store, options)
+    );
+  }
+
+  async diff(ref: string, changeId?: string): Promise<KnowledgeDiffResult> {
+    this.assertOpen();
+    return unwrapKnowledgeDelta(
+      await getKnowledgeDiff(this.store, ref, changeId)
+    );
+  }
+
+  async impact(
+    ref: string,
+    options: KnowledgeImpactInput = {}
+  ): Promise<KnowledgeImpactResult> {
+    this.assertOpen();
+    return unwrapKnowledgeDelta(
+      await analyzeKnowledgeImpact(this.store, ref, options)
+    );
+  }
+
   async status(): Promise<IndexStatus> {
     this.assertOpen();
     return unwrapStore(

package/src/sdk/index.ts

@@ -54,6 +54,13 @@ export type {
   GnoSkippedDocument,
   GnoUpdateOptions,
   GnoVectorSearchOptions,
+  KnowledgeChange,
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactEvidenceStep,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
 } from "./types";
 export {
   ContextCapsuleContractError,

package/src/sdk/types.ts

@@ -17,6 +17,13 @@ import type {
 } from "../core/context-capsule";
 import type { ContextEvidenceErrorCode } from "../core/context-evidence";
 import type { ContextVerifierErrorCode } from "../core/context-verifier";
+import type {
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
+} from "../core/knowledge-delta";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
 import type {
@@ -52,6 +59,15 @@ export type {
   SyncResult,
 };
 export type { AskOptions, HybridSearchOptions } from "../pipeline/types";
+export type {
+  KnowledgeChange,
+  KnowledgeChangesResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactEvidenceStep,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
+} from "../core/knowledge-delta";
 export type { Collection, Config as GnoConfig, Context } from "../config/types";
 export type { GetResponse as GnoGetResult } from "../cli/commands/get";
 export type {
@@ -233,6 +249,12 @@ export interface GnoClient {
   list(
     options?: GnoListOptions
   ): Promise<import("../cli/commands/ls").LsResponse>;
+  changes(options?: ListKnowledgeChangesInput): Promise<KnowledgeChangesResult>;
+  diff(ref: string, changeId?: string): Promise<KnowledgeDiffResult>;
+  impact(
+    ref: string,
+    options?: KnowledgeImpactInput
+  ): Promise<KnowledgeImpactResult>;
   status(): Promise<IndexStatus>;
   listRetrievalTraces(
     options?: RetrievalTraceListRequest

package/src/serve/doc-events.ts

@@ -1,6 +1,6 @@
 export type DocumentEventOrigin = "watcher" | "save" | "create";
 
-export interface DocumentEvent {
+export interface DocumentChangedEvent {
   type: "document-changed";
   uri: string;
   collection: string;
@@ -9,6 +9,17 @@ export interface DocumentEvent {
   changedAt: string;
 }
 
+export interface CapsuleReverifiedEvent {
+  type: "capsule-reverified";
+  registrationId: string;
+  capsuleId: string;
+  operationStatus: "completed" | "failed";
+  affectedQuestionState: "unaffected" | "affected" | "unknown";
+  changedAt: string;
+}
+
+export type DocumentEvent = DocumentChangedEvent | CapsuleReverifiedEvent;
+
 export interface DocumentEventBusState {
   connectedClients: number;
   retryMs: number;

package/src/serve/resident-runtime.ts

@@ -31,6 +31,7 @@ import {
   isInitialized,
   loadConfig,
 } from "../config";
+import { SavedCapsuleReverificationScheduler } from "../core/capsule-reverification-scheduler";
 import { acquireWriteLock } from "../core/file-lock";
 import { JobManager } from "../core/job-manager";
 import { recordContentMutation } from "../core/mutation-generations";
@@ -94,6 +95,7 @@ export interface ResidentRuntime {
   readonly toolMutex: Mutex;
   readonly readerGate: ReaderGate;
   readonly jobManager: JobManager;
+  readonly capsuleReverificationScheduler: SavedCapsuleReverificationScheduler;
   readonly modelManager: ModelManager;
   readonly mcpContext: ToolContext;
   readonly generations: ResidentGeneration;
@@ -266,6 +268,8 @@ export async function startResidentRuntime(
   ctxHolder.current.scheduler = scheduler;
   ctxHolder.current.eventBus = options.eventBus ?? null;
 
+  let capsuleReverificationScheduler: SavedCapsuleReverificationScheduler | null =
+    null;
   const watchService = (
     deps.watchServiceFactory ??
     ((watchOptions) => new DefaultCollectionWatchService(watchOptions))
@@ -282,6 +286,10 @@ export async function startResidentRuntime(
         });
         options.watchCallbacks?.onSyncComplete?.(event);
       },
+      onSettled: () => {
+        capsuleReverificationScheduler?.notifySyncSettled();
+        options.watchCallbacks?.onSettled?.();
+      },
     },
     syncOptions: withContentTypeRules({}, initialConfig),
   });
@@ -312,6 +320,17 @@ export async function startResidentRuntime(
   const backgroundWork = new ResidentBackgroundWork(
     () => !disposed && admission.accepting
   );
+  capsuleReverificationScheduler = new SavedCapsuleReverificationScheduler({
+    deps: {
+      store,
+      get config() {
+        return ctxHolder.config;
+      },
+      indexName: canonicalizeIndexName(options.index ?? DEFAULT_INDEX_NAME),
+      notify: (event) => options.eventBus?.emit(event),
+    },
+    startBackgroundWork: (operation) => backgroundWork.start(operation),
+  });
 
   const mcpContext = createToolContext({
     store,
@@ -355,6 +374,7 @@ export async function startResidentRuntime(
     toolMutex,
     readerGate,
     jobManager,
+    capsuleReverificationScheduler,
     modelManager,
     mcpContext,
     generations,
@@ -453,6 +473,7 @@ export async function startResidentRuntime(
         syncOptions.triggerEmbed === false
           ? null
           : await scheduler.triggerNow();
+      capsuleReverificationScheduler.notifySyncSettled();
       return { syncResult, embedResult };
     },
     async dispose() {
@@ -466,6 +487,7 @@ export async function startResidentRuntime(
       );
       if (deadlineReached) shutdownState = "deadline";
       await backgroundWork.cancelAndDrain();
+      await capsuleReverificationScheduler.dispose();
       await jobManager.shutdown().catch(() => undefined);
       await Promise.allSettled([
         Promise.resolve().then(() => watchService.dispose()),

package/src/serve/routes/api.ts

@@ -160,6 +160,7 @@ import {
   withRetrievalTraceHeader,
 } from "../retrieval-trace";
 import { buildAppStatus, type StatusBuildDeps } from "../status";
+import { handleChanges, handleDiff, handleImpact } from "./changes";
 
 /** Mutable context holder for hot-reloading presets */
 export interface ContextHolder {
@@ -5122,6 +5123,18 @@ export async function routeApi(
     );
   }
 
+  if (path === "/api/changes" && req.method === "GET") {
+    return handleChanges(store, url);
+  }
+
+  if (path === "/api/diff" && req.method === "GET") {
+    return handleDiff(store, url);
+  }
+
+  if (path === "/api/impact" && req.method === "GET") {
+    return handleImpact(store, url);
+  }
+
   // Unknown API route
   if (path.startsWith("/api/")) {
     return errorResponse("NOT_FOUND", `Unknown API endpoint: ${path}`, 404);

package/src/serve/routes/changes.ts

@@ -0,0 +1,102 @@
+/** Read-only REST handlers for knowledge change, diff, and impact services. */
+
+import type { KnowledgeImpactInput } from "../../core/knowledge-delta";
+import type { StorePort } from "../../store/types";
+
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+} from "../../core/knowledge-delta";
+
+const errorResponse = (
+  code: "VALIDATION" | "RUNTIME",
+  message: string
+): Response =>
+  Response.json(
+    { error: { code, message } },
+    { status: code === "VALIDATION" ? 400 : 500 }
+  );
+
+const parsePositiveInt = (
+  url: URL,
+  name: string
+): number | undefined | Response => {
+  const raw = url.searchParams.get(name);
+  if (raw === null) return;
+  if (!/^\d+$/.test(raw)) {
+    return errorResponse("VALIDATION", `${name} must be a positive integer`);
+  }
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value > 0
+    ? value
+    : errorResponse("VALIDATION", `${name} must be a positive integer`);
+};
+
+export async function handleChanges(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const limit = parsePositiveInt(url, "limit");
+  if (limit instanceof Response) return limit;
+  const result = await listKnowledgeChanges(store, {
+    since: url.searchParams.get("since") ?? undefined,
+    collection: url.searchParams.get("collection") ?? undefined,
+    limit,
+  });
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}
+
+export async function handleDiff(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const ref = url.searchParams.get("ref")?.trim();
+  if (!ref) return errorResponse("VALIDATION", "ref is required");
+  const result = await getKnowledgeDiff(
+    store,
+    ref,
+    url.searchParams.get("change") ?? undefined
+  );
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}
+
+export async function handleImpact(
+  store: StorePort,
+  url: URL
+): Promise<Response> {
+  const ref = url.searchParams.get("ref")?.trim();
+  if (!ref) return errorResponse("VALIDATION", "ref is required");
+  const input: KnowledgeImpactInput = {};
+  for (const [queryName, inputName] of [
+    ["maxDepth", "maxDepth"],
+    ["maxNodes", "maxNodes"],
+    ["maxEdges", "maxEdges"],
+    ["frontierLimit", "frontierLimit"],
+    ["visitedLimit", "visitedLimit"],
+  ] as const) {
+    const value = parsePositiveInt(url, queryName);
+    if (value instanceof Response) return value;
+    if (value !== undefined) input[inputName] = value;
+  }
+  const result = await analyzeKnowledgeImpact(store, ref, input);
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  return Response.json(result.data);
+}

package/src/serve/server.ts

@@ -69,6 +69,7 @@ import {
   handleUpdateDoc,
   handleVerifyConnector,
 } from "./routes/api";
+import { handleChanges, handleDiff, handleImpact } from "./routes/changes";
 import { handleGraph, handleGraphQuery } from "./routes/graph";
 import {
   handleDocBacklinks,
@@ -968,6 +969,39 @@ export async function startServer(
             );
           },
         },
+        "/api/changes": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleChanges(store, url)
+              ),
+              isDev
+            );
+          },
+        },
+        "/api/diff": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleDiff(store, url)
+              ),
+              isDev
+            );
+          },
+        },
+        "/api/impact": {
+          GET: async (req: Request) => {
+            const url = new URL(req.url);
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleImpact(store, url)
+              ),
+              isDev
+            );
+          },
+        },
       },
     });
   } catch (e) {

package/src/serve/watch-service.ts

@@ -31,6 +31,8 @@ export interface CollectionWatchCallbacks {
     relPaths: string[];
     error: unknown;
   }) => void;
+  /** Fires after all watcher syncs and queued paths have settled. */
+  onSettled?: () => void;
 }
 
 interface CollectionWatchServiceOptions {
@@ -236,6 +238,13 @@ export class CollectionWatchService {
       const remaining = this.#pendingByCollection.get(collectionName);
       if (remaining && remaining.size > 0) {
         void this.#flushCollection(collectionName);
+      } else if (
+        this.#syncing.size === 0 &&
+        ![...this.#pendingByCollection.values()].some(
+          (relPaths) => relPaths.size > 0
+        )
+      ) {
+        this.#callbacks?.onSettled?.();
       }
     }
   }

package/src/store/index.ts

@@ -33,6 +33,16 @@ export type {
   CollectionRow,
   CollectionStatus,
   ContextRow,
+  DocumentChangeDateDelta,
+  DocumentChangeKind,
+  DocumentChangeListOptions,
+  DocumentChangePage,
+  DocumentChangePurgeResult,
+  DocumentChangeRetentionPolicy,
+  DocumentChangeRetentionResult,
+  DocumentChangeRow,
+  DocumentChangeSet,
+  DocumentChangeStructureDelta,
   DocumentInput,
   DocumentRow,
   FtsResult,
@@ -72,6 +82,17 @@ export type {
   RetrievalTraceRunRow,
   RetrievalTraceStatus,
   RetrievalTraceTerminalStatus,
+  RenameDocumentOptions,
+  SavedCapsuleAffectedQuestionState,
+  SavedCapsuleEvidenceReference,
+  SavedCapsuleNotificationPreference,
+  SavedCapsuleOperationStatus,
+  SavedCapsuleRegistration,
+  SavedCapsuleRegistrationInput,
+  SavedCapsuleRegistrationRecord,
+  SavedCapsuleReverificationState,
+  SavedCapsuleTriggerKind,
+  SavedCapsuleVerificationRecord,
   StoreError,
   StoreErrorCode,
   StorePort,

package/src/store/migrations/015-document-change-journal.ts

@@ -0,0 +1,85 @@
+/**
+ * Migration: bounded, metadata-only document change journal.
+ *
+ * The journal intentionally stores document identity, hashes, active state,
+ * and compact structural summaries. Source and converted document bodies are
+ * never copied into this table.
+ *
+ * @module src/store/migrations/015-document-change-journal
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 15,
+  name: "document_change_journal",
+
+  up(db: Database): void {
+    db.exec(`
+      CREATE TABLE document_changes (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        document_id INTEGER NOT NULL CHECK (document_id > 0),
+        collection TEXT NOT NULL,
+        change_kind TEXT NOT NULL
+          CHECK (change_kind IN ('create', 'update', 'rename', 'inactivate', 'reactivate')),
+        old_rel_path TEXT,
+        new_rel_path TEXT,
+        old_docid TEXT,
+        new_docid TEXT,
+        old_uri TEXT,
+        new_uri TEXT,
+        old_source_hash TEXT,
+        new_source_hash TEXT,
+        old_mirror_hash TEXT,
+        new_mirror_hash TEXT,
+        old_active INTEGER CHECK (old_active IS NULL OR old_active IN (0, 1)),
+        new_active INTEGER CHECK (new_active IS NULL OR new_active IN (0, 1)),
+        heading_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+        link_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+        typed_edge_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+        date_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[],"changed":[]}',
+        structure_truncated INTEGER NOT NULL DEFAULT 0
+          CHECK (structure_truncated IN (0, 1)),
+        observed_at_ms INTEGER NOT NULL CHECK (observed_at_ms >= 0),
+        byte_size INTEGER NOT NULL CHECK (byte_size > 0 AND byte_size <= 131072),
+        CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (old_rel_path IS NULL OR length(CAST(old_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+        CHECK (new_rel_path IS NULL OR length(CAST(new_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+        CHECK (old_docid IS NULL OR length(CAST(old_docid AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (new_docid IS NULL OR length(CAST(new_docid AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (old_uri IS NULL OR length(CAST(old_uri AS BLOB)) BETWEEN 1 AND 8192),
+        CHECK (new_uri IS NULL OR length(CAST(new_uri AS BLOB)) BETWEEN 1 AND 8192),
+        CHECK (old_source_hash IS NULL OR length(CAST(old_source_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (new_source_hash IS NULL OR length(CAST(new_source_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (old_mirror_hash IS NULL OR length(CAST(old_mirror_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (new_mirror_hash IS NULL OR length(CAST(new_mirror_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (length(CAST(heading_delta_json AS BLOB)) <= 16384),
+        CHECK (length(CAST(link_delta_json AS BLOB)) <= 16384),
+        CHECK (length(CAST(typed_edge_delta_json AS BLOB)) <= 16384),
+        CHECK (length(CAST(date_delta_json AS BLOB)) <= 16384)
+      );
+
+      CREATE INDEX idx_document_changes_collection_sequence
+      ON document_changes(collection, sequence);
+
+      CREATE INDEX idx_document_changes_document_sequence
+      ON document_changes(document_id, sequence);
+
+      CREATE INDEX idx_document_changes_retention
+      ON document_changes(observed_at_ms, sequence);
+
+      CREATE TABLE document_change_journal_state (
+        singleton_id INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+        last_sequence INTEGER NOT NULL DEFAULT 0 CHECK (last_sequence >= 0),
+        retention_floor INTEGER NOT NULL DEFAULT 0
+          CHECK (retention_floor >= 0 AND retention_floor <= last_sequence)
+      );
+
+      INSERT INTO document_change_journal_state (
+        singleton_id, last_sequence, retention_floor
+      ) VALUES (1, 0, 0);
+    `);
+  },
+};