@cerefox/memory 1.7.0 → 1.8.0

package/dist/server-assets/_shared/ef-meta/index.ts

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.7.0";
+export const EF_VERSION = "1.8.0";
 
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.7.0";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.7.0";
+export const CEREFOX_VERSION = "1.8.0";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).

package/dist/server-assets/db/migrations/0025_drop_orphaned_overloads.sql

@@ -0,0 +1,16 @@
+-- 0025_drop_orphaned_overloads.sql — remove pre-author-era 1-arg overloads.
+--
+-- cerefox_purge_document(UUID) and cerefox_restore_document(UUID) survived
+-- every CREATE OR REPLACE since their signatures grew (OR REPLACE only
+-- replaces the SAME signature), leaving long-lived databases with BOTH
+-- overloads. A named 1-arg call is then ambiguous — PostgREST PGRST203
+-- ("could not choose the best candidate") — which is how the first
+-- acceptance run against a long-lived database failed to purge its
+-- fixtures (v1.7.0).
+-- Fresh databases never had the old signatures and are unaffected.
+--
+-- Schema version 0.12.0 → 0.12.1. The DROPs also run from rpcs.sql on every
+-- deploy; this migration makes the version advance signal the redeploy.
+
+DROP FUNCTION IF EXISTS cerefox_purge_document(UUID);
+DROP FUNCTION IF EXISTS cerefox_restore_document(UUID);

package/dist/server-assets/db/migrations/0026_metadata_guard_and_dead_links.sql

@@ -0,0 +1,46 @@
+-- 0026_metadata_guard_and_dead_links.sql — #212 metadata type guards +
+-- #214 phase-2 dead-link sweep.
+--
+-- RPC changes ship via rpcs.sql on this deploy: cerefox_ingest_document
+-- rejects non-object p_metadata (the MCP layer always did; now every write
+-- path agrees), cerefox_set_document_metadata refuses to MERGE onto a
+-- non-object stored value (|| would produce an array; only replace=true
+-- repairs), and two read-only RPCs arrive: cerefox_find_dead_links (whole-KB
+-- [Text](uuid) sweep) and cerefox_metadata_health (rows with non-object
+-- metadata, surfaced by doctor).
+--
+-- Schema version 0.12.1 → 0.12.2. This migration also REPORTS (not repairs)
+-- any rows already in the non-object state, so the operator sees them at
+-- upgrade time; repair is `cerefox document set-metadata <id> --replace`.
+
+-- Table-level backstop (round-5 review): closes every current and future
+-- direct writer at once, not only the RPC/CLI/web paths patched in code.
+-- NOT VALID: legacy non-object rows survive (reported below) until repaired
+-- with `document set-metadata --replace`, which the constraint then checks.
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'cerefox_documents_metadata_object'
+    ) THEN
+        ALTER TABLE cerefox_documents
+            ADD CONSTRAINT cerefox_documents_metadata_object
+            CHECK (jsonb_typeof(metadata) = 'object') NOT VALID;
+    END IF;
+END $$;
+
+DO $$
+DECLARE
+    v_count INT;
+BEGIN
+    SELECT count(*) INTO v_count
+    FROM cerefox_documents
+    WHERE metadata IS NOT NULL AND jsonb_typeof(metadata) <> 'object';
+    IF v_count > 0 THEN
+        RAISE NOTICE
+            'Migration 0026: % document(s) hold NON-OBJECT metadata (legacy #212 state). List them with cerefox doctor (or SELECT * FROM cerefox_metadata_health()); repair each with cerefox document set-metadata <id> --replace --json ''<object>''.',
+            v_count;
+    ELSE
+        RAISE NOTICE 'Migration 0026: metadata guards + dead-link sweep arrive with rpcs.sql. No non-object metadata rows found. Schema 0.12.2.';
+    END IF;
+END $$;

package/dist/server-assets/db/migrations/0027_drop_archived_search_artifacts.sql

