@cerefox/memory 1.6.1 → 1.7.1

package/dist/server-assets/_shared/mcp-tools/partial-edits.ts

@@ -35,7 +35,7 @@ import {
   sha256hex,
 } from "./_chunker.ts";
 import { activeEmbedderName, embedBatch, resolveEmbedderKind } from "../embeddings/index.ts";
-import { logUsage } from "./_utils.ts";
+import { extractConflictHashes, isMissingFunctionError, logUsage } from "./_utils.ts";
 import { McpInvalidParams, type MCPSupabaseClient, type ToolContext, type ToolDefinition } from "./types.ts";
 
 /**
@@ -175,6 +175,28 @@ async function readDocument(
   supabase: MCPSupabaseClient,
   documentId: string,
 ): Promise<{ title: string; content: string; hash: string }> {
+  // Trashed check BEFORE anything else: a partial edit of a trashed document
+  // would otherwise pay for embeddings and then hit the RPC's CEREFOX_DELETED
+  // refusal as an unshaped error, on every retry (round-4 review). ADVISORY
+  // only — the RPC guard is authoritative — so a client without the .from()
+  // surface (test doubles) skips it rather than failing.
+  try {
+    const { data: lifecycle } = await supabase
+      .from("cerefox_documents")
+      .select("deleted_at")
+      .eq("id", documentId)
+      .maybeSingle();
+    if (lifecycle?.deleted_at) {
+      throw new McpInvalidParams(
+        `Document ${documentId} is soft-deleted (in the trash). A trashed document ` +
+          `cannot be edited — restore it first with cerefox_restore_document, then retry.`,
+      );
+    }
+  } catch (e) {
+    if (e instanceof McpInvalidParams) throw e;
+    // fall through — the RPC's CEREFOX_DELETED guard still refuses the write
+  }
+
   const { data, error } = await supabase.rpc("cerefox_get_document", {
     p_document_id: documentId,
     p_version_id: null,
@@ -303,8 +325,7 @@ async function applyAndWrite(
   if (error) {
     const message = error.message ?? "";
     if (message.includes("CEREFOX_CONFLICT")) {
-      const current = message.match(/current hash ([0-9a-f]{64})/)?.[1] ?? "unknown";
-      throw conflictError(documentId, expectedHash, current);
+      throw conflictError(documentId, expectedHash, extractConflictHashes(message).current);
     }
     if (message.includes("cerefox_documents_hash_unique")) {
       // content_hash is UNIQUE store-wide, so an edit whose result matches
@@ -318,7 +339,25 @@ async function applyAndWrite(
           `cerefox_search for the resulting content to find it.`,
       );
     }
-    if (message.includes("does not exist") && message.includes("cerefox_ingest_document")) {
+    if (message.includes("CEREFOX_UNRESOLVED_LINKS")) {
+      // Only ids INTRODUCED by this write reject (the RPC tolerates dead
+      // links the document already carried), so the diagnosis is specific.
+      const ids = message.match(/do not exist: ([^.]+)\./)?.[1] ?? "(unparsed)";
+      throw new Error(
+        `Edit rejected — this edit introduces link(s) to document id(s) that do not ` +
+          `exist: ${ids}. The UUIDs are almost certainly mangled — re-read the source ` +
+          `you copied each link from, correct the id(s), and retry. Do not retry ` +
+          `unchanged. Deliberate examples belong in code formatting (backticks).`,
+      );
+    }
+    if (message.includes("CEREFOX_DELETED")) {
+      // Race backstop: the doc was trashed between our read and the write.
+      throw new Error(
+        `Document ${documentId} was soft-deleted while this edit was in flight. ` +
+          `Restore it first with cerefox_restore_document, then retry.`,
+      );
+    }
+    if (isMissingFunctionError(message, "cerefox_ingest_document")) {
       throw new Error(
         `This server is behind: partial edits need schema 0.11.0 or newer. ` +
           `Run \`cerefox server deploy\`, then retry. (${message})`,

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

@@ -0,0 +1,130 @@
+/**
+ * `cerefox_restore_document` — bring a soft-deleted document back (#210).
+ *
+ * The counterpart to `cerefox_delete_document`, added by maintainer decision
+ * (2026-08-13) reversing the earlier "restore is human-only" posture: every
+ * restore is audited with author attribution, restoring cannot destroy
+ * content, and CLI/MCP parity (`cerefox document restore` existed all along)
+ * beats a boundary the audit surface had already outgrown.
+ *
+ * What still cannot happen from here: **permanent purge**, which remains
+ * web-UI-only — the one action that actually destroys data keeps its
+ * human-in-the-loop confirmation.
+ *
+ * No `expected_content_hash`, matching the CLI contract: a trashed document
+ * cannot be rewritten while in the trash (cerefox_ingest_document refuses
+ * updates to soft-deleted documents as of 0.12.0), so what was reviewed in
+ * the trash is what comes back — there is no read-freshness to prove.
+ */
+
+import type { MCPSupabaseClient } from "./types.ts";
+
+import { isDocumentNotFoundError, isMissingFunctionError, logUsage } from "./_utils.ts";
+import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+
+async function handler(
+  supabase: MCPSupabaseClient,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string> {
+  const document_id = args.document_id as string | undefined;
+  const reason = args.reason as string | undefined;
+
+  if (!document_id) throw new McpInvalidParams("document_id is required");
+
+  const author = (args.author as string | undefined) ?? (args.requestor as string | undefined);
+  // Derived from the transport, never taken from the caller: an agent must not
+  // be able to record itself as a user. Matches the delete handler.
+  const authorType = ctx.accessPath === "cli" ? "user" : "agent";
+
+  const { data, error } = await supabase.rpc("cerefox_restore_document", {
+    p_document_id: document_id,
+    p_author: author ?? "unknown",
+    p_author_type: authorType,
+    p_reason: reason ?? null,
+  });
+
+  if (error) {
+    const message = error.message ?? String(error);
+    if (isMissingFunctionError(message, "cerefox_restore_document")) {
+      throw new Error(
+        `This server is behind: cerefox_restore_document needs schema 0.12.0 or newer. ` +
+          `Run \`cerefox server deploy\`, then retry. (${message})`,
+      );
+    }
+    if (isDocumentNotFoundError(error)) {
+      throw new McpInvalidParams(`Document ${document_id} not found.`);
+    }
+    throw new Error(`RPC error: ${message}`);
+  }
+
+  const row = data as
+    | {
+        document_id?: string;
+        title?: string;
+        total_chars?: number;
+        restored?: boolean;
+        was_deleted?: boolean;
+      }
+    | undefined;
+  if (!row) throw new Error("cerefox_restore_document returned no data");
+
+  if (!row.restored) {
+    // Report what happened, not what was asked for: the document was never in
+    // the trash, nothing changed, no audit entry was written.
+    return (
+      `Document ${document_id} ("${row.title ?? "untitled"}") is NOT deleted — ` +
+      `there is nothing to restore. No change was made.`
+    );
+  }
+
+  logUsage(supabase, {
+    operation: "restore",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor as string | undefined,
+    document_id,
+    result_count: 1,
+  });
+
+  return (
+    `Restored "${row.title ?? "untitled"}" (id: ${document_id}, ` +
+    `${row.total_chars ?? "?"} chars) from the trash. It is searchable again ` +
+    `and the restore is recorded in the audit log.\n` +
+    `Tell your user what you restored and why.`
+  );
+}
+
+export const restoreDocumentTool: ToolDefinition = {
+  name: "cerefox_restore_document",
+  description:
+    "Restore a soft-deleted document from the trash — the inverse of cerefox_delete_document. The document becomes searchable again; the restore is recorded in the audit log with your identity. Restoring a document that is not deleted is a reported no-op. Pass a short reason — like a delete's reason, it is what the human reviewing the audit trail goes on. Permanent purge has no agent surface: once a human purges a document from the web UI, it is gone and cannot be restored.",
+  annotations: {
+    title: "Restore document from trash",
+    readOnlyHint: false,
+    // Recovery only: it can bring content back, never remove it.
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  inputSchema: {
+    type: "object",
+    required: ["document_id"],
+    properties: {
+      document_id: { type: "string", description: "UUID of the soft-deleted document to restore." },
+      reason: {
+        type: "string",
+        description:
+          "Why this document is being restored. Recorded in the audit-log entry. Short and specific beats long.",
+      },
+      author: {
+        type: "string",
+        description: "Who is making this change. Recorded in the audit log.",
+      },
+      requestor: {
+        type: "string",
+        description: "Name of the agent or user making this request. Recorded in the usage log.",
+      },
+    },
+  },
+  handler,
+};

package/dist/server-assets/db/migrations/0024_mcp_delete_document.sql

@@ -0,0 +1,26 @@
+-- 0024_mcp_delete_document.sql — MCP soft-delete parity (#208).
+--
+-- Reworks cerefox_delete_document: optional CAS via p_expected_content_hash
+-- (CEREFOX_CONFLICT / PT409 on mismatch, same pattern as the ingest CAS),
+-- p_reason appended to the audit description, JSONB return instead of VOID,
+-- and idempotent re-delete (original deleted_at preserved, no duplicate audit
+-- entry). No table DDL: the function itself ships in rpcs.sql, which
+-- `cerefox server deploy` re-applies wholesale. This migration exists so the
+-- schema version advances in step, which is what tells an existing deployment
+-- it needs that redeploy.
+--
+-- Schema version 0.11.3 → 0.12.0. Restore moves OUT of the web-UI-only tier
+-- (#210, maintainer decision): both delete and restore are agent-reachable
+-- and audited; permanent purge is now the single web-UI-only action.
+-- cerefox_ingest_document additionally refuses to rewrite a soft-deleted
+-- document (restore first), which is what makes restore safe without a
+-- freshness token.
+
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0024: cerefox_delete_document + cerefox_restore_document '
+        'rework arrives with rpcs.sql on this deploy — CAS on delete, p_reason, '
+        'JSONB returns, honest no-ops. Backs the new cerefox_delete_document '
+        'and cerefox_restore_document MCP tools (#208, #210). Schema 0.12.0.';
+END $$;

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

@@ -0,0 +1,15 @@
+-- 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
+-- production acceptance run 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 $$;