@cerefox/memory 1.7.1 → 1.9.0

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

@@ -598,63 +598,18 @@ AS $$
     GROUP BY d.id, d.title, d.source, d.metadata;
 $$;
 
--- ── cerefox_save_note ─────────────────────────────────────────────────────────
--- Agent write tool: create a minimal document record for a short text note.
--- Embedding and chunking are NOT done server-side in V1 — the Python ingestion
--- pipeline should be used for full ingest.  This RPC is intended for quick
--- one-shot note capture from AI agents that want to store something immediately.
+-- ── retired V1 RPC (dropped in 0.14.0) ──────────────────────────────────────
+-- cerefox_save_note was a Python-era V1 tool with zero callers since the TS
+-- rewrite — nothing in the CLI, MCP tools, Edge Functions, web app, OR the
+-- SQL layer ever called it. The DROP stays here so re-applying rpcs.sql also
+-- cleans long-lived databases (migration 0028 carries the same).
 --
--- Parameters:
---   p_title       : Note title (required)
---   p_content     : Markdown content (required)
---   p_source      : Origin label, e.g. 'agent' (default: 'agent')
---   p_project_id  : Optional project UUID (assigns to a single project)
---   p_metadata    : Optional JSONB metadata (e.g. agent name, session id)
---
--- Returns: the created document row (id, title, created_at)
-
-CREATE OR REPLACE FUNCTION cerefox_save_note(
-    p_title       TEXT,
-    p_content     TEXT,
-    p_source      TEXT    DEFAULT 'agent',
-    p_project_id  UUID    DEFAULT NULL,
-    p_metadata    JSONB   DEFAULT '{}'::JSONB
-)
-RETURNS TABLE (
-    id          UUID,
-    title       TEXT,
-    created_at  TIMESTAMPTZ
-)
-LANGUAGE plpgsql
-SECURITY DEFINER
-SET search_path = public, pg_catalog
-AS $$
-DECLARE
-    v_hash TEXT;
-    v_doc_id UUID;
-    v_created_at TIMESTAMPTZ;
-BEGIN
-    -- Compute content hash to support deduplication on the caller side.
-    v_hash := encode(sha256(p_content::BYTEA), 'hex');
-
-    INSERT INTO cerefox_documents (
-        title, source, content_hash, metadata, chunk_count, total_chars
-    ) VALUES (
-        p_title, p_source, v_hash, p_metadata, 0, length(p_content)
-    )
-    RETURNING cerefox_documents.id, cerefox_documents.created_at
-    INTO v_doc_id, v_created_at;
-
-    -- Assign to project if provided (many-to-many junction).
-    IF p_project_id IS NOT NULL THEN
-        INSERT INTO cerefox_document_projects (document_id, project_id)
-        VALUES (v_doc_id, p_project_id)
-        ON CONFLICT DO NOTHING;
-    END IF;
-
-    RETURN QUERY SELECT v_doc_id, p_title, v_created_at;
-END;
-$$;
+-- cerefox_context_expand (below) looked like the same class but is NOT dead:
+-- cerefox_search_docs calls it for small-to-big retrieval. TS-side grep alone
+-- cannot establish an RPC is unused — SQL functions have SQL callers. It was
+-- briefly slated for removal in this release; the sandbox validation caught
+-- the breakage (42883 from search_docs) before anything shipped.
+DROP FUNCTION IF EXISTS cerefox_save_note(TEXT, TEXT, TEXT, UUID, JSONB);
 
 -- ── cerefox_context_expand ────────────────────────────────────────────────────
 -- Small-to-big retrieval: given a set of chunk IDs from a search result,
@@ -1009,9 +964,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;
 
@@ -1248,7 +1213,7 @@ $$;
 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).