@@ -0,0 +1,172 @@
+-- 0027_drop_archived_search_artifacts.sql — archived chunks carry no search
+-- artifacts (#216). THE CANONICAL RATIONALE LIVES HERE; code comments
+-- reference it.
+--
+-- Search is current-chunks-only by design (every search index is partial on
+-- version_id IS NULL), version reconstruction and diffs read `content`, and
+-- restoring an old version is deliberately manual re-ingest (which
+-- re-embeds). Embeddings and fts on archived chunks were therefore never
+-- readable by anything — pure storage cost, measured at ~30-45% of the chunk
+-- relation on long-lived stores — and after a reindex they are stale for the
+-- current embedder besides. There is no config and no maintenance command:
+-- with nothing able to read the artifacts, this is an invariant, not a
+-- policy. The archived content — the actual safety copy — is untouched.
+--
+-- Four parts:
+--   1. embedding_primary becomes nullable, WITH a replacement guard: a CHECK
+--      that a CURRENT chunk always carries an embedding. Without it, a short
+--      embedding-API response could insert a silently search-invisible chunk
+--      where the old NOT NULL failed loudly (review round 6).
+--   2. The NEW cerefox_snapshot_version ships INSIDE this migration (repo
+--      precedent: 0005-0008, 0011, 0025 carry function bodies). This closes
+--      two windows where the OLD snapshot could keep archiving WITH
+--      artifacts after 0027 was stamped: `bun scripts/db_migrate.ts` (which
+--      never refreshes rpcs.sql), and a `server deploy` that failed between
+--      the migration step and the RPC refresh.
+--   3. Back-fill: strip artifacts from existing archived rows, reporting
+--      rows and bytes. embedder_upgrade is nulled with its vector;
+--      embedder_primary is deliberately kept (NOT NULL, harmless provenance).
+--   4. Space note: Postgres frees the bytes for REUSE via autovacuum rather
+--      than shrinking files immediately — growth stops even if the reported
+--      database size does not drop the same day.
+--
+-- Schema version 0.12.2 → 0.13.0.
+
+ALTER TABLE cerefox_chunks ALTER COLUMN embedding_primary DROP NOT NULL;
+
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'cerefox_chunks_current_has_embedding'
+    ) THEN
+        ALTER TABLE cerefox_chunks
+            ADD CONSTRAINT cerefox_chunks_current_has_embedding
+            CHECK (version_id IS NOT NULL OR embedding_primary IS NOT NULL);
+    END IF;
+END $$;
+
+-- The new snapshot (identical to the rpcs.sql copy this release ships):
+
+DROP FUNCTION IF EXISTS cerefox_snapshot_version(UUID, TEXT, INT);
+DROP FUNCTION IF EXISTS cerefox_snapshot_version(UUID, TEXT, INT, BOOLEAN);
+CREATE FUNCTION cerefox_snapshot_version(
+    p_document_id       UUID,
+    p_source            TEXT    DEFAULT 'manual',
+    -- NULL (the new default) means "use the store's policy from
+    -- cerefox_config". Passing a value still overrides, for deliberate one-off
+    -- admin operations — but callers no longer supply one by accident.
+    p_retention_hours   INT     DEFAULT NULL,
+    p_cleanup_enabled   BOOLEAN DEFAULT NULL
+)
+RETURNS TABLE (
+    version_id     UUID,
+    version_number INT,
+    chunk_count    INT,
+    total_chars    INT
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_version_id     UUID;
+    v_version_number INT;
+    v_chunk_count    INT;
+    v_total_chars    INT;
+    -- Resolve the retention policy from the STORE, not the caller.
+    --
+    -- These used to arrive as parameters filled from each client's own env, so
+    -- the surviving version history depended on which client wrote last: an
+    -- agent running defaults would prune versions that an operator had
+    -- configured to keep. Retention describes the data, so it belongs to the
+    -- data. Same COALESCE(param, config, default) shape the retrieval tunables
+    -- already use.
+    v_retention      INT     := COALESCE(p_retention_hours,
+                                         cerefox_config_int('version_retention_hours', 120));
+    v_cleanup        BOOLEAN := COALESCE(p_cleanup_enabled,
+                                         cerefox_config_bool('version_cleanup_enabled', TRUE));
+BEGIN
+    -- Count current chunks to record in the version metadata
+    SELECT COUNT(*), COALESCE(SUM(char_count), 0)
+    INTO v_chunk_count, v_total_chars
+    FROM cerefox_chunks c
+    WHERE c.document_id = p_document_id
+      AND c.version_id IS NULL;
+
+    -- Compute the next version number (sequential per document)
+    SELECT COALESCE(MAX(dv.version_number), 0) + 1
+    INTO v_version_number
+    FROM cerefox_document_versions dv
+    WHERE dv.document_id = p_document_id;
+
+    -- Create the version row
+    INSERT INTO cerefox_document_versions (
+        document_id, version_number, source, chunk_count, total_chars
+    ) VALUES (
+        p_document_id, v_version_number, p_source, v_chunk_count, v_total_chars
+    )
+    RETURNING id INTO v_version_id;
+
+    -- Archive all current chunks by pointing them at the new version, and
+    -- NULL their search artifacts in the same write (0.13.0, #216 — full
+    -- rationale in migration 0027). The content — the actual safety copy —
+    -- is untouched. embedder_upgrade is nulled with its vector;
+    -- embedder_primary is deliberately KEPT (it is NOT NULL, and the label
+    -- is harmless provenance for a vector that no longer exists — nothing
+    -- reads embedder columns without a version_id IS NULL filter).
+    UPDATE cerefox_chunks c
+    SET version_id = v_version_id,
+        embedding_primary = NULL,
+        embedding_upgrade = NULL,
+        embedder_upgrade = NULL,
+        fts = NULL
+    WHERE c.document_id = p_document_id
+      AND c.version_id IS NULL;
+
+    -- Lazy retention: delete versions outside the retention window,
+    -- but always keep the most recently created version (the one we just made).
+    -- Skip archived versions (archived=true) -- they are protected from cleanup.
+    -- Skip cleanup entirely if p_cleanup_enabled is false (immutable mode).
+    IF v_cleanup THEN
+        DELETE FROM cerefox_document_versions dv
+        WHERE dv.document_id = p_document_id
+          AND dv.archived IS NOT TRUE
+          AND dv.created_at < NOW() - (v_retention || ' hours')::INTERVAL
+          AND dv.id != (
+              SELECT id FROM cerefox_document_versions
+              WHERE document_id = p_document_id
+              ORDER BY created_at DESC
+              LIMIT 1
+          );
+    END IF;
+
+    RETURN QUERY SELECT v_version_id, v_version_number, v_chunk_count, v_total_chars;
+END;
+$$;
+
+DO $$
+DECLARE
+    v_rows  INT;
+    v_bytes BIGINT;
+BEGIN
+    SELECT count(*),
+           COALESCE(SUM(COALESCE(pg_column_size(embedding_primary), 0))
+                  + SUM(COALESCE(pg_column_size(embedding_upgrade), 0))
+                  + SUM(COALESCE(pg_column_size(fts), 0)), 0)
+    INTO v_rows, v_bytes
+    FROM cerefox_chunks
+    WHERE version_id IS NOT NULL
+      AND (embedding_primary IS NOT NULL OR embedding_upgrade IS NOT NULL OR fts IS NOT NULL);
+
+    UPDATE cerefox_chunks
+    SET embedding_primary = NULL,
+        embedding_upgrade = NULL,
+        embedder_upgrade = NULL,
+        fts = NULL
+    WHERE version_id IS NOT NULL
+      AND (embedding_primary IS NOT NULL OR embedding_upgrade IS NOT NULL OR fts IS NOT NULL);
+
+    RAISE NOTICE
+        'Migration 0027: stripped search artifacts from % archived chunk row(s), freeing ~% for reuse. Archived content is untouched; current chunks keep their embeddings.',
+        v_rows, pg_size_pretty(v_bytes);
+END $$;

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

@@ -1009,9 +1009,19 @@ BEGIN
     )
     RETURNING id INTO v_version_id;
 
