@cerefox/memory 0.7.2 → 0.8.1

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -0,0 +1,193 @@
+/**
+ * `cerefox_search` — hybrid (FTS + semantic) search over the knowledge base.
+ *
+ * Three modes:
+ * - `docs` (default) — document-level hybrid via `cerefox_search_docs`.
+ * - `hybrid` — chunk-level hybrid via `cerefox_hybrid_search`.
+ * - `fts` — FTS-only via `cerefox_fts_search` (no embedding needed).
+ *
+ * Embedding is computed for `docs` and `hybrid` modes via the shared
+ * embedder. Results respect a per-call `max_bytes` budget capped at
+ * `MAX_RESPONSE_BYTES`; whole rows are dropped to fit the budget.
+ *
+ * Mirrors `supabase/functions/cerefox-mcp/tools/search.ts` byte-for-byte
+ * in response shape so v0.4.0 can keep agents on the same on-the-wire
+ * format whether they go through the remote MCP or the new local TS one.
+ */
+
+import type { MCPSupabaseClient } from "./types.ts";
+
+import { getEmbedding } from "../embeddings/index.ts";
+import { applyByteBudget, logUsage, MAX_RESPONSE_BYTES } from "./_utils.ts";
+import { lookupProjectId } from "./_projects.ts";
+import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+
+async function handler(
+  supabase: MCPSupabaseClient,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string> {
+  const query = args.query as string;
+  const project_name = args.project_name as string | undefined;
+  const match_count = (args.match_count as number | undefined) ?? 5;
+  const mode = (args.mode as string | undefined) ?? "docs";
+  const alpha = (args.alpha as number | undefined) ?? 0.7;
+  const min_score = (args.min_score as number | undefined) ?? 0.5;
+  const metadata_filter =
+    (args.metadata_filter as Record<string, string> | null | undefined) ?? null;
+  const requested_max_bytes = args.max_bytes as number | undefined;
+
+  const max_bytes = Math.min(requested_max_bytes ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES);
+
+  if (
+    metadata_filter !== null &&
+    metadata_filter !== undefined &&
+    (typeof metadata_filter !== "object" || Array.isArray(metadata_filter))
+  ) {
+    throw new McpInvalidParams("metadata_filter must be a JSON object or null");
+  }
+
+  if (!query?.trim()) throw new McpInvalidParams("query is required");
+
+  if (mode !== "fts" && !ctx.openaiApiKey) {
+    throw new Error(
+      "OpenAI API key not configured. Set OPENAI_API_KEY (Edge Function) or CEREFOX_OPENAI_API_KEY (.env, local).",
+    );
+  }
+
+  // Resolve project name to UUID if provided
+  let projectId: string | null = null;
+  if (project_name) {
+    projectId = await lookupProjectId(supabase, project_name);
+    if (!projectId) throw new Error(`Project not found: ${project_name}`);
+  }
+
+  // FTS mode doesn't need an embedding
+  let embedding: number[] | null = null;
+  if (mode !== "fts") {
+    embedding = await getEmbedding(query, ctx.openaiApiKey!);
+  }
+
+  const metaFilterParam =
+    metadata_filter && Object.keys(metadata_filter).length > 0
+      ? { p_metadata_filter: metadata_filter }
+      : {};
+
+  let rpcName: string;
+  let rpcParams: Record<string, unknown>;
+
+  if (mode === "fts") {
+    rpcName = "cerefox_fts_search";
+    rpcParams = {
+      p_query_text: query,
+      p_match_count: match_count,
+      p_project_id: projectId,
+      ...metaFilterParam,
+    };
+  } else if (mode === "hybrid") {
+    rpcName = "cerefox_hybrid_search";
+    rpcParams = {
+      p_query_text: query,
+      p_query_embedding: embedding,
+      p_match_count: match_count,
+      p_alpha: alpha,
+      p_use_upgrade: false,
+      p_project_id: projectId,
+      p_min_score: min_score,
+      ...metaFilterParam,
+    };
+  } else {
+    rpcName = "cerefox_search_docs";
+    rpcParams = {
+      p_query_text: query,
+      p_query_embedding: embedding,
+      p_match_count: match_count,
+      p_alpha: alpha,
+      p_project_id: projectId,
+      p_min_score: min_score,
+      ...metaFilterParam,
+    };
+  }
+
+  const { data, error } = await supabase.rpc(rpcName, rpcParams);
+
+  if (error) throw new Error(`RPC error: ${error.message}`);
+
+  const { accepted, truncated, usedBytes } = applyByteBudget(data ?? [], max_bytes);
+
+  logUsage(supabase, {
+    operation: "search",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor as string | undefined,
+    query_text: query,
+    project_id: projectId,
+    result_count: accepted.length,
+  });
+
+  if (accepted.length === 0) return "No results found.";
+
+  const rows = accepted as Array<{
+    document_id?: string;
+    doc_title?: string;
+    full_content?: string;
+    best_score?: number;
+    is_partial?: boolean;
+    chunk_count?: number;
+    total_chars?: number;
+  }>;
+
+  const parts: string[] = rows.map((row) => {
+    const title = row.doc_title ?? "Untitled";
+    const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
+    const score = row.best_score != null ? ` (score: ${row.best_score.toFixed(3)})` : "";
+    const partial = row.is_partial
+      ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
+      : "";
+    return `## ${title}${docId}${score}${partial}\n\n${row.full_content ?? ""}`;
+  });
+
+  let output = parts.join("\n\n---\n\n");
+  if (truncated) {
+    output +=
+      `\n\n[Results truncated at ${usedBytes} bytes. Use a more specific query or a smaller match_count to see more.]`;
+  }
+  return output;
+}
+
+export const searchTool: ToolDefinition = {
+  name: "cerefox_search",
+  description:
+    "Search the Cerefox personal knowledge base. Returns complete documents ranked by hybrid (FTS + semantic) relevance.",
+  inputSchema: {
+    type: "object",
+    required: ["query"],
+    properties: {
+      query: { type: "string", description: "Natural-language search query" },
+      match_count: {
+        type: "integer",
+        description: "Maximum number of documents to return (default: 5)",
+      },
+      project_name: {
+        type: "string",
+        description: "Filter results to a specific project by name (optional)",
+      },
+      metadata_filter: {
+        type: "object",
+        description:
+          'Optional JSONB containment filter. Only documents whose metadata contains ALL specified key-value pairs are returned. Example: {"type": "decision", "status": "active"}. Call cerefox_list_metadata_keys first to discover available keys and values. Omit to search all documents.',
+        additionalProperties: { type: "string" },
+      },
+      max_bytes: {
+        type: "integer",
+        description:
+          "Optional response size budget in bytes. Results are dropped whole until the budget is satisfied; a truncated flag is set when results are dropped. Defaults to the server maximum (200000). Pass a smaller value if your context window is limited. Values above the server maximum are silently capped.",
+      },
+      requestor: {
+        type: "string",
+        description:
+          'Name of the agent or user making this request (e.g., "Claude Code", "archiver"). Recorded in the usage log for attribution. Defaults to "mcp-agent" if not provided. May be enforced via server config.',
+      },
+    },
+  },
+  handler,
+};

package/dist/server-assets/_shared/mcp-tools/set-document-projects.ts

@@ -0,0 +1,163 @@
+/**
+ * `cerefox_set_document_projects` — destructive replace of a document's
+ * project memberships. Empty list clears all memberships. Logged as
+ * `update-metadata` in the audit log; document content is untouched.
+ *
+ * Mirrors Python `CerefoxClient.set_document_projects` +
+ * `_handle_set_document_projects`. v0.1.20 introduced this tool to give
+ * agents an explicit full-set primitive without rewriting content (issue
+ * #38, Part 4).
+ */
+
+import type { MCPSupabaseClient } from "./types.ts";
+
+import { logUsage } from "./_utils.ts";
+import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+
+async function handler(
+  supabase: MCPSupabaseClient,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string> {
+  const document_id = (args.document_id as string | undefined)?.trim();
+  const project_names_raw = args.project_names;
+  const author = (args.author as string | undefined) ?? "mcp-agent";
+
+  if (!document_id) {
+    throw new McpInvalidParams(
+      "Missing required argument: document_id (UUID from a prior cerefox_search result).",
+    );
+  }
+  if (
+    project_names_raw === undefined ||
+    project_names_raw === null ||
+    !Array.isArray(project_names_raw)
+  ) {
+    throw new McpInvalidParams(
+      "Missing or invalid argument: project_names must be a JSON array of strings " +
+        "(empty array allowed to clear all memberships).",
+    );
+  }
+  if (!project_names_raw.every((n) => typeof n === "string")) {
+    throw new McpInvalidParams("project_names must contain only strings.");
+  }
+
+  // Strip empties; preserve order; dedup case-insensitively.
+  const seenLower = new Set<string>();
+  const cleanNames: string[] = [];
+  for (const n of project_names_raw as string[]) {
+    const stripped = n.trim();
+    if (!stripped) continue;
+    const key = stripped.toLowerCase();
+    if (seenLower.has(key)) continue;
+    seenLower.add(key);
+    cleanNames.push(stripped);
+  }
+
+  // Verify the document exists and isn't soft-deleted.
+  const { data: doc } = await supabase
+    .from("cerefox_documents")
+    .select("id, title")
+    .eq("id", document_id)
+    .is("deleted_at", null)
+    .limit(1);
+  if (!doc?.length) {
+    throw new Error(`Document not found (or soft-deleted): ${document_id}`);
+  }
+
+  // Resolve each name → project_id (create if absent). Preserve order.
+  const projectIds: string[] = [];
+  for (const name of cleanNames) {
+    const { data: proj } = await supabase
+      .from("cerefox_projects")
+      .select("id")
+      .ilike("name", name)
+      .limit(1);
+    if (proj?.length) {
+      projectIds.push(proj[0].id);
+    } else {
+      const { data: newProj } = await supabase
+        .from("cerefox_projects")
+        .insert({ name })
+        .select("id");
+      if (newProj?.[0]?.id) projectIds.push(newProj[0].id);
+    }
+  }
+
+  // DELETE-then-INSERT replace (matches Python assign_document_projects).
+  await supabase.from("cerefox_document_projects").delete().eq("document_id", document_id);
+  if (projectIds.length > 0) {
+    const rows = projectIds.map((pid) => ({ document_id, project_id: pid }));
+    await supabase.from("cerefox_document_projects").insert(rows);
+  }
+
+  // Audit entry — project membership is metadata, not content.
+  try {
+    await supabase.rpc("cerefox_create_audit_entry", {
+      p_document_id: document_id,
+      p_version_id: null,
+      p_operation: "update-metadata",
+      p_author: author,
+      p_author_type: "agent",
+      p_size_before: null,
+      p_size_after: null,
+      p_description:
+        cleanNames.length > 0
+          ? `Set document projects to [${cleanNames.join(", ")}]`
+          : "Cleared all project memberships",
+    });
+  } catch (err) {
+    console.warn("set-document-projects: audit entry failed", err);
+  }
+
+  logUsage(supabase, {
+    operation: "set-document-projects",
+    accessPath: ctx.accessPath,
+    requestor: author,
+    document_id,
+    result_count: projectIds.length,
+  });
+
+  if (cleanNames.length === 0) {
+    return (
+      `Cleared all project memberships for document ${document_id}. ` +
+      "The document no longer belongs to any project."
+    );
+  }
+  return (
+    `Set project memberships for document ${document_id}:\n` +
+    `  Projects (${cleanNames.length}): ${cleanNames.join(", ")}\n` +
+    `  Project IDs: ${projectIds.join(", ")}\n` +
+    "  Note: this REPLACED the previous membership set. Any projects not " +
+    "listed above are no longer associated with this document."
+  );
+}
+
+export const setDocumentProjectsTool: ToolDefinition = {
+  name: "cerefox_set_document_projects",
+  description:
+    "Set the document's project memberships to EXACTLY the given list. Destructive replace: any existing memberships not in this list are removed. Pass an empty list to clear all project memberships. Projects are looked up by name (case-insensitive); missing projects are created. Logged as update-metadata in the audit log — content is untouched. Use cerefox_ingest with project_names if you want to set memberships AND update content in one call. Use this tool when you only need to change project membership without re-writing the document body.",
+  inputSchema: {
+    type: "object",
+    required: ["document_id", "project_names"],
+    properties: {
+      document_id: {
+        type: "string",
+        description:
+          "UUID of the document. Get this from a prior cerefox_search result (the [id: ...] tag after the title).",
+      },
+      project_names: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "Explicit list of project names. Each created if absent. Order is preserved. Empty list = remove from all projects.",
+      },
+      author: {
+        type: "string",
+        description:
+          'Agent or tool name recorded in the audit log. Defaults to "mcp-agent". May be enforced via server config.',
+      },
+    },
+  },
+  handler,
+};

package/dist/server-assets/_shared/mcp-tools/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared MCP tool-handler contract.
+ *
+ * Each `cerefox_*` tool is a `ToolDefinition` exporting:
+ * - `name` — MCP tool name (e.g. `cerefox_search`).
+ * - `description` — single-paragraph description shown to agents.
+ * - `inputSchema` — JSON Schema for the tool's `arguments` object.
+ * - `handler(supabase, args, ctx)` — async function returning the MCP
+ *   `TextContent` body as a string.
+ *
+ * The same `ToolDefinition`s are wired into both:
+ * - The remote `cerefox-mcp` Edge Function (Deno; HTTP-framed JSON-RPC).
+ * - The local `@cerefox/memory` stdio MCP server (Bun/Node; stdio-framed).
+ *
+ * Wiring code (request dispatch, framing, identity enforcement) lives in
+ * each consumer; the handlers themselves are runtime-agnostic.
+ */
+
+/** Structural type for the Supabase client surface the handlers actually
+ *  use (`.rpc()` + `.from()`). We deliberately don't `import { SupabaseClient }
+ *  from "@supabase/supabase-js"` here because Bun workspaces install a
+ *  separate copy of supabase-js into each workspace member, and TypeScript
+ *  then sees two distinct (but structurally identical) `SupabaseClient`
+ *  classes. Decoupling the shared module with a minimal structural type
+ *  side-steps the duplicate-class problem and keeps the shared modules
+ *  truly runtime-neutral. */
+// deno-lint-ignore no-explicit-any
+type AnyChain = any;
+
+export interface MCPSupabaseClient {
+  rpc<T = unknown>(fn: string, params?: Record<string, unknown>): AnyChain;
+  from(table: string): AnyChain;
+}
+
+/** Re-export an alias name so callers can use the descriptive name. */
+export type SupabaseClient = MCPSupabaseClient;
+
+/** JSON Schema fragment for tool inputs. We use a permissive `unknown` value
+ *  type rather than a strict JSON-Schema TS type to avoid forcing every tool
+ *  to maintain a type-perfect schema literal. */
+export type JsonSchema = Record<string, unknown>;
+
+/**
+ * Logical channel through which a Cerefox operation reached the backend.
+ * Recorded in `cerefox_usage_log.access_path` so the analytics dashboard
+ * can attribute load to each surface.
+ *
+ * Values:
+ *   - `remote-mcp`  — `cerefox-mcp` Edge Function (HTTP MCP transport).
+ *   - `local-mcp`   — `@cerefox/memory`'s `cerefox-mcp` stdio bin.
+ *   - `cli`         — the `cerefox` CLI bin (v0.5+). Mirrors the
+ *                     Python CLI's `access_path = "cli"`.
+ *
+ * Adding a new channel here also requires updating
+ * `cerefox_usage_log.access_path`'s domain (Postgres CHECK constraint).
+ */
+export type AccessPath = "remote-mcp" | "local-mcp" | "cli";
+
+export interface ToolContext {
+  /** OpenAI/Fireworks API key for tools that need to embed (search, ingest).
+   *  Resolved by the consumer (EF: `Deno.env.get("OPENAI_API_KEY")`;
+   *  local: `Settings.openaiApiKey`). */
+  openaiApiKey?: string;
+  /** Identifies the wire path the call came in on. Recorded in
+   *  `cerefox_usage_log.access_path`. */
+  accessPath: AccessPath;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  /** Returns the MCP `TextContent.text` body. Tools that fail throw; the
+   *  consumer's request wrapper translates thrown errors into JSON-RPC
+   *  `-32603` (internal error) responses, or `-32602` (invalid params)
+   *  when the thrown error is `McpInvalidParams`. */
+  handler: (
+    supabase: MCPSupabaseClient,
+    args: Record<string, unknown>,
+    ctx: ToolContext,
+  ) => Promise<string>;
+}
+
+/** Typed `Error` subclass for input-validation failures. Consumers translate
+ *  this into JSON-RPC `-32602` (invalid params). Plain `Error`s become
+ *  `-32603` (internal). */
+export class McpInvalidParams extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "McpInvalidParams";
+  }
+}

