@cerefox/memory 1.6.1 → 1.7.1

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

@@ -1127,33 +1127,88 @@ $$;
 -- Soft-deletes a document by setting deleted_at = NOW(). The document, its
 -- chunks, and versions remain in the database but are excluded from search.
 -- Use cerefox_purge_document for permanent deletion.
--- Use cerefox_restore_document to undo a soft delete.
+-- Use cerefox_restore_document to undo a soft delete (agent-reachable since
+-- 0.12.0, #210). Permanent purge is web-UI-only by design (access-paths.md →
+-- "Destructive operations and the trust model").
+--
+-- p_expected_content_hash (0.12.0, #208): optional CAS. When provided, the
+-- delete proceeds only if it matches the document's current content_hash —
+-- proof the caller read what it is deleting. Checked under the same FOR UPDATE
+-- lock as the ingest CAS (iter-32); mismatch → CEREFOX_CONFLICT under PT409,
+-- never a retryable SQLSTATE. NULL/blank skips the check: the CLI confirms
+-- interactively instead, and the MCP tool makes the parameter required at the
+-- transport layer (its callers have no interactive prompt).
+-- p_reason (0.12.0, #208): optional, appended to the audit description — for
+-- the human reviewing the trash, who otherwise sees only what was deleted.
+--
+-- Deleting an already-deleted document is a reported no-op: the original
+-- deleted_at is preserved and no duplicate audit entry is written.
 
+DROP FUNCTION IF EXISTS cerefox_delete_document(UUID, TEXT, TEXT, TEXT, TEXT);
 DROP FUNCTION IF EXISTS cerefox_delete_document(UUID, TEXT, TEXT);
 DROP FUNCTION IF EXISTS cerefox_delete_document(UUID);
 CREATE FUNCTION cerefox_delete_document(
-    p_document_id   UUID,
-    p_author        TEXT    DEFAULT 'unknown',
-    p_author_type   TEXT    DEFAULT 'user'
+    p_document_id           UUID,
+    p_author                TEXT    DEFAULT 'unknown',
+    p_author_type           TEXT    DEFAULT 'user',
+    p_expected_content_hash TEXT    DEFAULT NULL,
+    p_reason                TEXT    DEFAULT NULL
 )
-RETURNS VOID
+RETURNS JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
 SET search_path = public, pg_catalog
 AS $$
 DECLARE
-    v_title      TEXT;
-    v_total_chars INT;
+    v_title        TEXT;
+    v_total_chars  INT;
+    v_current_hash TEXT;
+    v_deleted_at   TIMESTAMPTZ;
 BEGIN
-    SELECT title, total_chars INTO v_title, v_total_chars
-    FROM cerefox_documents WHERE id = p_document_id;
+    -- FOR UPDATE: makes the hash check atomic with the delete — a concurrent
+    -- content update serializes here, and a stale deleter sees its hash.
+    SELECT title, total_chars, content_hash, deleted_at
+    INTO v_title, v_total_chars, v_current_hash, v_deleted_at
+    FROM cerefox_documents WHERE id = p_document_id
+    FOR UPDATE;
 
     IF NOT FOUND THEN
-        RAISE EXCEPTION 'Document % not found', p_document_id;
+        RAISE EXCEPTION 'Document % not found', p_document_id
+            USING ERRCODE = '22023';  -- invalid_parameter_value
     END IF;
 
-    -- Soft delete: set deleted_at timestamp
-    UPDATE cerefox_documents SET deleted_at = NOW() WHERE id = p_document_id;
+    -- Optimistic concurrency: blank is ABSENT, not stale (same rule and same
+    -- reason as cerefox_ingest_document — '' can never equal a real hash, so
+    -- classifying it as a conflict would be a permanent failure reported as a
+    -- resolvable one).
+    -- Compare TRIMMED, matching the presence check: a correct hash with a
+    -- stray trailing newline must not be misreported as a stale-hash
+    -- conflict — that reads as "changed since it was read" with two hashes
+    -- that look identical, and re-reading can never fix it.
+    -- Validated BEFORE the already-deleted no-op: "a delete proves a read"
+    -- has to hold for trashed documents too, or a garbage hash gets reported
+    -- as a successful no-op and the caller learns nothing.
+    IF NULLIF(BTRIM(p_expected_content_hash), '') IS NOT NULL
+       AND BTRIM(p_expected_content_hash) <> v_current_hash THEN
+        RAISE EXCEPTION
+            'CEREFOX_CONFLICT: document % changed since it was read (expected hash %, current hash %). Re-read the document, check it still warrants deletion, and retry with the new hash.',
+            p_document_id, p_expected_content_hash, v_current_hash
+            USING ERRCODE = 'PT409';  -- deterministic conflict; see ingest CAS
+    END IF;
+
+    IF v_deleted_at IS NOT NULL THEN
+        RETURN jsonb_build_object(
+            'document_id', p_document_id,
+            'title', v_title,
+            'total_chars', v_total_chars,
+            'deleted_at', v_deleted_at,
+            'already_deleted', TRUE
+        );
+    END IF;
+
+    UPDATE cerefox_documents SET deleted_at = NOW()
+    WHERE id = p_document_id
+    RETURNING deleted_at INTO v_deleted_at;
 
     PERFORM cerefox_create_audit_entry(
         p_document_id := p_document_id,
@@ -1163,33 +1218,72 @@ BEGIN
         p_size_before := v_total_chars,
         p_size_after := 0,
         p_description := 'Soft-deleted document: ' || COALESCE(v_title, '(untitled)') ||
-                         ' (' || COALESCE(v_total_chars, 0) || ' chars)'
+                         ' (' || COALESCE(v_total_chars, 0) || ' chars)' ||
+                         COALESCE('; reason: ' || NULLIF(BTRIM(p_reason), ''), '')
+    );
+
+    RETURN jsonb_build_object(
+        'document_id', p_document_id,
+        'title', v_title,
+        'total_chars', v_total_chars,
+        'deleted_at', v_deleted_at,
+        'already_deleted', FALSE
     );
 END;
 $$;
 
 -- ── cerefox_restore_document ─────────────────────────────────────────────────
 -- Restores a soft-deleted document by clearing deleted_at.
-
-CREATE OR REPLACE FUNCTION cerefox_restore_document(
+--
+-- 0.12.0 (#210): agent-reachable — exposed over MCP as cerefox_restore_document
+-- alongside the CLI verb, by maintainer decision (2026-08-13): everything is
+-- audited, restore cannot destroy content, and CLI/MCP parity outweighs the
+-- earlier "an agent must not undo its own delete" posture, which predated the
+-- audit surface. Permanent purge remains web-UI-only.
+-- Same honesty contract as the reworked delete: JSONB return; restoring a
+-- document that is not deleted is a reported no-op (no audit entry); a missing
+-- document raises rather than silently returning. p_reason lands in the audit
+-- description.
+
+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 prod).
+DROP FUNCTION IF EXISTS cerefox_restore_document(UUID);
+CREATE FUNCTION cerefox_restore_document(
     p_document_id   UUID,
     p_author        TEXT    DEFAULT 'unknown',
-    p_author_type   TEXT    DEFAULT 'user'
+    p_author_type   TEXT    DEFAULT 'user',
+    p_reason        TEXT    DEFAULT NULL
 )
-RETURNS VOID
+RETURNS JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
 SET search_path = public, pg_catalog
 AS $$
 DECLARE
-    v_title      TEXT;
+    v_title       TEXT;
     v_total_chars INT;
+    v_deleted_at  TIMESTAMPTZ;
 BEGIN
-    SELECT title, total_chars INTO v_title, v_total_chars
-    FROM cerefox_documents WHERE id = p_document_id AND deleted_at IS NOT NULL;
+    SELECT title, total_chars, deleted_at
+    INTO v_title, v_total_chars, v_deleted_at
+    FROM cerefox_documents WHERE id = p_document_id
+    FOR UPDATE;
 
-    IF v_title IS NULL THEN
-        RETURN;  -- Not found or not deleted
+    IF NOT FOUND THEN
+        RAISE EXCEPTION 'Document % not found', p_document_id
+            USING ERRCODE = '22023';  -- invalid_parameter_value
+    END IF;
+
+    IF v_deleted_at IS NULL THEN
+        RETURN jsonb_build_object(
+            'document_id', p_document_id,
+            'title', v_title,
+            'total_chars', v_total_chars,
+            'restored', FALSE,
+            'was_deleted', FALSE
+        );
     END IF;
 
     UPDATE cerefox_documents SET deleted_at = NULL WHERE id = p_document_id;
@@ -1201,7 +1295,16 @@ BEGIN
         p_author_type := p_author_type,
         p_size_before := 0,
         p_size_after := v_total_chars,
-        p_description := 'Restored document: ' || COALESCE(v_title, '(untitled)')
+        p_description := 'Restored document: ' || COALESCE(v_title, '(untitled)') ||
+                         COALESCE('; reason: ' || NULLIF(BTRIM(p_reason), ''), '')
+    );
+
+    RETURN jsonb_build_object(
+        'document_id', p_document_id,
+        'title', v_title,
+        'total_chars', v_total_chars,
+        'restored', TRUE,
+        'was_deleted', TRUE
     );
 END;
 $$;
@@ -1209,7 +1312,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',
@@ -1247,6 +1357,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
@@ -1371,6 +1518,9 @@ DECLARE
     v_op            JSONB;      -- iter-33: per-operation audit element
     v_size_warn_at  INT;
     v_size_warning  BOOLEAN := FALSE;
+    v_doc_deleted   TIMESTAMPTZ;
+    v_scannable     TEXT;
+    v_missing       TEXT[];
 BEGIN
     -- ── Zero-chunk guard (v0.3.1) ────────────────────────────────────────
     -- Refuse to create or update a document with no chunks. Three reasons:
@@ -1391,6 +1541,64 @@ 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
+    -- becomes a dead link. Fenced code blocks and inline code spans are
+    -- stripped first — code formatting is the markdown-native way to write
+    -- an EXAMPLE link, and the escape mechanism here (no bypass flag, by
+    -- design). Trashed targets resolve: the id denotes a document. One PK
+    -- lookup for all candidates; ~1-2ms. Runs on create AND update, so a
+    -- link whose target was later purged surfaces on the next edit.
+    -- See docs/specs/link-integrity-design.md.
+    SELECT string_agg(c->>'content', E'\n') INTO v_scannable
+    FROM jsonb_array_elements(p_chunks) c;
+
+    -- 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
+    -- flows re-send content verbatim from disk and could never converge, and
+    -- an unrelated partial edit re-sends the untouched section holding the
+    -- link. Only NEWLY-INTRODUCED unresolvable ids reject; legacy dead links
+    -- are the phase-2 sweep's job (#214). Creates validate everything.
+    IF v_missing IS NOT NULL AND p_document_id IS NOT NULL THEN
+        SELECT array_agg(x) INTO v_missing
+        FROM unnest(v_missing) x
+        WHERE strpos(
+            lower(COALESCE((SELECT string_agg(ch.content, E'\n')
+                            FROM cerefox_chunks ch
+                            WHERE ch.document_id = p_document_id
+                              AND ch.version_id IS NULL), '')),
+            lower(x)) = 0;
+    END IF;
+
+    IF v_missing IS NOT NULL THEN
+        RAISE EXCEPTION
+            'CEREFOX_UNRESOLVED_LINKS: % linked document id(s) do not exist: %. If these were meant to link existing documents, the ids are mangled — re-read the source and correct them. If they are examples, put them in code formatting (backticks or a fence).',
+            array_length(v_missing, 1), array_to_string(v_missing, ', ')
+            USING ERRCODE = '22023';  -- deterministic; never a retryable SQLSTATE
+    END IF;
+
     -- Validate review_status
     v_status := CASE WHEN p_review_status IN ('approved', 'pending_review')
                      THEN p_review_status ELSE 'approved' END;
@@ -1412,8 +1620,8 @@ BEGIN
         -- updaters serialize here, and the second one sees the first one's
         -- hash — the race window (chunk + embed latency) is closed at the
         -- only place all transports share (iter-32).
-        SELECT COALESCE(d.total_chars, 0), d.content_hash
-        INTO v_old_chars, v_current_hash
+        SELECT COALESCE(d.total_chars, 0), d.content_hash, d.deleted_at
+        INTO v_old_chars, v_current_hash, v_doc_deleted
         FROM cerefox_documents d WHERE d.id = v_doc_id
         FOR UPDATE;
 
@@ -1422,6 +1630,20 @@ BEGIN
                 USING ERRCODE = '22023';  -- invalid_parameter_value
         END IF;
 
+        -- Refuse to rewrite a trashed document (0.12.0, #211 review). Before
+        -- this guard an update by document_id landed content in a document
+        -- excluded from search — a write into a black hole — and it silently
+        -- broke the restore contract: restore takes no freshness token on the
+        -- premise that what was reviewed in the trash is what comes back.
+        IF v_doc_deleted IS NOT NULL THEN
+            -- CEREFOX_ prefix per the convention below: transport handlers
+            -- detect it and rephrase for their caller.
+            RAISE EXCEPTION
+                'CEREFOX_DELETED: document % is soft-deleted; restore it first (cerefox_restore_document / cerefox document restore) or create a new document.',
+                v_doc_id
+                USING ERRCODE = '22023';  -- invalid_parameter_value
+        END IF;
+
         -- ── Optimistic concurrency check (iter-32) ───────────────────
         -- Content updates must prove freshness (expected hash) or explicitly
         -- choose last-write-wins. Message prefixes are machine-detectable:
@@ -1442,7 +1664,10 @@ BEGIN
                     'CEREFOX_TOKEN_REQUIRED: content updates require expected_content_hash (the content_hash you read) or last_write_wins=true. Current hash: %',
                     v_current_hash
                     USING ERRCODE = '22023';  -- invalid_parameter_value
-            ELSIF p_expected_content_hash <> v_current_hash THEN
+            -- Trimmed comparison, matching the presence check above: a correct
+            -- hash with stray whitespace is not a stale one (found via the
+            -- delete CAS review, #208 — same flaw existed here since iter-32).
+            ELSIF BTRIM(p_expected_content_hash) <> v_current_hash THEN
                 RAISE EXCEPTION
                     'CEREFOX_CONFLICT: document % changed since it was read (expected hash %, current hash %). Re-read the document, merge your changes, and retry with the new hash.',
                     v_doc_id, p_expected_content_hash, v_current_hash
@@ -2488,6 +2713,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)
@@ -2539,6 +2788,17 @@ 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.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,
+    -- p_reason, honest no-op). Back the new cerefox_delete_document and
+    -- cerefox_restore_document MCP tools (CLI parity). Ingest CAS compares
+    -- trimmed.
     -- 0.11.3 (#204): cerefox_set_document_metadata — metadata-only writes.
     -- 0.11.2 (iteration 36): RLS enabled on cerefox_document_relations,
     -- which iteration 29 left off the list (Supabase rls_disabled_in_public).
@@ -2546,7 +2806,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.11.3'::TEXT;
+    SELECT '0.12.2'::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.11.3
+-- @version: 0.12.2
 -- 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,

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

@@ -88,6 +88,32 @@ function concurrencyErrorResponse(
       { status: 409, headers },
     );
   }
+  if (message.includes("CEREFOX_UNRESOLVED_LINKS")) {
+    // Link integrity (#214): the content links document id(s) that do not
+    // exist — almost always a mangled UUID. 422: well-formed request whose
+    // content fails a semantic check the caller can fix.
+    return new Response(
+      JSON.stringify({
+        error: "unresolved_links",
+        message:
+          "The content links document id(s) that do not exist. Re-read the source each link was copied from and correct the id(s) — do not retry unchanged. Wrap deliberate example ids in code formatting (backticks).",
+        detail: message,
+      }),
+      { status: 422, headers },
+    );
+  }
+  if (message.includes("CEREFOX_DELETED")) {
+    // 0.12.0: a trashed document refuses content updates until restored.
+    return new Response(
+      JSON.stringify({
+        error: "document_deleted",
+        message:
+          "This document is soft-deleted (in the trash). Restore it first, then retry the update — or create a new document.",
+        detail: message,
+      }),
+      { status: 409, headers },
+    );
+  }
   if (message.includes("CEREFOX_TOKEN_REQUIRED")) {
     return new Response(
       JSON.stringify({

package/docs/guides/access-paths.md

@@ -250,30 +250,37 @@ client-facing configuration or committed to the repository.
 Cerefox classifies write operations into three tiers based on how irreversible they are.
 The access surface for each tier is **not** the same — this asymmetry is a deliberate
 architectural property, not an oversight. Future contributors should read this section
-before "completing" the parity table by adding purge or restore to agent-facing access
-paths.
+before "completing" the parity table by adding purge to agent-facing access paths.
+
+> **History**: until v1.7.0 restore sat in tier 3 with purge, on the theory that an
+> agent must not be able to silently undo its own delete. The maintainer reversed
+> that in #210 (2026-08-13): every delete and restore is audited with author
+> attribution, restore cannot destroy content, and the CLI had `document restore`
+> all along — the boundary the docs described had already outgrown the code. The
+> guarded property is now exactly one thing: **no agent path to permanent purge.**
 
 ### The three tiers
 
 | Tier | Operations | Reversible? | Where exposed |
 |---|---|---|---|
 | 1. Reads + soft mutations | search, get, list-*, ingest (create/update), metadata-search, get-audit-log | n/a (reads) / yes (versioned) | All paths — MCP, Edge Functions, CLI, web UI |
-| 2. Soft-destructive | `delete_document` (soft delete to trash), `set_review_status` | yes — restorable via web UI | All paths (CLI: `cerefox document delete`; web UI; **not** MCP or Edge Functions today) |
-| 3. **Hard-destructive** | `purge_document` (permanent), `restore_document` (un-trash), `set_version_archived` (toggle version retention) | no (purge) / yes (restore, but recovers from a destructive action) | **Web UI only** |
+| 2. Soft-destructive + recovery | `delete_document` (soft delete to trash), `restore_document` (un-trash), `set_review_status` | yes — delete is restorable; restore recovers | CLI (`cerefox document delete` / `restore`), web UI, and — since v1.7.0 (#208, #210) — MCP (`cerefox_delete_document`, which requires the caller's read-hash, and `cerefox_restore_document`). **Not** the primitive GPT-Actions Edge Functions (deliberately deferred). |
+| 3. **Hard-destructive** | `purge_document` (permanent), `set_version_archived` (toggle version retention) | no (purge) | **Web UI only** |
 
-### Why purge / restore are web-UI-only
+### Why purge is web-UI-only
 
 The recovery story behind Cerefox depends on a **human-in-the-loop confirmation step
-before irreversible action.** Soft-delete on its own is not enough — an agent that
-mistakenly soft-deletes a document needs to be unable to silently restore the same
-document later (covering its tracks), and certainly unable to escalate from soft-delete
-to permanent purge.
+before irreversible action.** Everything an agent can do — write, soft-delete,
+restore — is reversible and audited; the one action that destroys data outright is
+reserved for a human who has just looked at what they are about to destroy.
 
 So the access model is:
 
-1. **An agent (via MCP, Edge Function, or CLI) can write or soft-delete freely.** Every
-   such operation is recorded in `cerefox_audit_log` with `author`, `author_type`, and
-   `created_at`. Soft-deleted documents land in trash and are excluded from search.
+1. **An agent (via MCP, Edge Function, or CLI) can write, soft-delete, and restore
+   freely.** Every such operation is recorded in `cerefox_audit_log` with `author`,
+   `author_type`, and `created_at`. Soft-deleted documents land in trash and are
+   excluded from search; a restore puts them back and is itself an audit event, so
+   a delete-then-restore leaves a visible trail rather than silence.
 2. **A human reviews the trash through the Cerefox web UI.** They see the audit history
    for each document, decide whether the agent's action was correct, and either restore
    the document or — only after seeing what they're about to destroy — purge it.
@@ -296,9 +303,11 @@ If you're building tooling that uses the CLI (Path C) or any MCP/Edge Function p
 - **Surface the soft-delete to the user.** When your agent decides to delete something,
   tell the user explicitly: "I soft-deleted X (recoverable from the Cerefox trash in
   the web UI)." This gives them the visibility to review and either restore or commit.
-- **Do not attempt to purge or restore from agent code.** There is intentionally no
-  programmatic path. If your workflow needs purge / restore, that workflow needs human
-  intervention — the design is correct, not incomplete.
+- **Do not attempt to purge from agent code.** There is intentionally no programmatic
+  path to permanent deletion — if your workflow needs purge, that workflow needs human
+  intervention. Restore, by contrast, is freely available since v1.7.0
+  (`cerefox_restore_document` over MCP, `cerefox document restore` on the CLI), audited
+  like every other write.
 
 ### CLI delete-doc — interactive vs scripted