-    -- Archive all current chunks by pointing them at the new version
+    -- Archive all current chunks by pointing them at the new version, and
+    -- NULL their search artifacts in the same write (0.13.0, #216 — full
+    -- rationale in migration 0027). The content — the actual safety copy —
+    -- is untouched. embedder_upgrade is nulled with its vector;
+    -- embedder_primary is deliberately KEPT (it is NOT NULL, and the label
+    -- is harmless provenance for a vector that no longer exists — nothing
+    -- reads embedder columns without a version_id IS NULL filter).
     UPDATE cerefox_chunks c
-    SET version_id = v_version_id
+    SET version_id = v_version_id,
+        embedding_primary = NULL,
+        embedding_upgrade = NULL,
+        embedder_upgrade = NULL,
+        fts = NULL
     WHERE c.document_id = p_document_id
       AND c.version_id IS NULL;
 
@@ -1247,6 +1257,9 @@ $$;
 
 DROP FUNCTION IF EXISTS cerefox_restore_document(UUID, TEXT, TEXT, TEXT);
 DROP FUNCTION IF EXISTS cerefox_restore_document(UUID, TEXT, TEXT);
+-- 0.12.1: the pre-author 1-arg overload survived every CREATE OR REPLACE
+-- since the signature grew (same orphan class as purge; found live on a long-lived database).
+DROP FUNCTION IF EXISTS cerefox_restore_document(UUID);
 CREATE FUNCTION cerefox_restore_document(
     p_document_id   UUID,
     p_author        TEXT    DEFAULT 'unknown',
@@ -1309,7 +1322,14 @@ $$;
 -- ── cerefox_purge_document ───────────────────────────────────────────────────
 -- Permanently deletes a soft-deleted document (CASCADE). Only works on
 -- documents that are already soft-deleted (deleted_at IS NOT NULL).
+--
+-- 0.12.1: drop the pre-author 1-arg overload. CREATE OR REPLACE never removed
+-- it when the signature grew, so long-lived databases carried BOTH — and a
+-- 1-arg named call was ambiguous there (PGRST203), which is how the first
+-- prod acceptance run failed to purge its fixtures. Same cleanup for
+-- cerefox_restore_document below.
 
+DROP FUNCTION IF EXISTS cerefox_purge_document(UUID);
 CREATE OR REPLACE FUNCTION cerefox_purge_document(
     p_document_id   UUID,
     p_author        TEXT    DEFAULT 'unknown',
@@ -1347,6 +1367,43 @@ END;
 $$;
 
 
+-- ── cerefox_extract_doc_link_ids ─────────────────────────────────────────────
+-- The ONE implementation of [Text](uuid) link scanning (#214), shared by the
+-- write-time guard in cerefox_ingest_document and the cerefox_find_dead_links
+-- sweep — "same scanning rules" is enforced by this being the only copy.
+--
+-- Fences are LINE-ANCHORED and handled by SPLITTING, not by a paired-fence
+-- regex: Postgres AREs give the whole RE the greediness of their first
+-- quantified atom, which silently overrode a later .*? and made a closed
+-- fence strip everything to end-of-string (round-5 review, verified live) —
+-- blinding the scan to every link after any code block. Odd-numbered split
+-- segments are outside fences; an unterminated fence leaves its tail inside
+-- an even segment, dropped (under-validate, never false-reject). Inline code
+-- spans are stripped after (their regex has no greediness hazard).
+
+CREATE OR REPLACE FUNCTION cerefox_extract_doc_link_ids(p_content TEXT)
+RETURNS TABLE (link_id TEXT)
+LANGUAGE sql
+IMMUTABLE
+SET search_path = public, pg_catalog
+AS $$
+    WITH segments AS (
+        SELECT seg, row_number() OVER () AS rn
+        FROM regexp_split_to_table(COALESCE(p_content, ''), '^[ \t]*```.*$', 'n') AS seg
+    ),
+    outside AS (
+        SELECT string_agg(regexp_replace(seg, '`[^`]*`', ' ', 'g'), ' ') AS s
+        FROM segments
+        WHERE rn % 2 = 1
+    )
+    SELECT lower(m[1])
+    FROM outside,
+    LATERAL regexp_matches(
+        outside.s,
+        '\]\(([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\)',
+        'g') AS m;
+$$;
+
 -- ── cerefox_ingest_document ──────────────────────────────────────────────────
 -- Single RPC for ingesting a document (create or update). Handles:
 --   - Create: insert document row, insert chunks, set review_status, create audit entry
@@ -1494,6 +1551,19 @@ BEGIN
             USING ERRCODE = '22023';  -- invalid_parameter_value
     END IF;
 
+    -- ── Metadata type guard (#212, 0.12.2) ───────────────────────────────
+    -- metadata is jsonb and accepts ANY JSON value, but every reader assumes
+    -- an object — and `document edit`'s JS spread DECOMPOSED a stored string
+    -- into per-character keys (13 real documents were in the vulnerable
+    -- state). The MCP layer always validated this; the RPC now does too, so
+    -- every write path agrees (CLI, scripts, direct PostgREST included).
+    IF p_metadata IS NOT NULL AND jsonb_typeof(p_metadata) <> 'object' THEN
+        RAISE EXCEPTION
+            'cerefox_ingest_document: metadata must be a JSON object, got %. Wrap scalar values in a key ({"value": ...}).',
+            jsonb_typeof(p_metadata)
+            USING ERRCODE = '22023';  -- invalid_parameter_value
+    END IF;
+
     -- ── Link integrity (#214, 0.12.0) ────────────────────────────────────
     -- Validate [Text](uuid) document links against the store: agents mangle
     -- long random ids when regenerating text, and a mangled id silently
@@ -1506,23 +1576,14 @@ BEGIN
     -- See docs/specs/link-integrity-design.md.
     SELECT string_agg(c->>'content', E'\n') INTO v_scannable
     FROM jsonb_array_elements(p_chunks) c;
-    -- Fences are LINE-ANCHORED, matching markdown semantics: only ``` at a
-    -- line start opens/closes a block, so a stray backtick run mid-prose
-    -- cannot mis-pair the fences and un-escape a later real code block. An
-    -- unterminated fence strips to end-of-content (under-validates, never
-    -- false-rejects). Inline code is stripped after, so fence markers are
-    -- intact when pairing runs.
-    v_scannable := regexp_replace(
-        COALESCE(v_scannable, ''),
-        E'(^|\\n)[ \\t]*```.*?(\\n[ \\t]*```[^\\n]*|$)', ' ', 'g');
-    v_scannable := regexp_replace(v_scannable, '`[^`]*`', ' ', 'g');
-
-    SELECT array_agg(DISTINCT m[1]) INTO v_missing
-    FROM regexp_matches(
-        v_scannable,
-        '\]\(([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\)',
-        'g') m
-    WHERE NOT EXISTS (SELECT 1 FROM cerefox_documents d WHERE d.id = m[1]::uuid);
+
+    -- Scanning delegated to cerefox_extract_doc_link_ids — the one copy of
+    -- the fence/inline-code/uuid rules, shared with the dead-link sweep
+    -- (0.12.2; the previous inline regex was defeated by ARE whole-RE
+    -- greediness — see the helper's header).
+    SELECT array_agg(DISTINCT l.link_id) INTO v_missing
+    FROM cerefox_extract_doc_link_ids(v_scannable) l
+    WHERE NOT EXISTS (SELECT 1 FROM cerefox_documents d WHERE d.id = l.link_id::uuid);
 
     -- On UPDATE, tolerate dead links the document ALREADY carries: a target
     -- purged after linking must not make the document unwritable — sync
@@ -1778,9 +1839,9 @@ $$;
 -- Reads chunk title and content directly from the DB -- caller only needs to
 -- supply the new document title.
 --
--- Only affects current chunks (version_id IS NULL). Archived chunks retain their
--- original tsvectors (they are excluded from all search indexes and require
--- re-ingestion to restore anyway).
+-- Only affects current chunks (version_id IS NULL). Archived chunks carry NO
+-- tsvector at all since 0.13.0 (#216) — fts is nulled at archive time, and a
+-- restore is a re-ingest that recomputes everything.
 
 DROP FUNCTION IF EXISTS cerefox_update_chunk_fts(UUID, TEXT);
 CREATE FUNCTION cerefox_update_chunk_fts(
@@ -2662,6 +2723,30 @@ BEGIN
             USING ERRCODE = 'P0002';
     END IF;
 
+    -- #212: a legacy row can hold NON-OBJECT metadata (the ingest RPC did not
+    -- validate its input until 0.12.2). Merging onto it with || would produce
+    -- an ARRAY — Postgres treats both sides as arrays — burying the stored
+    -- value one level deeper and leaving the row still corrupt. Only replace
+    -- actually repairs such a row, so refuse the merge and say so. jsonb
+    -- 'null' is treated like SQL NULL (empty), matching the CLI.
+    IF NOT p_replace AND v_before IS NOT NULL
+       AND jsonb_typeof(v_before) NOT IN ('object', 'null') THEN
+        RAISE EXCEPTION
+            'CEREFOX_BAD_METADATA: stored metadata on document % is not an object (%). A merge cannot repair it — retry with replace (CLI: --replace; MCP: replace: true), passing the full intended object.',
+            p_document_id, jsonb_typeof(v_before)
+            USING ERRCODE = '22023';
+    END IF;
+
+    -- Normalized BEFORE value for merge and reporting: everything below must
+    -- work when the stored value is a scalar/array/'null' and p_replace is
+    -- true — that is the REPAIR path, and jsonb_object_keys on a scalar
+    -- errors, which would roll back the repair itself (round-5 review,
+    -- verified live).
+    v_before := CASE
+        WHEN v_before IS NULL OR jsonb_typeof(v_before) <> 'object' THEN '{}'::jsonb
+        ELSE v_before
+    END;
+
     -- Keys explicitly set to null are removals, never stored values.
     SELECT COALESCE(array_agg(key), ARRAY[]::TEXT[]) INTO v_null_keys
     FROM jsonb_each(p_metadata)
@@ -2713,6 +2798,15 @@ 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.
+    -- 0.13.0 (#216): archived chunks carry no search artifacts —
+    -- cerefox_snapshot_version nulls embedding_primary/embedding_upgrade/fts
+    -- at archive time; embedding_primary becomes nullable; migration 0027
+    -- strips existing archived rows.
+    -- 0.12.2 (#212, #214): metadata must be a JSON object (ingest input guard
+    -- + set_document_metadata stored-state merge guard); cerefox_find_dead_links
+    -- (link-integrity phase-2 sweep); cerefox_metadata_health (doctor check).
+    -- 0.12.1: drop orphaned 1-arg overloads of purge/restore (pre-author era;
+    -- CREATE OR REPLACE never removed them; ambiguous PGRST203 on 1-arg calls).
     -- 0.12.0 (#208, #210): cerefox_delete_document — CAS
     -- (p_expected_content_hash), p_reason in audit description, JSONB return,
     -- idempotent re-delete; cerefox_restore_document — same rework (JSONB,
@@ -2726,7 +2820,75 @@ AS $$
     -- 0.11.0 supersedes 0.10.6 (v1.2.1, #191): this branch carries that fix plus
     -- the partial-edit surface, and both migrations (0019, 0020) are in the
     -- sequence, so a store deploying this gets everything from both lines.
-    SELECT '0.12.0'::TEXT;
+    SELECT '0.13.0'::TEXT;
+$$;
+
+-- ── cerefox_find_dead_links ──────────────────────────────────────────────────
+-- Phase 2 of link integrity (#214): a read-only whole-KB sweep for
+-- [Text](uuid) links whose target document no longer EXISTS (purged after
+-- linking). Complements the write-time guard, which validates only
+-- newly-introduced links on updates. Same scanning rules as the guard:
+-- line-anchored fences and inline code spans are stripped (examples are not
+-- links); a trashed target still exists and is NOT a dead link.
+-- Full chunk scan — run on demand (CLI `cerefox document dead-links`), not on
+-- every doctor.
+
+CREATE OR REPLACE FUNCTION cerefox_find_dead_links()
+RETURNS TABLE (
+    document_id     UUID,
+    document_title  TEXT,
+    dead_link_id    UUID,
+    occurrences     BIGINT
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+    -- Scanning delegated to cerefox_extract_doc_link_ids — the one copy of
+    -- the fence/inline-code/uuid rules, shared with the write-time guard.
+    -- Deliberate scope: trashed LINKER documents are excluded (they are
+    -- inert until restored; restoring one re-enters it into the next sweep).
+    WITH doc_content AS (
+        SELECT d.id, d.title, string_agg(c.content, E'\n' ORDER BY c.chunk_index) AS content
+        FROM cerefox_documents d
+        JOIN cerefox_chunks c ON c.document_id = d.id AND c.version_id IS NULL
+        WHERE d.deleted_at IS NULL
+        GROUP BY d.id, d.title
+    ),
+    links AS (
+        SELECT dc.id, dc.title, l.link_id AS target
+        FROM doc_content dc,
+        LATERAL cerefox_extract_doc_link_ids(dc.content) l
+    )
+    SELECT l.id, l.title, l.target::uuid, count(*)
+    FROM links l
+    WHERE NOT EXISTS (SELECT 1 FROM cerefox_documents t WHERE t.id = l.target::uuid)
+    GROUP BY l.id, l.title, l.target
+    ORDER BY l.title, l.target;
+$$;
+
+-- ── cerefox_metadata_health ──────────────────────────────────────────────────
+-- #212: rows whose stored metadata is not a JSON object — the state the
+-- 0.12.2 write guards now prevent, but which legacy rows may still be in.
+-- Cheap (documents table only); surfaced by `cerefox doctor`. Repair:
+-- `cerefox document set-metadata <id> --replace --json '<object>'`.
+
+CREATE OR REPLACE FUNCTION cerefox_metadata_health()
+RETURNS TABLE (
+    document_id     UUID,
+    document_title  TEXT,
+    metadata_type   TEXT
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+    SELECT d.id, d.title, jsonb_typeof(d.metadata)
+    FROM cerefox_documents d
+    WHERE d.metadata IS NOT NULL AND jsonb_typeof(d.metadata) <> 'object'
+    ORDER BY d.title;
 $$;
 
 -- ── 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.12.0
+-- @version: 0.13.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 —
@@ -42,7 +42,15 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     source_path     TEXT,
     -- SHA-256 of raw markdown content; used for deduplication
     content_hash    TEXT        NOT NULL,
-    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    -- #212 (0.12.2): must be a JSON OBJECT — jsonb accepts any JSON value,
+    -- but every reader assumes an object, and non-object values were silently
+    -- destroyed by read-modify-write paths. The table-level CHECK closes all
+    -- current AND future direct writers at once; existing databases get it as
+    -- NOT VALID via migration 0026 (legacy rows survive until repaired with
+    -- `document set-metadata --replace`, which the constraint then validates).
+    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb
+                    CONSTRAINT cerefox_documents_metadata_object
+                    CHECK (jsonb_typeof(metadata) = 'object'),
     chunk_count     INT         NOT NULL DEFAULT 0,
     total_chars     INT         NOT NULL DEFAULT 0,
     -- review_status: human governance flag. 'approved' = validated by human,
@@ -204,8 +212,16 @@ CREATE TABLE IF NOT EXISTS cerefox_chunks (
     -- reconstructs with its OWN format. See docs/guides/content-format.md.
     content_format  SMALLINT    NOT NULL DEFAULT 1,
 
-    -- Primary embedding: always computed, cloud API (default: OpenAI text-embedding-3-small)
-    embedding_primary  VECTOR(768) NOT NULL,
+    -- Primary embedding: always computed on write, cloud API (default: OpenAI
+    -- text-embedding-3-small). NULL only on ARCHIVED rows (0.13.0, #216 —
+    -- rationale in migration 0027): archiving nulls the search artifacts.
+    -- The CHECK below preserves the pre-0.13.0 guarantee that a CURRENT
+    -- chunk always has an embedding — without it, a short embedding-API
+    -- response could insert a silently search-invisible chunk where the old
+    -- NOT NULL failed loudly.
+    embedding_primary  VECTOR(768)
+                       CONSTRAINT cerefox_chunks_current_has_embedding
+                       CHECK (version_id IS NOT NULL OR embedding_primary IS NOT NULL),
     -- Upgrade embedding: optional, alternative model (Fireworks, Vertex, etc.)
     embedding_upgrade  VECTOR(768),
 

package/docs/guides/cli.md

@@ -226,6 +226,12 @@ cerefox document list [OPTIONS]
 
 **Purpose**: update a document's title and/or metadata in place, without re-ingesting content.
 
+> **v1.7.1 (#212)**: a title-only edit no longer writes `metadata` at all, and
+> the command refuses to patch a document whose stored metadata is not a JSON
+> object (a legacy state older writes could create) instead of destroying it —
+> repair such a row with `cerefox document set-metadata <id> --replace --json
+> '<object>'`. `cerefox doctor` lists any rows in that state.
+
 **Synopsis**:
 ```
 cerefox document edit [OPTIONS] DOCUMENT_ID
@@ -341,6 +347,20 @@ cerefox document set-projects <doc-id> --clear
 
 ---
 
+### `cerefox document dead-links`
+
+**Purpose**: whole-KB sweep for `[Text](uuid)` links whose target document no longer exists (phase 2 of link integrity, #214; v1.7.1, needs schema 0.12.2).
+
+**Synopsis**: `cerefox document dead-links [--json]`
+
+The write-time guard (v1.7.0) validates only links a write *introduces* — deliberately, so a target purged after linking cannot make its linkers unwritable. This command finds those legacy dead links on demand. A trashed target still exists and is **not** reported; trashed **linker** documents are also excluded (inert until restored — a restore re-enters them into the next sweep). Full chunk scan server-side (one RPC call); run on demand, not part of `doctor`.
+
+**Fix each hit** by editing the linking document: correct the id, remove the link, or backtick it as an example. Full linking overview: [`linking.md`](linking.md).
+
+**MCP equivalent**: none (maintenance verb).
+
+---
+
 ### `cerefox document restore`
 
 **Purpose**: restore a soft-deleted (trashed) document back to active.
@@ -806,6 +826,7 @@ surface).
 | `document get` | `cerefox_get_document` | ✅ |
 | `document list` | `cerefox_metadata_search` (scope by `project_name` / metadata / time) | ✅ as of this change. Unscoped whole-KB listing has no MCP path by design (scope it) |
 | `document edit` (title / metadata in place) | — | 🔒 intentional: a human/web-parity convenience. Agents update title+metadata deterministically via `cerefox_ingest` (with `document_id`); a metadata-only edit isn't a needed agent primitive |
+| `document dead-links` | — | 🔒 intentional: a maintenance sweep for the operator (v1.7.1, #214 phase 2); agents encounter dead links through the write-time guard instead |
 | `document delete` (soft-delete) | `cerefox_delete_document` | ✅ v1.7.0 (#208). MCP requires the caller's read-hash; the CLI confirms interactively instead |
 | `document restore` | `cerefox_restore_document` | ✅ v1.7.0 (#210). Permanent purge remains web-UI-only |
 | `document version list` | `cerefox_list_versions` | ✅ |

package/docs/guides/upgrading.md

@@ -150,6 +150,15 @@ knowing about:
   you're coming from a pre-installer 0.1.x clone, see the "old pre-installer
   clone" note above: install the package and run `cerefox init`.
 
+## Notable: v1.8.0 storage reclaim (migration 0027)
+
+Upgrading to v1.8.0 strips never-read search artifacts from archived version
+chunks (rationale: #216 / the migration's own header) and the migration
+prints what it freed. Postgres releases the bytes for **reuse** via
+autovacuum rather than shrinking files immediately, so expect growth to stop
+rather than the reported database size to drop the same day. Archived
+version *content* is untouched.
+
 ## After upgrading: AI agents
 
 New tools and updated tool signatures are picked up by MCP clients in **new

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "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",
@@ -65,7 +65,7 @@
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "build": "bun build src/bin/cerefox.ts --outdir dist/bin --target node --format esm --external @huggingface/transformers --external onnxruntime-node",
+    "build": "bun run bundle-server-assets && bun build src/bin/cerefox.ts --outdir dist/bin --target node --format esm --external @huggingface/transformers --external onnxruntime-node",
     "clean": "rm -rf dist docs AGENT_GUIDE.md AGENT_QUICK_REFERENCE.md",
     "bundle-docs": "bun run ../../scripts/bundle_package_docs.ts",
     "bundle-server-assets": "bun run ../../scripts/bundle_server_assets.ts",