package/dist/server-assets/db/migrations/0003_add_document_versions.sql

@@ -0,0 +1,91 @@
+-- Migration 0003: Add document versioning support
+-- Applied by: scripts/db_migrate.py
+-- Safe to apply on a live database with existing documents and chunks.
+-- All changes are additive — no data is dropped or altered.
+--
+-- What this migration does:
+--   1. Creates cerefox_document_versions table
+--   2. Adds nullable version_id FK to cerefox_chunks
+--   3. Drops the plain UNIQUE constraint on (document_id, chunk_index)
+--   4. Adds a partial unique index on (document_id, chunk_index) WHERE version_id IS NULL
+--   5. Drops the plain HNSW and GIN indexes (replaced by partial equivalents)
+--   6. Creates partial HNSW, GIN, and version-lookup indexes
+--   7. Enables RLS on cerefox_document_versions
+
+-- ── 1. Document versions table ─────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS cerefox_document_versions (
+    id              UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id     UUID        NOT NULL REFERENCES cerefox_documents(id) ON DELETE CASCADE,
+    version_number  INT         NOT NULL,
+    source          TEXT        NOT NULL DEFAULT 'manual',
+    chunk_count     INT         NOT NULL DEFAULT 0,
+    total_chars     INT         NOT NULL DEFAULT 0,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT cerefox_document_versions_doc_num_unique UNIQUE (document_id, version_number)
+);
+
+-- ── 2. Add version_id to chunks ────────────────────────────────────────────
+-- NULL = current version (searchable, indexed)
+-- non-NULL = archived under that version (not searchable, lazily deleted)
+
+ALTER TABLE cerefox_chunks
+    ADD COLUMN IF NOT EXISTS version_id UUID
+        REFERENCES cerefox_document_versions(id) ON DELETE CASCADE;
+
+-- ── 3. Drop plain unique constraint ────────────────────────────────────────
+-- The old constraint disallows duplicate (document_id, chunk_index) across ALL
+-- chunks. With versioning, the same chunk_index can exist in both current and
+-- archived versions. The partial unique index below replaces this constraint.
+
+ALTER TABLE cerefox_chunks
+    DROP CONSTRAINT IF EXISTS cerefox_chunks_doc_idx_unique;
+
+-- ── 4. Partial unique index for current chunks ──────────────────────────────
+-- Ensures (document_id, chunk_index) is unique among current chunks (version_id IS NULL).
+-- Archived chunks are excluded and may share chunk_index values across versions.
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_cerefox_chunks_current_unique
+    ON cerefox_chunks(document_id, chunk_index)
+    WHERE version_id IS NULL;
+
+-- ── 5. Drop plain indexes (replaced by partial equivalents below) ───────────
+
+DROP INDEX IF EXISTS idx_cerefox_chunks_fts;
+DROP INDEX IF EXISTS idx_cerefox_chunks_emb_primary;
+DROP INDEX IF EXISTS idx_cerefox_chunks_emb_upgrade;
+
+-- ── 6. Partial FTS, HNSW, and version-lookup indexes ───────────────────────
+-- WHERE version_id IS NULL ensures only current chunks are indexed for search.
+-- Archived chunks are never returned in search results.
+
+-- Full-text search (current chunks only)
+CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_fts
+    ON cerefox_chunks USING GIN(fts)
+    WHERE version_id IS NULL;
+
+-- Primary vector index (current chunks only)
+CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_emb_primary
+    ON cerefox_chunks USING hnsw (embedding_primary vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64)
+    WHERE version_id IS NULL;
+
+-- Upgrade vector index (current chunks only)
+CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_emb_upgrade
+    ON cerefox_chunks USING hnsw (embedding_upgrade vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64)
+    WHERE version_id IS NULL;
+
+-- Archived chunk lookup (for version retrieval)
+CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_version
+    ON cerefox_chunks(version_id, chunk_index)
+    WHERE version_id IS NOT NULL;
+
+-- ── 7. RLS on new table ────────────────────────────────────────────────────
+
+ALTER TABLE cerefox_document_versions ENABLE ROW LEVEL SECURITY;
+
+-- ── 8. updated_at trigger on versions table ────────────────────────────────
+-- cerefox_document_versions has no updated_at column (immutable after creation),
+-- so no trigger is needed.