+-- 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,
@@ -1829,9 +1794,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(
@@ -2010,6 +1975,211 @@ AS $$
     ORDER BY p.name;
 $$;
 
+-- ── Project write RPCs (0.14.0, #147/#219) ──────────────────────────────────
+-- Project writes carried no business logic until the audit trail arrived —
+-- then every caller (CLI, web, shared helpers, ingestion pipeline, the ingest
+-- EF) grew its own follow-up cerefox_create_audit_entry call: non-atomic,
+-- warn-on-failure, and empirically forgettable (review round 1 caught two
+-- unwired paths in the release that introduced the convention). Single
+-- Implementation Principle applies the moment a write has a side effect: the
+-- write AND its audit entry live here, in one transaction. Callers are thin.
+
+-- Return shape changed in review round 4 (full row: the web routes were
+-- re-reading the row the RPC had just written). A changed RETURNS TABLE
+-- cannot go through CREATE OR REPLACE — drop first (house pattern).
+DROP FUNCTION IF EXISTS cerefox_create_project(TEXT, TEXT, TEXT, TEXT, TEXT);
+
+CREATE FUNCTION cerefox_create_project(
+    p_name        TEXT,
+    p_description TEXT DEFAULT '',
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user',
+    -- 'error'  → explicit creation (CLI/web): duplicate name raises.
+    -- 'return' → get-or-create (implicit creation during document
+    --            assignment): an existing project is returned untouched and
+    --            NOT audited — only an actual create writes an entry.
+    p_if_exists   TEXT DEFAULT 'error'
+)
+RETURNS TABLE (
+    project_id          UUID,
+    project_name        TEXT,
+    project_description TEXT,
+    created             BOOLEAN,
+    created_at          TIMESTAMPTZ,
+    updated_at          TIMESTAMPTZ
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_row cerefox_projects%ROWTYPE;
+BEGIN
+    IF NULLIF(BTRIM(p_name), '') IS NULL THEN
+        RAISE EXCEPTION 'Project name is required' USING ERRCODE = '22023';
+    END IF;
+    IF p_if_exists NOT IN ('error', 'return') THEN
+        RAISE EXCEPTION 'p_if_exists must be ''error'' or ''return''' USING ERRCODE = '22023';
+    END IF;
+
+    IF p_if_exists = 'return' THEN
+        -- Case-insensitive, matching the name resolution the assignment
+        -- paths have always used. (A case-colliding pair created directly is
+        -- pre-existing behavior: the unique constraint is exact-match; this
+        -- resolver returns the first match.)
+        SELECT p.* INTO v_row
+        FROM cerefox_projects p WHERE lower(p.name) = lower(BTRIM(p_name)) LIMIT 1;
+        IF v_row.id IS NOT NULL THEN
+            RETURN QUERY SELECT v_row.id, v_row.name, v_row.description, FALSE,
+                                v_row.created_at, v_row.updated_at;
+            RETURN;
+        END IF;
+    END IF;
+
+    BEGIN
+        INSERT INTO cerefox_projects (name, description)
+        VALUES (BTRIM(p_name), COALESCE(p_description, ''))
+        RETURNING * INTO v_row;
+    EXCEPTION WHEN unique_violation THEN
+        -- TOCTOU (round 4): a concurrent create won the race between the
+        -- resolve above and this insert. In 'return' mode that is exactly
+        -- the get-or-create contract — hand back the winner, no audit entry
+        -- (this call created nothing). In 'error' mode a duplicate is the
+        -- caller's error, exactly as if there had been no race.
+        IF p_if_exists = 'return' THEN
+            SELECT p.* INTO v_row
+            FROM cerefox_projects p WHERE lower(p.name) = lower(BTRIM(p_name)) LIMIT 1;
+            IF v_row.id IS NOT NULL THEN
+                RETURN QUERY SELECT v_row.id, v_row.name, v_row.description, FALSE,
+                                    v_row.created_at, v_row.updated_at;
+                RETURN;
+            END IF;
+        END IF;
+        RAISE;
+    END;
+
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'project-create',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'Project ''' || v_row.name || ''' created'
+            || CASE WHEN p_if_exists = 'return'
+                    THEN ' implicitly (document assignment)' ELSE '' END
+    );
+    RETURN QUERY SELECT v_row.id, v_row.name, v_row.description, TRUE,
+                        v_row.created_at, v_row.updated_at;
+END;
+$$;
+
+DROP FUNCTION IF EXISTS cerefox_update_project(UUID, TEXT, TEXT, TEXT, TEXT);
+
+CREATE FUNCTION cerefox_update_project(
+    p_project_id  UUID,
+    -- NULL = keep the current value (the #191/#204 "NULL means not provided"
+    -- convention). An explicit empty name is rejected.
+    p_name        TEXT DEFAULT NULL,
+    p_description TEXT DEFAULT NULL,
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user'
+)
+RETURNS TABLE (
+    project_id          UUID,
+    project_name        TEXT,
+    project_description TEXT,
+    created_at          TIMESTAMPTZ,
+    updated_at          TIMESTAMPTZ
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_old  cerefox_projects%ROWTYPE;
+    v_new  cerefox_projects%ROWTYPE;
+    v_changes TEXT[] := '{}';
+BEGIN
+    IF p_name IS NULL AND p_description IS NULL THEN
+        RAISE EXCEPTION 'Nothing to update: pass p_name and/or p_description' USING ERRCODE = '22023';
+    END IF;
+    IF p_name IS NOT NULL AND NULLIF(BTRIM(p_name), '') IS NULL THEN
+        RAISE EXCEPTION 'Project name cannot be empty' USING ERRCODE = '22023';
+    END IF;
+
+    SELECT p.* INTO v_old FROM cerefox_projects p WHERE p.id = p_project_id FOR UPDATE;
+    IF NOT FOUND THEN
+        RAISE EXCEPTION 'Project not found: %', p_project_id USING ERRCODE = '22023';
+    END IF;
+
+    UPDATE cerefox_projects SET
+        name        = COALESCE(BTRIM(p_name), name),
+        description = COALESCE(p_description, description),
+        updated_at  = NOW()
+    WHERE id = p_project_id
+    RETURNING * INTO v_new;
+
+    -- The trail records what actually changed, not which arguments arrived.
+    IF v_new.name <> v_old.name THEN
+        v_changes := v_changes || ('renamed ''' || v_old.name || ''' → ''' || v_new.name || '''');
+    END IF;
+    IF COALESCE(v_new.description, '') <> COALESCE(v_old.description, '') THEN
+        v_changes := v_changes || 'description changed';
+    END IF;
+
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'project-edit',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'Project ''' || v_new.name || ''' edited ('
+            || COALESCE(NULLIF(array_to_string(v_changes, '; '), ''), 'no-op') || ')'
+    );
+    RETURN QUERY SELECT v_new.id, v_new.name, v_new.description,
+                        v_new.created_at, v_new.updated_at;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION cerefox_delete_project(
+    p_project_id  UUID,
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user'
+)
+RETURNS TABLE (deleted BOOLEAN, project_name TEXT)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_name  TEXT;
+    v_links INT;
+BEGIN
+    -- Lock + read name and link count in one pass: the memberships CASCADE
+    -- with the row, so the count must be read pre-DELETE — but the zero-row
+    -- path (repeat delete) pays for nothing (round 4).
+    SELECT p.name, (SELECT COUNT(*) FROM cerefox_document_projects dp
+                    WHERE dp.project_id = p.id)
+    INTO v_name, v_links
+    FROM cerefox_projects p WHERE p.id = p_project_id FOR UPDATE;
+
+    IF v_name IS NULL THEN
+        -- Zero rows: nothing happened, so nothing is audited — the trail
+        -- must never assert an event that did not occur. Callers decide
+        -- whether "already gone" is an error (CLI) or a 404 (web).
+        RETURN QUERY SELECT FALSE, NULL::TEXT;
+        RETURN;
+    END IF;
+
+    DELETE FROM cerefox_projects WHERE id = p_project_id;
+
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'project-delete',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'Project ''' || v_name || ''' deleted ('
+            || v_links || ' document link(s) removed)'
+    );
+    RETURN QUERY SELECT TRUE, v_name;
+END;
+$$;
+
 -- ── cerefox_metadata_search ──────────────────────────────────────────────────
 -- Query documents by metadata key-value criteria without a text search term.
 -- Uses JSONB containment (@>) which leverages the existing GIN index on
@@ -2432,7 +2602,23 @@ BEGIN
 END;
 $$;
 
-CREATE OR REPLACE FUNCTION cerefox_set_config(p_key TEXT, p_value TEXT)
+-- The 2-arg signature grew to 4 in 0.14.0 (audit trail). CREATE OR REPLACE
+-- never removes the old overload, and a surviving one makes named calls
+-- ambiguous under PostgREST (PGRST203) — the v1.7.0 purge/restore lesson.
+-- Both signatures dropped (house pattern, cf. delete_document): the old one
+-- so it cannot linger, the current one so re-applying this file stays
+-- idempotent after migration 0028 has already created it.
+DROP FUNCTION IF EXISTS cerefox_set_config(TEXT, TEXT);
+DROP FUNCTION IF EXISTS cerefox_set_config(TEXT, TEXT, TEXT, TEXT);
+
+CREATE FUNCTION cerefox_set_config(
+    p_key         TEXT,
+    p_value       TEXT,
+    -- 0.14.0: config changes are governance decisions ("who turned retention
+    -- off, and when?") and belong in the audit trail like any other write.
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user'
+)
 RETURNS VOID
 LANGUAGE plpgsql
 SECURITY DEFINER
@@ -2457,14 +2643,30 @@ DECLARE
         -- point. A signal in the write's response, never a refusal.
         'document_size_warning_chars'
     ];
+    v_old TEXT;
 BEGIN
     IF NOT (p_key = ANY(v_allowed)) THEN
         RAISE EXCEPTION 'Unknown config key: %. Allowed keys: %', p_key, v_allowed;
     END IF;
 
+    SELECT value INTO v_old FROM cerefox_config WHERE key = p_key;
+
     INSERT INTO cerefox_config (key, value)
     VALUES (p_key, p_value)
     ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value;
+
+    -- Same-transaction audit entry (document_id NULL — a store-level write).
+    -- A no-op set (same value) is still recorded: "checked and confirmed" is
+    -- itself a governance action, and skipping it would make the trail lie by
+    -- omission when someone re-asserts a setting.
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'config-change',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'config: ' || p_key || ': '
+            || COALESCE('''' || v_old || '''', '(unset)')
+            || ' → ''' || p_value || ''''
+    );
 END;
 $$;
 
@@ -2788,6 +2990,10 @@ 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).
@@ -2806,7 +3012,7 @@ 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.2'::TEXT;
+    SELECT '0.14.0'::TEXT;
 $$;
 
 -- ── cerefox_find_dead_links ──────────────────────────────────────────────────

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.2
+-- @version: 0.14.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 —
@@ -140,7 +140,13 @@ CREATE TABLE IF NOT EXISTS cerefox_audit_log (
                       'insert', 'replace-section', 'delete-section',
                       -- iteration 35 (#197): renaming a heading is neither a
                       -- rewrite nor a removal, and the trail should say so.
-                      'rename-section')
+                      'rename-section',
+                      -- 0.14.0 (iteration 38, #147): store-level writes join the
+                      -- trail. These entries carry document_id NULL — like the
+                      -- rows a purge cascade orphans, so every reader already
+                      -- tolerates them.
+                      'config-change', 'project-create', 'project-edit',
+                      'project-delete')
     ),
     CONSTRAINT cerefox_audit_log_author_type_check CHECK (author_type IN ('user', 'agent'))
 );
@@ -212,8 +218,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/dist/server-assets/supabase/functions/cerefox-ingest/index.ts

@@ -3,6 +3,10 @@ import { createClient } from "jsr:@supabase/supabase-js@2";
 import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/index.ts";
 import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
+import {
+  ensureDocumentInProject,
+  setDocumentProjectsByName,
+} from "../../../_shared/mcp-tools/_projects.ts";
 import {
   chunkMarkdown,
   embeddingInputFor,
@@ -220,97 +224,10 @@ async function sha256hex(text: string): Promise<string> {
 //
 // Used by both update branches AND the create path so resolution is consistent.
 
-// deno-lint-ignore no-explicit-any
-async function ensureDocumentInProject(
-  // deno-lint-ignore no-explicit-any
-  supabase: any,
-  documentId: string,
-  projectName: string,
-): Promise<string | null> {
-  // Resolve project name → id (look up; create if absent).
-  let projectId: string | null = null;
-  const { data: proj } = await supabase
-    .from("cerefox_projects")
-    .select("id")
-    .ilike("name", projectName)
-    .limit(1);
-  if (proj?.length) {
-    projectId = proj[0].id;
-  } else {
-    const { data: newProj } = await supabase
-      .from("cerefox_projects")
-      .insert({ name: projectName })
-      .select("id");
-    projectId = newProj?.[0]?.id ?? null;
-  }
-  if (!projectId) return null;
-
-  // Check membership; INSERT only if missing. PRIMARY KEY (document_id, project_id)
-  // guarantees uniqueness, so this is safe under concurrent calls (worst case:
-  // one of two concurrent inserts fails with 23505 unique_violation — we log
-  // and treat as "already a member"; outcome is identical).
-  const { data: existing } = await supabase
-    .from("cerefox_document_projects")
-    .select("document_id")
-    .eq("document_id", documentId)
-    .eq("project_id", projectId)
-    .limit(1);
-  if (existing?.length) return projectId;  // Already a member — non-destructive
-
-  const { error: insertErr } = await supabase
-    .from("cerefox_document_projects")
-    .insert({ document_id: documentId, project_id: projectId });
-  if (insertErr && !String(insertErr.message ?? "").includes("duplicate key")) {
-    console.warn("ensureDocumentInProject: insert failed", insertErr);
-  }
-  return projectId;
-}
-
-// ── Destructive set-the-full-list helper (project_names list form) ─────────
-//
-// Resolves each name to a project_id (creating if absent), then REPLACES the
-// document's project memberships with exactly that set. Used by the
-// project_names: string[] form on cerefox_ingest (full-set semantics).
-//
-// Empty list = remove from all projects.
-
-// deno-lint-ignore no-explicit-any
-async function setDocumentProjectsByName(
-  // deno-lint-ignore no-explicit-any
-  supabase: any,
-  documentId: string,
-  projectNames: string[],
-): Promise<string[]> {
-  const projectIds: string[] = [];
-  for (const name of projectNames) {
-    if (!name) continue;
-    const { data: proj } = await supabase
-      .from("cerefox_projects")
-      .select("id")
-      .ilike("name", name)
-      .limit(1);
-    if (proj?.length) {
-      projectIds.push(proj[0].id);
-    } else {
-      const { data: newProj } = await supabase
-        .from("cerefox_projects")
-        .insert({ name })
-        .select("id");
-      if (newProj?.[0]?.id) projectIds.push(newProj[0].id);
-    }
-  }
-
-  // DELETE-then-INSERT replace (matches Python assign_document_projects).
-  await supabase
-    .from("cerefox_document_projects")
-    .delete()
-    .eq("document_id", documentId);
-  if (projectIds.length > 0) {
-    const rows = projectIds.map((pid) => ({ document_id: documentId, project_id: pid }));
-    await supabase.from("cerefox_document_projects").insert(rows);
-  }
-  return projectIds;
-}
+// Project resolution + membership helpers are the SHARED implementations
+// (_shared/mcp-tools/_projects.ts) — the EF carried textual clones until
+// v1.9.0, which is exactly how forks drift (round-3 review). Both route
+// project creation through cerefox_create_project (audits in-transaction).
 
 // ── Main handler ───────────────────────────────────────────────────────────
 
@@ -535,9 +452,9 @@ Deno.serve(async (req: Request) => {
     // - project_names (list) → destructive replace (full-set semantics)
     // - project_name (singular) → non-destructive add (only if project_names absent)
     if (project_names !== null) {
-      await setDocumentProjectsByName(supabase, existingDoc.id, project_names);
+      await setDocumentProjectsByName(supabase, existingDoc.id, project_names, { author, authorType: author_type });
     } else if (project_name) {
-      await ensureDocumentInProject(supabase, existingDoc.id, project_name);
+      await ensureDocumentInProject(supabase, existingDoc.id, project_name, { author, authorType: author_type });
     }
 
     const note = update_if_exists ? undefined : "update_if_exists flag was overridden by document_id";
@@ -658,9 +575,9 @@ Deno.serve(async (req: Request) => {
       // - project_names (list) → destructive replace (full-set semantics)
       // - project_name (singular) → non-destructive add (only if project_names absent)
       if (project_names !== null) {
-        await setDocumentProjectsByName(supabase, existingDoc.id, project_names);
+        await setDocumentProjectsByName(supabase, existingDoc.id, project_names, { author, authorType: author_type });
       } else if (project_name) {
-        await ensureDocumentInProject(supabase, existingDoc.id, project_name);
+        await ensureDocumentInProject(supabase, existingDoc.id, project_name, { author, authorType: author_type });
       }
 
       return new Response(
@@ -759,9 +676,9 @@ Deno.serve(async (req: Request) => {
   // - project_name (singular) → assign one via the non-destructive helper
   let projectId: string | null = null;
   if (project_names !== null && project_names.length > 0) {
-    await setDocumentProjectsByName(supabase, documentId, project_names);
+    await setDocumentProjectsByName(supabase, documentId, project_names, { author, authorType: author_type });
   } else if (project_name) {
-    projectId = await ensureDocumentInProject(supabase, documentId, project_name);
+    projectId = await ensureDocumentInProject(supabase, documentId, project_name, { author, authorType: author_type });
   }
 
   // Fire-and-forget usage logging for ingest

package/docs/guides/cli.md

@@ -453,6 +453,8 @@ cerefox project delete [OPTIONS] PROJECT
 | `--description TEXT` | str | _none_ | Project description (`create` / `edit`). |
 | `--name TEXT` | str | _unchanged_ | New name (`edit`). |
 | `-y, --yes` | flag | off | Skip confirmation (`delete`; required for non-interactive use). |
+| `-a, --author TEXT` | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log (v1.9.0 — project writes are audited in-transaction by the server). |
+| `--author-type TEXT` | user\|agent | `user` | Recorded alongside the author. |
 
 **Examples**:
 ```bash
@@ -461,6 +463,10 @@ cerefox project edit research --name research-archive
 cerefox project delete research-archive --yes
 ```
 
+Since v1.9.0 every project mutation is recorded in the audit log by the
+server itself (`project-create` / `project-edit` / `project-delete`), with
+the audit entry written in the same transaction as the change.
+
 ---
 
 ### `cerefox metadata keys`
@@ -519,7 +525,7 @@ cerefox audit list [OPTIONS]
 |---|---|---|---|
 | `--document-id TEXT` | UUID | _none_ | Filter to a single document. |
 | `--author TEXT` | str | _none_ | Filter by author name (exact match). |
-| `--operation [create\|update-content\|update-metadata\|delete\|status-change\|archive\|unarchive\|restore]` | choice | _none_ | Filter by operation type. |
+| `--operation TEXT` | choice | _none_ | Filter by operation type: `create`, `update-content`, `update-metadata`, `insert`, `replace-section`, `delete-section`, `rename-section`, `delete`, `restore`, `status-change`, `archive`, `unarchive`, `config-change`, `project-create`, `project-edit`, `project-delete`. |
 | `--since TEXT` | ISO-8601 | _none_ | Lower bound on `created_at`. |
 | `--until TEXT` | ISO-8601 | _none_ | Upper bound on `created_at`. |
 | `--limit INTEGER` | int | `50` | Max rows. |
@@ -698,9 +704,14 @@ Agents see 15 tools with the flag off and 19 with it on. See
 ```
 cerefox config list           # all current key/value pairs
 cerefox config get KEY
-cerefox config set KEY VALUE
+cerefox config set KEY VALUE [--author NAME] [--author-type user|agent]
 ```
 
+Since v1.9.0 every `config set` is recorded in the audit log by the server
+itself (`config-change`, with the old → new value), in the same transaction
+as the write — pass `--author` (or set `CEREFOX_AUTHOR_NAME`) so the entry
+is attributed; it records `unknown` otherwise, with a warning.
+
 Used for toggling features at runtime without a redeploy — see the "Decision Log Q1 Part 2 — usage tracking opt-in" entry (stored in the Cerefox knowledge base).
 
 ---