@cerefox/memory 1.0.5 → 1.1.0-beta.1

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

@@ -0,0 +1,59 @@
+-- 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')
+);

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,10 +292,24 @@ 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)
+        any_pass AS (SELECT bool_or(fl.passes) AS ok FROM flagged fl),
+        -- v1.0.6: in the below-confidence fallback, rank each candidate WITHIN
+        -- its parent document so we can return one chunk per document. The cap
+        -- used to apply to chunks, so when a document owned several of the top
+        -- chunks the caller saw fewer than 3 results after document-level
+        -- de-duplication (cerefox_search_docs, CLI and web) — the count varied
+        -- with corpus shape rather than with the cap.
+        ranked AS (
+            SELECT fl.*,
+                   ROW_NUMBER() OVER (
+                       PARTITION BY ch.document_id ORDER BY fl.score DESC
+                   ) AS rank_in_doc
+            FROM flagged fl
+            JOIN cerefox_chunks ch ON ch.id = fl.id
+        )
     SELECT
         c.id            AS chunk_id,
         c.document_id,
@@ -311,11 +335,13 @@ BEGIN
         -- memory layer can produce. "Truly nothing" (no candidates at all)
         -- still returns zero rows.
         NOT ap.ok       AS below_confidence
-    FROM flagged cm
+    FROM ranked cm
     CROSS JOIN any_pass ap
     JOIN cerefox_chunks   c ON c.id = cm.id
     JOIN cerefox_documents d ON c.document_id = d.id
-    WHERE cm.passes OR NOT ap.ok
+    -- Normal results are unchanged; fallback rows are restricted to each
+    -- document's best chunk so the cap below counts documents, not chunks.
+    WHERE cm.passes OR (NOT ap.ok AND cm.rank_in_doc = 1)
     ORDER BY cm.score DESC
     LIMIT (SELECT CASE WHEN ap2.ok THEN p_match_count
                        ELSE LEAST(p_match_count, 3) END
@@ -333,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,
@@ -367,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);
@@ -427,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
@@ -733,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,
@@ -1724,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.
 
@@ -1737,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
@@ -1744,7 +2032,13 @@ 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'
+    ];
 BEGIN
     IF NOT (p_key = ANY(v_allowed)) THEN
         RAISE EXCEPTION 'Unknown config key: %. Allowed keys: %', p_key, v_allowed;
@@ -1938,7 +2232,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.1'::TEXT;
+    SELECT '0.10.0'::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.1
+-- @version: 0.10.0
 -- 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.
 --

package/docs/guides/configuration.md

@@ -117,18 +117,36 @@ This handles intermittent OpenAI API errors (500s) that would otherwise cause se
 
 ## Retrieval
 
+> **Deployment-wide defaults (v1.1.0+).** `min_search_score`,
+> `min_term_coverage`, and `search_alpha` can also be set **once, in the
+> database**, and every access path obeys — CLI, local and remote MCP, Edge
+> Functions, web — because they all resolve through the same search RPCs:
+>
+> ```bash
+> cerefox config set min_search_score 0.6
+> cerefox config list          # shows every settable key
+> ```
+>
+> Resolution order, highest first: **per-call argument** (`--min-score`, the
+> `min_score` MCP parameter) → **client env var** below → **`cerefox_config`**
+> → built-in default. A malformed stored value is ignored in favour of the
+> built-in, so a bad setting can never break search.
+
 > **Which paths read these?** Client-side tunables in this section are read
 > from *your* `.env` by the **CLI**, the **local MCP server**, and `cerefox
-> web`. The **remote MCP / Edge Function path** runs on Supabase and does not
-> see your `.env` — it uses the server defaults unless the caller passes the
-> per-call parameter (e.g. `min_score`, `min_term_coverage` on
-> `cerefox_search`). Setting them as Supabase **Function secrets** may also
-> work but is not a tested configuration.
+> web`. Since **v1.0.6** the same values are also honored on the **remote MCP /
+> Edge Function path** when set as Supabase **Function secrets**
+> (`supabase secrets set CEREFOX_MIN_SEARCH_SCORE=0.55 --project-ref <ref>`) —
+> the shared helpers read `Deno.env` as well as `process.env`. Per-call
+> parameters (`min_score`, `min_term_coverage`, `alpha` on `cerefox_search`)
+> override both. A single setting that governs every path without secrets is
+> tracked as issue #133 (DB-backed config).
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CEREFOX_MAX_RESPONSE_BYTES` | `200000` | Maximum bytes in a single search response (local MCP path). See explanation below. |
 | `CEREFOX_MIN_SEARCH_SCORE` | `0.50` (`0.60` with the local embedder) | Minimum cosine similarity for hybrid and semantic search results (0.0–1.0). The default is embedder-aware: nomic scores unrelated text higher than OpenAI, so `CEREFOX_EMBEDDER=local` raises the floor to 0.60. In **hybrid search**, chunks that matched the FTS keyword operator (`@@`) always pass through regardless of their vector score — the threshold only filters vector-only results. In **semantic search**, all results are filtered. The pure **FTS search** mode is unaffected. Increase for stricter precision; decrease for wider recall. |