package/dist/server-assets/db/migrations/0004_add_audit_log_review_status_archived.sql

@@ -0,0 +1,71 @@
+-- Migration 0004: Add audit log table, review_status column, archived flag
+--
+-- Adds:
+--   1. cerefox_audit_log table (immutable, append-only)
+--   2. review_status column on cerefox_documents (approved | pending_review)
+--   3. archived boolean on cerefox_document_versions (protection from cleanup)
+--   4. Indexes for audit log queries (temporal, author, document, FTS on description)
+--   5. RLS on cerefox_audit_log
+
+-- ── 1. Audit log table ──────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS cerefox_audit_log (
+    id              UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id     UUID        REFERENCES cerefox_documents(id) ON DELETE SET NULL,
+    version_id      UUID        REFERENCES cerefox_document_versions(id) ON DELETE SET NULL,
+    operation       TEXT        NOT NULL,
+    author          TEXT        NOT NULL DEFAULT 'unknown',
+    author_type     TEXT        NOT NULL DEFAULT 'user',
+    size_before     INT,
+    size_after      INT,
+    description     TEXT        NOT NULL DEFAULT '',
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT cerefox_audit_log_operation_check CHECK (
+        operation IN ('create', 'update-content', 'update-metadata', 'delete',
+                      'status-change', 'archive', 'unarchive')
+    ),
+    CONSTRAINT cerefox_audit_log_author_type_check CHECK (author_type IN ('user', 'agent'))
+);
+
+-- ── 2. Review status on documents ───────────────────────────────────────────
+
+ALTER TABLE cerefox_documents
+    ADD COLUMN IF NOT EXISTS review_status TEXT NOT NULL DEFAULT 'approved';
+
+-- Add check constraint (idempotent: drop if exists, then add)
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM information_schema.check_constraints
+        WHERE constraint_name = 'cerefox_documents_review_status_check'
+    ) THEN
+        ALTER TABLE cerefox_documents
+            ADD CONSTRAINT cerefox_documents_review_status_check
+            CHECK (review_status IN ('approved', 'pending_review'));
+    END IF;
+END $$;
+
+-- ── 3. Archived flag on versions ────────────────────────────────────────────
+
+ALTER TABLE cerefox_document_versions
+    ADD COLUMN IF NOT EXISTS archived BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- ── 4. Indexes for audit log ────────────────────────────────────────────────
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_audit_log_created
+    ON cerefox_audit_log(created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_audit_log_document
+    ON cerefox_audit_log(document_id, created_at DESC)
+    WHERE document_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_audit_log_author
+    ON cerefox_audit_log(author, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_audit_log_desc_fts
+    ON cerefox_audit_log USING GIN(to_tsvector('english', description));
+
+-- ── 5. RLS ──────────────────────────────────────────────────────────────────
+
+ALTER TABLE cerefox_audit_log ENABLE ROW LEVEL SECURITY;