@cerefox/memory 1.0.8 → 1.1.0-beta.2

package/dist/server-assets/db/migrations/0014_document_relations.sql

@@ -0,0 +1,64 @@
+-- 0014_document_relations.sql — typed edges between documents (iteration 29).
+--
+-- Adds the relation graph on top of the existing document model:
+--   * cerefox_document_relations — typed, directed edges (source → target)
+--   * cerefox_documents.lifecycle_status — 'active' | 'superseded' | 'stale' | 'archived'
+--
+-- Design: docs/research/document-relations-and-semantic-graph.md §2.2, §3.
+-- Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS cerefox_document_relations (
+    id           UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_id    UUID        NOT NULL REFERENCES cerefox_documents(id) ON DELETE CASCADE,
+    target_id    UUID        NOT NULL REFERENCES cerefox_documents(id) ON DELETE CASCADE,
+    -- Free-text by design: agents define new types without a migration. The
+    -- type dictionary (in the RPCs) gives known types behaviour; unknown types
+    -- are stored and returned, just without special handling.
+    rel_type     TEXT        NOT NULL,
+    metadata     JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    author       TEXT        NOT NULL DEFAULT 'unknown',
+    author_type  TEXT        NOT NULL DEFAULT 'agent',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    -- One edge of a given type per ordered pair; different types may coexist.
+    UNIQUE (source_id, target_id, rel_type),
+    -- A document relating to itself is always a mistake, and self-edges would
+    -- make traversal loop.
+    CONSTRAINT cerefox_relations_no_self_edge CHECK (source_id <> target_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_source ON cerefox_document_relations(source_id);
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_target ON cerefox_document_relations(target_id);
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_type   ON cerefox_document_relations(rel_type);
+
+-- Lifecycle status: how a document stands relative to the rest of the graph.
+-- Distinct from review_status (editorial state) and deleted_at (existence).
+ALTER TABLE cerefox_documents
+    ADD COLUMN IF NOT EXISTS lifecycle_status TEXT NOT NULL DEFAULT 'active';
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_docs_lifecycle
+    ON cerefox_documents(lifecycle_status)
+    WHERE lifecycle_status <> 'active';
+
+-- Data-API grants for the new table (migration 0013 / #26: privileges are
+-- explicit now, and a new table gets none by default).
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
+        GRANT SELECT, INSERT, UPDATE, DELETE
+            ON TABLE public.cerefox_document_relations TO service_role;
+    END IF;
+END
+$$;
+
+-- Relation writes are auditable operations; widen the audit-log constraint.
+ALTER TABLE cerefox_audit_log DROP CONSTRAINT IF EXISTS cerefox_audit_log_operation_check;
+ALTER TABLE cerefox_audit_log ADD CONSTRAINT cerefox_audit_log_operation_check CHECK (
+    operation IN ('create', 'update-content', 'update-metadata', 'delete',
+                  'status-change', 'archive', 'unarchive', 'restore',
+                  'relation-set', 'relation-delete')
+);
+
+-- Relations ship dormant: the MCP tools stay hidden until a deployment opts in.
+INSERT INTO cerefox_config (key, value)
+VALUES ('relations_enabled', 'false')
+ON CONFLICT (key) DO NOTHING;

package/dist/server-assets/db/rpcs.sql

@@ -99,10 +99,13 @@ CREATE OR REPLACE FUNCTION cerefox_hybrid_search(
     p_query_text      TEXT,
     p_query_embedding VECTOR(768),
     p_match_count     INT     DEFAULT 10,
-    p_alpha           FLOAT   DEFAULT 0.7,
+    p_alpha           FLOAT   DEFAULT NULL,
     p_use_upgrade     BOOLEAN DEFAULT FALSE,
     p_project_id      UUID    DEFAULT NULL,
-    p_min_score       FLOAT   DEFAULT 0.0,
+    -- NULL means "not specified by the caller" (#133): resolve from
+    -- cerefox_config, else the built-in default. Callers that pass a value
+    -- still win — the chain is per-call > client .env > DB config > default.
+    p_min_score       FLOAT   DEFAULT NULL,
     p_metadata_filter JSONB   DEFAULT NULL,
     -- 28I follow-up (v1.0.4): in OR-fallback mode, the unconditional FTS pass
     -- requires at least this fraction of the query's meaningful (non-stopword,
@@ -110,7 +113,7 @@ CREATE OR REPLACE FUNCTION cerefox_hybrid_search(
     -- meant 100% of terms — the pass this gate generalizes. Chunks below the
     -- bar can still pass via the vector threshold, else they are
     -- below-confidence material. 0 restores the pre-gate OR behavior.
-    p_min_term_coverage FLOAT DEFAULT 0.5
+    p_min_term_coverage FLOAT DEFAULT NULL
 )
 RETURNS TABLE (
     chunk_id        UUID,
@@ -164,6 +167,13 @@ DECLARE
     seen_tokens   TEXT[]    := '{}';
     total_tokens  INT;
     candidate_count INT := p_match_count * 5;
+    -- #133 resolution: caller value, else deployment config, else built-in.
+    v_min_score     FLOAT := COALESCE(p_min_score,
+                                      cerefox_config_float('min_search_score', 0.5));
+    v_alpha         FLOAT := COALESCE(p_alpha,
+                                      cerefox_config_float('search_alpha', 0.7));
+    v_min_coverage  FLOAT := COALESCE(p_min_term_coverage,
+                                      cerefox_config_float('min_term_coverage', 0.5));
 BEGIN
     -- Build the OR-composed query: plainto each whitespace token (so tokens get
     -- the same normalization/stemming as the AND path), skip stopword-only
@@ -217,7 +227,7 @@ BEGIN
                     WHEN and_matches OR total_tokens = 0 THEN TRUE
                     ELSE (SELECT COUNT(*) FROM unnest(tok_queries) tq
                           WHERE c.fts @@ tq)::FLOAT
-                         >= p_min_term_coverage * total_tokens
+                         >= v_min_coverage * total_tokens
                 END AS coverage_ok
             FROM cerefox_chunks c
             JOIN cerefox_documents d ON c.document_id = d.id
@@ -261,8 +271,8 @@ BEGIN
         combined AS (
             SELECT
                 COALESCE(f.id, v.id) AS id,
-                (   p_alpha * COALESCE(v.vec_score, 0.0) +
-                    (1.0 - p_alpha) * COALESCE(f.fts_score, 0.0)
+                (   v_alpha * COALESCE(v.vec_score, 0.0) +
+                    (1.0 - v_alpha) * COALESCE(f.fts_score, 0.0)
                 ) AS score,
                 COALESCE(v.vec_score, 0.0) AS vec_score,
                 -- TRUE when the chunk matched the @@ FTS operator WITH enough
@@ -282,7 +292,7 @@ BEGIN
         -- results (no FTS match) are filtered by the cosine threshold.
         flagged AS (
             SELECT *,
-                   (combined.has_fts_match OR combined.vec_score >= p_min_score) AS passes
+                   (combined.has_fts_match OR combined.vec_score >= v_min_score) AS passes
             FROM combined
         ),
         any_pass AS (SELECT bool_or(fl.passes) AS ok FROM flagged fl),
@@ -349,7 +359,7 @@ CREATE OR REPLACE FUNCTION cerefox_fts_search(
     p_metadata_filter JSONB DEFAULT NULL,
     -- v1.0.4: see cerefox_hybrid_search. In OR-fallback mode results must
     -- match at least this fraction of the query's meaningful terms.
-    p_min_term_coverage FLOAT DEFAULT 0.5
+    p_min_term_coverage FLOAT DEFAULT NULL
 )
 RETURNS TABLE (
     chunk_id        UUID,
@@ -383,6 +393,8 @@ DECLARE
     tok_queries   tsquery[] := '{}';
     seen_tokens   TEXT[]    := '{}';
     total_tokens  INT;
+    v_min_coverage FLOAT := COALESCE(p_min_term_coverage,
+                                     cerefox_config_float('min_term_coverage', 0.5));
 BEGIN
     FOR tok IN SELECT unnest(regexp_split_to_array(trim(p_query_text), '\s+')) LOOP
         tok_q := plainto_tsquery('english', tok);
@@ -443,7 +455,7 @@ BEGIN
       -- returns only chunks matching enough of the query's terms.
       AND (and_matches OR total_tokens = 0
            OR (SELECT COUNT(*) FROM unnest(tok_queries) tq
-               WHERE c.fts @@ tq)::FLOAT >= p_min_term_coverage * total_tokens)
+               WHERE c.fts @@ tq)::FLOAT >= v_min_coverage * total_tokens)
       AND (p_project_id IS NULL OR EXISTS (
               SELECT 1 FROM cerefox_document_projects dp
               WHERE dp.document_id = d.id AND dp.project_id = p_project_id
@@ -749,13 +761,15 @@ CREATE OR REPLACE FUNCTION cerefox_search_docs(
     p_query_text             TEXT,
     p_query_embedding        VECTOR(768),
     p_match_count            INT   DEFAULT 5,
-    p_alpha                  FLOAT DEFAULT 0.7,
+    p_alpha                  FLOAT DEFAULT NULL,
     p_project_id             UUID  DEFAULT NULL,
-    p_min_score              FLOAT DEFAULT 0.0,
+    p_min_score              FLOAT DEFAULT NULL,
     p_small_to_big_threshold INT   DEFAULT 20000,
     p_context_window         INT   DEFAULT 1,
     p_metadata_filter        JSONB DEFAULT NULL,
-    p_min_term_coverage      FLOAT DEFAULT 0.5
+    -- NULL flows through to cerefox_hybrid_search, which resolves the
+    -- caller > cerefox_config > built-in chain in one place (#133).
+    p_min_term_coverage      FLOAT DEFAULT NULL
 )
 RETURNS TABLE (
     document_id              UUID,
@@ -1740,6 +1754,239 @@ BEGIN
 END;
 $$;
 
+-- ══ Document relations (iteration 29) ═════════════════════════════════════════
+-- Typed edges between documents. Design:
+-- docs/research/document-relations-and-semantic-graph.md
+--
+-- Type dictionary: rel_type is free text (any string is accepted and returned),
+-- but a few KNOWN types carry behaviour. Keeping the dictionary in one place
+-- here — rather than scattered CASE expressions — is what lets the set/delete
+-- RPCs stay symmetric with each other.
+--   symmetric   both directions are written/removed together
+--   supersedes  target becomes 'superseded'
+--   contradicts both documents become 'stale'
+CREATE OR REPLACE FUNCTION cerefox_relation_is_symmetric(p_rel_type TEXT)
+RETURNS BOOLEAN
+LANGUAGE sql
+IMMUTABLE
+SET search_path = public, pg_catalog
+AS $$
+    SELECT p_rel_type IN ('related_to', 'contradicts', 'duplicates');
+$$;
+
+-- Create (or update) a relation. Symmetric types write both directions in one
+-- transaction, so a half-written pair is impossible.
+CREATE OR REPLACE FUNCTION cerefox_set_relation(
+    p_source_id   UUID,
+    p_target_id   UUID,
+    p_rel_type    TEXT,
+    p_author      TEXT    DEFAULT 'unknown',
+    p_author_type TEXT    DEFAULT 'agent',
+    p_metadata    JSONB   DEFAULT '{}'::jsonb
+)
+RETURNS TABLE (
+    relation_id UUID,
+    source_id   UUID,
+    target_id   UUID,
+    rel_type      TEXT,
+    is_symmetric  BOOLEAN
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+-- The OUT columns (source_id, target_id, rel_type) share names with the
+-- table's columns; inside the INSERT/ON CONFLICT below the COLUMN is meant.
+#variable_conflict use_column
+DECLARE
+    v_symmetric BOOLEAN := cerefox_relation_is_symmetric(p_rel_type);
+    v_id        UUID;
+BEGIN
+    IF p_source_id = p_target_id THEN
+        RAISE EXCEPTION 'A document cannot relate to itself (%).', p_source_id
+            USING ERRCODE = '22023';
+    END IF;
+    IF p_rel_type IS NULL OR btrim(p_rel_type) = '' THEN
+        RAISE EXCEPTION 'rel_type is required.' USING ERRCODE = '22023';
+    END IF;
+    -- Explicit existence checks give a clear error instead of an FK violation.
+    IF NOT EXISTS (SELECT 1 FROM cerefox_documents d
+                   WHERE d.id = p_source_id AND d.deleted_at IS NULL) THEN
+        RAISE EXCEPTION 'Source document % not found (or deleted).', p_source_id
+            USING ERRCODE = '22023';
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM cerefox_documents d
+                   WHERE d.id = p_target_id AND d.deleted_at IS NULL) THEN
+        RAISE EXCEPTION 'Target document % not found (or deleted).', p_target_id
+            USING ERRCODE = '22023';
+    END IF;
+
+    INSERT INTO cerefox_document_relations AS r
+        (source_id, target_id, rel_type, metadata, author, author_type)
+    VALUES (p_source_id, p_target_id, btrim(p_rel_type), COALESCE(p_metadata, '{}'::jsonb),
+            p_author, p_author_type)
+    ON CONFLICT (source_id, target_id, rel_type) DO UPDATE
+        SET metadata = EXCLUDED.metadata,
+            author = EXCLUDED.author,
+            author_type = EXCLUDED.author_type
+    RETURNING r.id INTO v_id;
+
+    IF v_symmetric THEN
+        INSERT INTO cerefox_document_relations
+            (source_id, target_id, rel_type, metadata, author, author_type)
+        VALUES (p_target_id, p_source_id, btrim(p_rel_type),
+                COALESCE(p_metadata, '{}'::jsonb), p_author, p_author_type)
+        ON CONFLICT (source_id, target_id, rel_type) DO UPDATE
+            SET metadata = EXCLUDED.metadata,
+                author = EXCLUDED.author,
+                author_type = EXCLUDED.author_type;
+    END IF;
+
+    -- Lifecycle side effects (type dictionary).
+    IF btrim(p_rel_type) = 'supersedes' THEN
+        UPDATE cerefox_documents SET lifecycle_status = 'superseded'
+        WHERE id = p_target_id;
+    ELSIF btrim(p_rel_type) = 'contradicts' THEN
+        UPDATE cerefox_documents SET lifecycle_status = 'stale'
+        WHERE id IN (p_source_id, p_target_id);
+    END IF;
+
+    INSERT INTO cerefox_audit_log (document_id, operation, author, author_type, description)
+    VALUES (p_source_id, 'relation-set', p_author, p_author_type,
+            format('%s → %s (%s)', p_source_id, p_target_id, btrim(p_rel_type)));
+
+    RETURN QUERY SELECT v_id, p_source_id, p_target_id, btrim(p_rel_type), v_symmetric;
+END;
+$$;
+
+-- Remove a relation. Symmetric types remove both directions. Lifecycle side
+-- effects are NOT auto-reverted: a document marked superseded may have been
+-- superseded by something else too, and guessing wrong is worse than leaving
+-- the operator to set it explicitly.
+CREATE OR REPLACE FUNCTION cerefox_delete_relation(
+    p_source_id   UUID,
+    p_target_id   UUID,
+    p_rel_type    TEXT,
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'agent'
+)
+RETURNS INT
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_deleted INT := 0;
+    v_n       INT;
+BEGIN
+    DELETE FROM cerefox_document_relations
+    WHERE source_id = p_source_id AND target_id = p_target_id
+      AND rel_type = btrim(p_rel_type);
+    GET DIAGNOSTICS v_n = ROW_COUNT; v_deleted := v_deleted + v_n;
+
+    IF cerefox_relation_is_symmetric(p_rel_type) THEN
+        DELETE FROM cerefox_document_relations
+        WHERE source_id = p_target_id AND target_id = p_source_id
+          AND rel_type = btrim(p_rel_type);
+        GET DIAGNOSTICS v_n = ROW_COUNT; v_deleted := v_deleted + v_n;
+    END IF;
+
+    IF v_deleted > 0 THEN
+        INSERT INTO cerefox_audit_log (document_id, operation, author, author_type, description)
+        VALUES (p_source_id, 'relation-delete', p_author, p_author_type,
+                format('%s → %s (%s)', p_source_id, p_target_id, btrim(p_rel_type)));
+    END IF;
+    RETURN v_deleted;
+END;
+$$;
+
+-- All edges touching a document, in both directions. `direction` tells the
+-- caller which way each edge points relative to the document asked about.
+CREATE OR REPLACE FUNCTION cerefox_get_relations(p_document_id UUID)
+RETURNS TABLE (
+    relation_id      UUID,
+    direction        TEXT,
+    rel_type         TEXT,
+    other_id         UUID,
+    other_title      TEXT,
+    other_lifecycle  TEXT,
+    metadata         JSONB,
+    author           TEXT,
+    created_at       TIMESTAMPTZ
+)
+LANGUAGE sql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_catalog
+AS $$
+    SELECT r.id, 'outbound'::TEXT, r.rel_type, r.target_id, d.title,
+           d.lifecycle_status, r.metadata, r.author, r.created_at
+    FROM cerefox_document_relations r
+    JOIN cerefox_documents d ON d.id = r.target_id
+    WHERE r.source_id = p_document_id AND d.deleted_at IS NULL
+    UNION ALL
+    SELECT r.id, 'inbound'::TEXT, r.rel_type, r.source_id, d.title,
+           d.lifecycle_status, r.metadata, r.author, r.created_at
+    FROM cerefox_document_relations r
+    JOIN cerefox_documents d ON d.id = r.source_id
+    WHERE r.target_id = p_document_id AND d.deleted_at IS NULL
+    ORDER BY 3, 9 DESC;
+$$;
+
+-- Walk the graph from a document along ONE relation type. Depth > 1 follows
+-- chains (meaningful for e.g. `follows` / `reply_to`); a visited-set stops
+-- cycles, which free-text types make possible.
+CREATE OR REPLACE FUNCTION cerefox_get_neighbors(
+    p_document_id UUID,
+    p_rel_type    TEXT,
+    p_depth       INT DEFAULT 1,
+    p_from_time   TIMESTAMPTZ DEFAULT NULL,
+    p_to_time     TIMESTAMPTZ DEFAULT NULL,
+    p_limit       INT DEFAULT 50
+)
+RETURNS TABLE (
+    document_id     UUID,
+    title           TEXT,
+    lifecycle_status TEXT,
+    depth           INT,
+    direction       TEXT,
+    doc_created_at  TIMESTAMPTZ
+)
+LANGUAGE sql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_catalog
+AS $$
+    WITH RECURSIVE walk AS (
+        SELECT p_document_id AS id, 0 AS depth, 'self'::TEXT AS direction,
+               ARRAY[p_document_id] AS seen
+        UNION ALL
+        SELECT nxt.id, w.depth + 1, nxt.direction, w.seen || nxt.id
+        FROM walk w
+        CROSS JOIN LATERAL (
+            SELECT r.target_id AS id, 'outbound'::TEXT AS direction
+            FROM cerefox_document_relations r
+            WHERE r.source_id = w.id AND r.rel_type = btrim(p_rel_type)
+            UNION ALL
+            SELECT r.source_id, 'inbound'::TEXT
+            FROM cerefox_document_relations r
+            WHERE r.target_id = w.id AND r.rel_type = btrim(p_rel_type)
+        ) nxt
+        WHERE w.depth < GREATEST(p_depth, 1)
+          AND NOT (nxt.id = ANY(w.seen))   -- cycle guard
+    )
+    SELECT DISTINCT ON (w.id)
+           w.id, d.title, d.lifecycle_status, w.depth, w.direction, d.created_at
+    FROM walk w
+    JOIN cerefox_documents d ON d.id = w.id
+    WHERE w.depth > 0
+      AND d.deleted_at IS NULL
+      AND (p_from_time IS NULL OR d.created_at >= p_from_time)
+      AND (p_to_time   IS NULL OR d.created_at <= p_to_time)
+    ORDER BY w.id, w.depth
+    LIMIT GREATEST(p_limit, 1);
+$$;
+
 -- ── cerefox_get_config / cerefox_set_config ──────────────────────────────────
 -- Read/write key-value config from cerefox_config table.
 
@@ -1753,6 +2000,31 @@ AS $$
     SELECT value FROM cerefox_config WHERE key = p_key;
 $$;
 
+-- Numeric config reader with a fallback (v1.1.0, #133). Returns p_fallback
+-- when the key is unset or unparseable, so a malformed row can never break
+-- search — it just reverts to the built-in default.
+CREATE OR REPLACE FUNCTION cerefox_config_float(p_key TEXT, p_fallback FLOAT)
+RETURNS FLOAT
+LANGUAGE plpgsql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_raw TEXT;
+    v_num FLOAT;
+BEGIN
+    SELECT value INTO v_raw FROM cerefox_config WHERE key = p_key;
+    IF v_raw IS NULL OR v_raw = '' THEN RETURN p_fallback; END IF;
+    BEGIN
+        v_num := v_raw::FLOAT;
+    EXCEPTION WHEN others THEN
+        RETURN p_fallback;
+    END;
+    RETURN v_num;
+END;
+$$;
+
 CREATE OR REPLACE FUNCTION cerefox_set_config(p_key TEXT, p_value TEXT)
 RETURNS VOID
 LANGUAGE plpgsql
@@ -1760,7 +2032,15 @@ SECURITY DEFINER
 SET search_path = public, pg_catalog
 AS $$
 DECLARE
-    v_allowed TEXT[] := ARRAY['usage_tracking_enabled', 'require_requestor_identity', 'requestor_identity_format'];
+    -- Retrieval tunables (#133) join the governance keys: setting one here
+    -- governs EVERY access path (CLI, local + remote MCP, Edge Functions, web),
+    -- because they all resolve through these RPCs.
+    v_allowed TEXT[] := ARRAY[
+        'usage_tracking_enabled', 'require_requestor_identity', 'requestor_identity_format',
+        'min_search_score', 'min_term_coverage', 'search_alpha',
+        -- Optional features, off by default (iteration 29).
+        'relations_enabled'
+    ];
 BEGIN
     IF NOT (p_key = ANY(v_allowed)) THEN
         RAISE EXCEPTION 'Unknown config key: %. Allowed keys: %', p_key, v_allowed;
@@ -1954,7 +2234,7 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
-    SELECT '0.9.2'::TEXT;
+    SELECT '0.10.1'::TEXT;
 $$;
 
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.9.2
+-- @version: 0.10.1
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —
@@ -49,6 +49,11 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     -- 'pending_review' = modified by agent, not yet reviewed.
     -- Content is searchable in both states.
     review_status   TEXT        NOT NULL DEFAULT 'approved',
+    -- lifecycle_status: where this document stands relative to the graph —
+    -- 'active' | 'superseded' | 'stale' | 'archived'. Distinct from
+    -- review_status (editorial state) and deleted_at (existence). Maintained by
+    -- the relation RPCs (e.g. `supersedes` marks its target superseded).
+    lifecycle_status TEXT       NOT NULL DEFAULT 'active',
     created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     -- Soft delete: NULL = active, timestamp = deleted (recoverable).
@@ -118,7 +123,9 @@ CREATE TABLE IF NOT EXISTS cerefox_audit_log (
 
     CONSTRAINT cerefox_audit_log_operation_check CHECK (
         operation IN ('create', 'update-content', 'update-metadata', 'delete',
-                      'status-change', 'archive', 'unarchive', 'restore')
+                      'status-change', 'archive', 'unarchive', 'restore',
+                      -- iteration 29: graph edges are auditable writes too
+                      'relation-set', 'relation-delete')
     ),
     CONSTRAINT cerefox_audit_log_author_type_check CHECK (author_type IN ('user', 'agent'))
 );
@@ -132,6 +139,32 @@ CREATE TABLE IF NOT EXISTS cerefox_document_projects (
     PRIMARY KEY (document_id, project_id)
 );
 
+-- ── Document relations (iteration 29) ─────────────────────────────────────────
+-- Typed, directed edges between documents. rel_type is free text by design so
+-- agents can define new types without a migration; the type dictionary lives in
+-- the RPCs and gives KNOWN types behaviour (symmetry, lifecycle side effects).
+-- Design: docs/research/document-relations-and-semantic-graph.md §2.2.
+
+CREATE TABLE IF NOT EXISTS cerefox_document_relations (
+    id           UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_id    UUID        NOT NULL REFERENCES cerefox_documents(id) ON DELETE CASCADE,
+    target_id    UUID        NOT NULL REFERENCES cerefox_documents(id) ON DELETE CASCADE,
+    rel_type     TEXT        NOT NULL,
+    metadata     JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    author       TEXT        NOT NULL DEFAULT 'unknown',
+    author_type  TEXT        NOT NULL DEFAULT 'agent',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (source_id, target_id, rel_type),
+    CONSTRAINT cerefox_relations_no_self_edge CHECK (source_id <> target_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_source ON cerefox_document_relations(source_id);
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_target ON cerefox_document_relations(target_id);
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_type   ON cerefox_document_relations(rel_type);
+CREATE INDEX IF NOT EXISTS idx_cerefox_docs_lifecycle
+    ON cerefox_documents(lifecycle_status)
+    WHERE lifecycle_status <> 'active';
+
 -- ── Chunks ────────────────────────────────────────────────────────────────────
 -- One row per chunk of a document. Embeddings and FTS live here.
 --
@@ -335,6 +368,11 @@ ON CONFLICT (key) DO NOTHING;
 INSERT INTO cerefox_config (key, value)
 VALUES ('requestor_identity_format', '^[a-zA-Z0-9_:.\- ]+$')
 ON CONFLICT (key) DO NOTHING;
+-- Document relations ship dormant: the tools stay hidden from agents until a
+-- deployment opts in (iteration 29).
+INSERT INTO cerefox_config (key, value)
+VALUES ('relations_enabled', 'false')
+ON CONFLICT (key) DO NOTHING;
 
 
 -- ── Usage log ────────────────────────────────────────────────────────────────

package/dist/server-assets/supabase/functions/cerefox-mcp/index.ts

@@ -34,12 +34,15 @@ import {
   unauthorizedChallenge,
 } from "./oauth.ts";
 import type { AuthResult, McpAuthenticator } from "../../../_shared/mcp-auth/index.ts";
+import type { MCPSupabaseClient } from "../../../_shared/mcp-tools/types.ts";
 import { checkAccessToken, parseAccessTokens } from "../../../_shared/ef-auth/index.ts";
 import {
   ALL_TOOLS,
   McpInvalidParams,
   TOOLS_BY_NAME,
   type ToolContext,
+  assertToolEnabled,
+  listEnabledTools,
 } from "../../../_shared/mcp-tools/index.ts";
 import {
   type AggregatedVersions,
@@ -57,11 +60,16 @@ const SERVER_VERSION = "0.4.0";
 
 // ── Tool list (derived from _shared/mcp-tools/) ─────────────────────────────
 
-const TOOLS = ALL_TOOLS.map((t) => ({
-  name: t.name,
-  description: t.description,
-  inputSchema: t.inputSchema,
-}));
+// Built per request rather than at module load: the tool surface depends on
+// deployment config (optional features are hidden until enabled), and an
+// isolate can outlive a config change.
+async function buildToolList(supabase: MCPSupabaseClient) {
+  return (await listEnabledTools(supabase)).map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  }));
+}
 
 // ── Method handlers ──────────────────────────────────────────────────────────
 
@@ -77,8 +85,8 @@ function handleInitialize(id: unknown): Response {
   });
 }
 
-function handleToolsList(id: unknown): Response {
-  return jsonResponse({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+async function handleToolsList(id: unknown, supabase: MCPSupabaseClient): Promise<Response> {
+  return jsonResponse({ jsonrpc: "2.0", id, result: { tools: await buildToolList(supabase) } });
 }
 
 async function handleToolsCall(
@@ -105,6 +113,14 @@ async function handleToolsCall(
   // deno-lint-ignore no-explicit-any
   const supabase: any = makeSupabaseClient();
 
+  // Optional features: a session that listed tools before the flag changed can
+  // still name a gated tool.
+  try {
+    await assertToolEnabled(supabase, toolName);
+  } catch (err) {
+    return errorResponse(id, -32602, err instanceof Error ? err.message : String(err));
+  }
+
   try {
     const { data: requireConfig } = await supabase.rpc("cerefox_get_config", {
       p_key: "require_requestor_identity",
@@ -336,7 +352,8 @@ Deno.serve(async (req: Request): Promise<Response> => {
     case "ping":
       return jsonResponse({ jsonrpc: "2.0", id, result: {} });
     case "tools/list":
-      return handleToolsList(id);
+      // deno-lint-ignore no-explicit-any
+      return await handleToolsList(id, makeSupabaseClient() as any);
     case "tools/call":
       return await handleToolsCall(
         id,

package/docs/guides/cli.md

@@ -544,42 +544,6 @@ Detects fresh vs. existing databases: a fresh DB gets schema + RPCs + migration
 | `--all` | flag | off | Reindex every chunk regardless of embedder. |
 | `--dry-run` | flag | off | Count what would be re-embedded; do nothing. |
 
-> **Reindex refreshes embeddings only.** It rewrites `embedding_primary` on
-> existing chunk rows and never re-chunks, so it cannot change a document's
-> stored `content_format`. Use `server migrate-format` for that (#164).
-
----
-
-### `cerefox server migrate-format`
-
-**Purpose**: convert documents still stored under the legacy chunk-reconstruction
-format to the current one, by re-ingesting them through the normal pipeline
-(re-chunk → re-embed → stamp the current format). `cerefox doctor` reports how
-many documents are affected.
-
-**Synopsis**: `cerefox server migrate-format [OPTIONS]`
-
-**Options**:
-
-| Flag | Type | Default | Description |
-|---|---|---|---|
-| `--dry-run` | flag | off | Report how many documents would convert; write nothing. |
-| `-l, --limit <n>` | int | all | Convert at most N documents (re-run to continue). |
-| `--document-id <uuid>` | string | — | Convert a single document. |
-| `--author <name>` | string | `CEREFOX_AUTHOR_NAME` | Recorded in the audit log per conversion. |
-
-**This costs embedding spend** — every converted document is re-embedded — so it
-is opt-in and never runs automatically. Legacy-format documents are *not*
-broken: they reconstruct exactly as they always have, and convert on their own
-the next time they are edited. Each conversion runs under optimistic
-concurrency, so a document edited mid-run is skipped rather than overwritten,
-and documents whose content is byte-identical to another document cannot be
-converted (the ingestion pipeline's dedup check rejects them) — those are
-reported rather than failing the run.
-
-**Take a backup first** (`cerefox backup create`). The previous chunks are
-archived as a document version, but version retention defaults to 48 hours.
-
 ---
 
 ### `cerefox token generate` / `cerefox token rotate` / `cerefox token list`