+| `CEREFOX_SEARCH_ALPHA` | `0.7` | Hybrid fusion weight (0.0–1.0): `1.0` = pure semantic, `0.0` = pure keyword. Applies to hybrid and document-mode search. Per-call override: `cerefox search --alpha`, or the `alpha` parameter on the `cerefox_search` MCP tool. |
 | `CEREFOX_MIN_TERM_COVERAGE` | *(unset — server default `0.5`)* | Confidence bar for the keyword OR-fallback (v1.0.4, schema ≥ 0.9.1): when a strict all-terms match fails and search relaxes to any-term matching, a result counts as a confident hit only if it matches at least this fraction of the query's meaningful terms; weaker matches surface as below-confidence candidates. `0` restores pre-gate behavior (any matching term passes); `1` requires every term. Per-call override: `cerefox search --min-term-coverage`. Leave unset against pre-0.9.1 servers. |
 | `CEREFOX_EMBED_MAX_INPUT_CHARS` | `20000` | Safety cap on the characters sent to the embedding model per input. The full chunk content is always stored and reconstructed untouched; only the embedding uses the (rare) truncated prefix, so an oversized chunk can never fail an ingest. |
 | `CEREFOX_MODELS_DIR` | `~/.cerefox/models` (in-container: inside the data volume) | Where the local embedder caches downloaded model weights (Cerefox Local; `CEREFOX_EMBEDDER=local`). |

package/docs/guides/setup-local.md

@@ -143,7 +143,9 @@ cerefox-local start          # start a stopped container
 cerefox-local stop           # stop it (your data persists in the Docker volume)
 cerefox-local restart
 cerefox-local logs -f        # follow the logs
-cerefox-local upgrade        # pull the latest image + recreate (keeps data + OPENAI key)
+cerefox-local upgrade        # upgrade to the newest release + recreate (keeps data + OPENAI key)
+cerefox-local upgrade v1.2.3 # pin an exact version (also how you downgrade)
+cerefox-local upgrade --latest  # follow the moving :latest tag from now on
 cerefox-local uninstall          # remove the container, KEEP the data volume
 cerefox-local uninstall --purge  # remove the container AND delete the data volume
 ```

package/docs/guides/upgrading.md

@@ -10,7 +10,7 @@ to re-run.
 |---|---|
 | **Installer / npm** (end user, no repo clone) | `cerefox self-update` (or re-run the [installer](quickstart.md#1-install), or `bun/npm update -g @cerefox/memory`). Then `cerefox server deploy` **if the release notes flag a server-side change**. `cerefox doctor` verifies. |
 | **Source checkout** (`git clone`, contributor) | `git pull`, then `cerefox server deploy` (or the lower-level `bun scripts/db_*.ts` + `npx supabase functions deploy`). Rebuild the SPA if you run `cerefox web` from source. |
-| **Local / self-hosted (Docker, World B)** | `cerefox-local upgrade` — pulls the new image and recreates the container (data persists in the volume; OpenAI key + tuning overrides preserved). **No separate `server deploy`/`reindex`**: the CLI, web, PostgREST, and schema all ship together in one versioned image, so they can't drift. See [`setup-local.md`](setup-local.md). |
+| **Local / self-hosted (Docker, World B)** | `cerefox-local upgrade` — resolves the newest release, pulls it, and recreates the container (`upgrade <tag>` pins an exact version; `upgrade --latest` follows the moving tag). Data persists in the volume; OpenAI key + tuning overrides preserved. **No separate `server deploy`/`reindex`**: the CLI, web, PostgREST, and schema all ship together in one versioned image, so they can't drift. See [`setup-local.md`](setup-local.md). |
 
 > **On an old pre-installer clone (0.1.x)?** The cleanest upgrade is to stop
 > running from the repo and install the package: follow the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.0.5",
+  "version": "1.1.0-beta.1",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",
@@ -43,7 +43,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@supabase/supabase-js": "^2.45.0",
     "cli-progress": "^3.12.0",
-    "commander": "^12.1.0",
+    "commander": "^14.0.3",
     "hono": "^4.12.34",
     "mammoth": "^1.9.0",
     "ora": "^9.4.0",
@@ -54,7 +54,7 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "^3.5.0",
+    "@huggingface/transformers": "^4.2.0",
     "onnxruntime-node": "^1.21.0"
   },
   "devDependencies": {