@cerefox/memory 1.12.1 → 1.13.1

package/dist/server-assets/_shared/mcp-tools/list-versions.ts

@@ -8,6 +8,7 @@ import type { MCPSupabaseClient } from "./types.ts";
 
 import { logUsage } from "./_utils.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
 
 /**
  * Version timestamps carried only a DATE (`slice(0, 10)`), which is
@@ -46,7 +47,7 @@ async function handler(
   logUsage(supabase, {
     operation: "list_versions",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: callerIdentity(args),
     document_id,
     result_count: versions.length,
   });
@@ -79,11 +80,7 @@ export const listVersionsTool: ToolDefinition = {
         type: "string",
         description: "UUID of the document whose version history to list",
       },
-      requestor: {
-        type: "string",
-        description:
-          'Name of the agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent" if not provided. May be enforced via server config.',
-      },
+      author: AUTHOR_PARAM_READ,
     },
   },
   handler,

package/dist/server-assets/_shared/mcp-tools/metadata-search.ts

@@ -9,7 +9,9 @@ import type { MCPSupabaseClient } from "./types.ts";
 
 import { applyByteBudget, getMaxResponseBytes, logUsage } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
+import { reviewWorkflowEnabled } from "./feature-flags.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
 
 async function handler(
   supabase: MCPSupabaseClient,
@@ -85,7 +87,7 @@ async function handler(
   logUsage(supabase, {
     operation: "metadata_search",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: callerIdentity(args),
     query_text: JSON.stringify(metadata_filter ?? {}),
     project_id: projectId,
     result_count: rows.length,
@@ -93,6 +95,10 @@ async function handler(
 
   if (rows.length === 0) return "No documents match the given criteria.";
 
+  // The review status is a column of a feature that may be off (#241); when
+  // it is, an agent should not see "approved" and wonder what it means.
+  const showReview = await reviewWorkflowEnabled(supabase);
+
   // Note: when include_content is true the RPC already respects p_max_bytes
   // server-side. The applyByteBudget helper is retained here only for
   // parity with the EF implementation and as a defensive trim — see the
@@ -109,7 +115,7 @@ async function handler(
     const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
     const header =
       `## ${row.title} [id: ${row.document_id}]\n` +
-      `${meta}${projects} | ${row.total_chars} chars | ${row.review_status} | updated ${row.updated_at?.slice(0, 10) ?? "?"}${hash}`;
+      `${meta}${projects} | ${row.total_chars} chars | ${showReview ? `${row.review_status} | ` : ""}updated ${row.updated_at?.slice(0, 10) ?? "?"}${hash}`;
 
     if (include_content && row.content) {
       return `${header}\n\n${row.content}`;
@@ -159,11 +165,7 @@ export const metadataSearchTool: ToolDefinition = {
         description:
           "Soft cap on total response bytes when include_content is true. Defaults to server maximum (200000).",
       },
-      requestor: {
-        type: "string",
-        description:
-          'Name of the agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent" if not provided. May be enforced via server config.',
-      },
+      author: AUTHOR_PARAM_READ,
     },
   },
   handler,

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

@@ -38,6 +38,7 @@ import {
 import { activeEmbedderName, embedBatch, resolveEmbedderKind } from "../embeddings/index.ts";
 import { extractConflictHashes, isMissingFunctionError, logUsage } from "./_utils.ts";
 import { McpInvalidParams, type MCPSupabaseClient, type ToolContext, type ToolDefinition } from "./types.ts";
+import { AUTHOR_PARAM_WRITE, DEFAULT_IDENTITY, callerIdentity } from "./identity.ts";
 
 /**
  * Who to record as the author. Derived from the access path rather than taken
@@ -307,8 +308,8 @@ async function applyAndWrite(
     p_source: null,
     p_content_hash: newHash,
     p_metadata: null, // null = keep existing metadata
-    // Agent writes land in review; a human at the CLI is the reviewer.
-    p_review_status: authorType === "agent" ? "pending_review" : "approved",
+    // review_status: decided by the RPC from p_author_type + the store's
+    // review_workflow_enabled flag (#241), not here.
     p_chunks: chunkData,
     p_author: requestor,
     // Who actually made the write, not which module executed it. The CLI is a
@@ -440,7 +441,7 @@ async function insertHandler(
     documentId,
     operations,
     expectedHash,
-    requestor: (args.requestor as string | undefined) ?? defaultRequestor(ctx),
+    requestor: callerIdentity(args) ?? defaultRequestor(ctx),
     toolLabel: "insert",
     authorType: resolveAuthorType(ctx, args),
   });
@@ -493,10 +494,7 @@ export const insertTool: ToolDefinition = {
         description:
           "content_hash of the version you are basing this on. Required — no last-write-wins.",
       },
-      requestor: {
-        type: "string",
-        description: 'Agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent".',
-      },
+      author: AUTHOR_PARAM_WRITE,
       author_type: {
         type: "string",
         enum: ["user", "agent"],
@@ -538,7 +536,7 @@ async function editHandler(
     documentId,
     operations,
     expectedHash,
-    requestor: (args.requestor as string | undefined) ?? defaultRequestor(ctx),
+    requestor: callerIdentity(args) ?? defaultRequestor(ctx),
     toolLabel: "edit",
     authorType: resolveAuthorType(ctx, args),
   });
@@ -618,10 +616,7 @@ export const editTool: ToolDefinition = {
         description:
           "content_hash of the version you are basing these edits on. Required — no last-write-wins.",
       },
-      requestor: {
-        type: "string",
-        description: 'Agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent".',
-      },
+      author: AUTHOR_PARAM_WRITE,
       author_type: {
         type: "string",
         enum: ["user", "agent"],

package/dist/server-assets/_shared/mcp-tools/relations.ts

@@ -15,6 +15,7 @@
 import { logUsage } from "./_utils.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 import type { MCPSupabaseClient } from "./types.ts";
+import { AUTHOR_PARAM_READ, AUTHOR_PARAM_WRITE, DEFAULT_IDENTITY, callerIdentity } from "./identity.ts";
 
 /** Relation types that carry behaviour; any other string is accepted too. */
 const KNOWN_TYPES =
@@ -44,7 +45,7 @@ async function setHandler(
     p_source_id: source,
     p_target_id: target,
     p_rel_type: relType,
-    p_author: (args.author as string | undefined) ?? "mcp-agent",
+    p_author: callerIdentity(args) ?? DEFAULT_IDENTITY,
     p_author_type: "agent",
     p_metadata: (args.metadata as Record<string, unknown> | undefined) ?? {},
   });
@@ -57,7 +58,7 @@ async function setHandler(
   logUsage(supabase, {
     operation: "set_relation",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: callerIdentity(args),
     document_id: source,
   });
 
@@ -103,8 +104,7 @@ export const setRelationTool: ToolDefinition = {
         type: "object",
         description: "Optional JSON context for the edge (note, confidence, …)",
       },
-      author: { type: "string", description: "Who is creating this relation" },
-      requestor: { type: "string", description: "Name of the agent making this request" },
+      author: AUTHOR_PARAM_WRITE,
     },
   },
   handler: setHandler,
@@ -126,7 +126,7 @@ async function deleteHandler(
     p_source_id: source,
     p_target_id: target,
     p_rel_type: relType,
-    p_author: (args.author as string | undefined) ?? "mcp-agent",
+    p_author: callerIdentity(args) ?? DEFAULT_IDENTITY,
     p_author_type: "agent",
   });
   if (error) throw new Error(`RPC error: ${error.message}`);
@@ -135,7 +135,7 @@ async function deleteHandler(
   logUsage(supabase, {
     operation: "delete_relation",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: callerIdentity(args),
     document_id: source,
   });
 
@@ -166,8 +166,7 @@ export const deleteRelationTool: ToolDefinition = {
       source_id: { type: "string", description: "UUID of the source document" },
       target_id: { type: "string", description: "UUID of the target document" },
       rel_type: { type: "string", description: "Relation type to remove" },
-      author: { type: "string", description: "Who is removing this relation" },
-      requestor: { type: "string", description: "Name of the agent making this request" },
+      author: AUTHOR_PARAM_WRITE,
     },
   },
   handler: deleteHandler,
@@ -197,7 +196,7 @@ async function getRelationsHandler(
   logUsage(supabase, {
     operation: "get_relations",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: callerIdentity(args),
     document_id: docId,
     result_count: rows.length,
   });
@@ -231,7 +230,7 @@ export const getRelationsTool: ToolDefinition = {
     required: ["document_id"],
     properties: {
       document_id: { type: "string", description: "UUID of the document" },
-      requestor: { type: "string", description: "Name of the agent making this request" },
+      author: AUTHOR_PARAM_READ,
     },
   },
   handler: getRelationsHandler,
@@ -268,7 +267,7 @@ async function getNeighborsHandler(
   logUsage(supabase, {
     operation: "get_neighbors",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: callerIdentity(args),
     document_id: docId,
     result_count: rows.length,
   });
@@ -307,7 +306,7 @@ export const getNeighborsTool: ToolDefinition = {
       from_time: { type: "string", description: "ISO-8601: only neighbours created on/after" },
       to_time: { type: "string", description: "ISO-8601: only neighbours created on/before" },
       limit: { type: "integer", description: "Max documents to return (default 50, max 200)" },
-      requestor: { type: "string", description: "Name of the agent making this request" },
+      author: AUTHOR_PARAM_READ,
     },
   },
   handler: getNeighborsHandler,

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

@@ -21,6 +21,7 @@ import type { MCPSupabaseClient } from "./types.ts";
 
 import { isDocumentNotFoundError, isMissingFunctionError, logUsage } from "./_utils.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+import { AUTHOR_PARAM_WRITE, DEFAULT_IDENTITY, callerIdentity } from "./identity.ts";
 
 async function handler(
   supabase: MCPSupabaseClient,
@@ -32,7 +33,7 @@ async function handler(
 
   if (!document_id) throw new McpInvalidParams("document_id is required");
 
-  const author = (args.author as string | undefined) ?? (args.requestor as string | undefined);
+  const author = callerIdentity(args);
   // 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";
@@ -81,7 +82,7 @@ async function handler(
   logUsage(supabase, {
     operation: "restore",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: author,
     document_id,
     result_count: 1,
   });
@@ -116,14 +117,7 @@ export const restoreDocumentTool: ToolDefinition = {
         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.",
-      },
+      author: AUTHOR_PARAM_WRITE,
     },
   },
   handler,

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -22,6 +22,7 @@ import { applyByteBudget, getConfiguredMinSearchScore, getConfiguredSearchAlpha,
   getMaxResponseBytes, getMinTermCoverage, logUsage } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
 
 async function handler(
   supabase: MCPSupabaseClient,
@@ -135,7 +136,7 @@ async function handler(
   logUsage(supabase, {
     operation: "search",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: callerIdentity(args),
     query_text: query,
     project_id: projectId,
     result_count: accepted.length,
@@ -244,11 +245,7 @@ export const searchTool: ToolDefinition = {
         description:
           "Optional response size budget in bytes. Results are dropped whole until the budget is satisfied; a truncated flag is set when results are dropped. Defaults to the server maximum (200000). Pass a smaller value if your context window is limited. Values above the server maximum are silently capped.",
       },
-      requestor: {
-        type: "string",
-        description:
-          'Name of the agent or user making this request (e.g., "Claude Code", "archiver"). Recorded in the usage log for attribution. Defaults to "mcp-agent" if not provided. May be enforced via server config.',
-      },
+      author: AUTHOR_PARAM_READ,
     },
   },
   handler,

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

@@ -21,6 +21,7 @@ import type { MCPSupabaseClient } from "./types.ts";
 
 import { logUsage } from "./_utils.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+import { AUTHOR_PARAM_WRITE, DEFAULT_IDENTITY, callerIdentity } from "./identity.ts";
 
 async function handler(
   supabase: MCPSupabaseClient,
@@ -48,7 +49,7 @@ async function handler(
     );
   }
 
-  const author = (args.author as string | undefined) ?? (args.requestor as string | undefined);
+  const author = callerIdentity(args);
   // Derived from the transport, never taken from the caller: an agent must not
   // be able to record itself as a user. Matches the partial-edit handlers.
   const authorType = ctx.accessPath === "cli" ? "user" : "agent";
@@ -71,7 +72,7 @@ async function handler(
   logUsage(supabase, {
     operation: "update_metadata",
     accessPath: ctx.accessPath,
-    requestor: args.requestor as string | undefined,
+    requestor: author,
     document_id,
     result_count: 1,
   });
@@ -119,14 +120,7 @@ export const setDocumentMetadataTool: ToolDefinition = {
         description:
           "Set the metadata to EXACTLY this object, discarding any key not listed. Defaults to false (merge). Use only when you mean to reset a document's tags wholesale.",
       },
-      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.",
-      },
+      author: AUTHOR_PARAM_WRITE,
     },
   },
   handler,

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

@@ -13,6 +13,7 @@ import type { MCPSupabaseClient } from "./types.ts";
 
 import { replaceDocumentProjects } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+import { AUTHOR_PARAM_WRITE, DEFAULT_IDENTITY, callerIdentity } from "./identity.ts";
 
 async function handler(
   supabase: MCPSupabaseClient,
@@ -21,7 +22,7 @@ async function handler(
 ): Promise<string> {
   const document_id = (args.document_id as string | undefined)?.trim();
   const project_names_raw = args.project_names;
-  const author = (args.author as string | undefined) ?? "mcp-agent";
+  const author = callerIdentity(args) ?? DEFAULT_IDENTITY;
 
   if (!document_id) {
     throw new McpInvalidParams(
@@ -96,11 +97,7 @@ export const setDocumentProjectsTool: ToolDefinition = {
         description:
           "Explicit list of project names. Each created if absent. Order is preserved. Empty list = remove from all projects.",
       },
-      author: {
-        type: "string",
-        description:
-          'Agent or tool name recorded in the audit log. Defaults to "mcp-agent". May be enforced via server config.',
-      },
+      author: AUTHOR_PARAM_WRITE,
     },
   },
   handler,

package/dist/server-assets/db/migrations/0031_review_workflow_toggle.sql

@@ -0,0 +1,74 @@
+-- 0031_review_workflow_toggle.sql — make the review workflow optional (#241,
+-- schema 0.16.0, iteration 44).
+--
+-- New config key `review_workflow_enabled`. Fresh installs get 'false' from
+-- schema.sql; this migration runs only on stores that predate the flag and
+-- seeds 'true' there, so upgrading never changes what a store does. Neither
+-- write ever overrides a value an operator has set (ON CONFLICT DO NOTHING).
+--
+-- The decision "agent write → pending_review" moves out of the six client call
+-- sites and into cerefox_ingest_document. That RPC lives in rpcs.sql, which
+-- `cerefox server deploy` re-applies. (0.16.0 also had the RPC read this flag
+-- on write and store 'approved' for everyone while off; 0.16.1 removed that —
+-- the flag governs visibility only, the stored value follows author_type.)
+--
+-- #240: cerefox_hybrid_search / cerefox_search_docs gain p_review_status so a
+-- filtered search is applied before the limit, not after. A new argument is a
+-- new overload; the old ones must go or PostgREST calls become ambiguous
+-- (PGRST203). Same DROPs sit at the top of rpcs.sql for the fresh path.
+--
+-- Idempotent: safe to re-run.
+
+INSERT INTO cerefox_config (key, value)
+VALUES ('review_workflow_enabled', 'true')
+ON CONFLICT (key) DO NOTHING;
+
+DROP FUNCTION IF EXISTS cerefox_hybrid_search(TEXT, VECTOR(768), INT, FLOAT, BOOLEAN, UUID, FLOAT, JSONB, FLOAT);
+DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID, FLOAT, INT, INT, JSONB, FLOAT);
+
+-- The allow-list in cerefox_set_config grows by one key. Same signature, so
+-- OR REPLACE is enough (no overload to drop). Carried here as well as in
+-- rpcs.sql so `db_migrate` alone leaves the key settable; the unit test
+-- `rpc-guard-invariants` pins the two lists to each other.
+CREATE OR REPLACE FUNCTION cerefox_set_config(
+    p_key         TEXT,
+    p_value       TEXT,
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user'
+)
+RETURNS VOID
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_allowed TEXT[] := ARRAY[
+        'usage_tracking_enabled', 'require_requestor_identity', 'requestor_identity_format',
+        'min_search_score', 'min_term_coverage', 'search_alpha',
+        'version_retention_hours', 'version_cleanup_enabled',
+        'relations_enabled',
+        'review_workflow_enabled',
+        '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;
+
+    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;
+$$;

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

@@ -76,6 +76,11 @@ DROP FUNCTION IF EXISTS cerefox_hybrid_search(TEXT, VECTOR(768), INT, FLOAT, BOO
 DROP FUNCTION IF EXISTS cerefox_fts_search(TEXT, INT, UUID, JSONB);
 DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID, FLOAT, INT, INT, JSONB);
 
+-- Iteration 44 (0.16.0, #240): p_review_status added to the two search RPCs
+-- so a review-status filter applies before the limit. Old overloads out.
+DROP FUNCTION IF EXISTS cerefox_hybrid_search(TEXT, VECTOR(768), INT, FLOAT, BOOLEAN, UUID, FLOAT, JSONB, FLOAT);
+DROP FUNCTION IF EXISTS cerefox_search_docs(TEXT, VECTOR(768), INT, FLOAT, UUID, FLOAT, INT, INT, JSONB, FLOAT);
+
 -- ── Shared return type note ────────────────────────────────────────────────────
 -- All chunk-level search RPCs return the same shape for consistency:
 --   chunk_id, document_id, chunk_index, title, content, heading_path,
@@ -113,7 +118,11 @@ CREATE OR REPLACE FUNCTION cerefox_hybrid_search(
     -- meant 100% of terms — the pass this gate generalizes. Chunks below the
     -- bar can still pass via the vector threshold, else they are
     -- below-confidence material. 0 restores the pre-gate OR behavior.
-    p_min_term_coverage FLOAT DEFAULT NULL
+    p_min_term_coverage FLOAT DEFAULT NULL,
+    -- #240: 'approved' | 'pending_review' restricts the candidate pool BEFORE
+    -- the limit, so a filtered page is a full page. NULL = no filter. Applied
+    -- here, in the CTEs, rather than by the caller on the returned page.
+    p_review_status   TEXT    DEFAULT NULL
 )
 RETURNS TABLE (
     chunk_id        UUID,
@@ -204,6 +213,7 @@ BEGIN
                       WHERE dp.document_id = d.id AND dp.project_id = p_project_id
                   ))
               AND (p_metadata_filter IS NULL OR d.metadata @> p_metadata_filter)
+              AND (p_review_status IS NULL OR d.review_status = p_review_status)
         ) INTO and_matches;
     END IF;
 
@@ -239,6 +249,7 @@ BEGIN
                       WHERE dp.document_id = d.id AND dp.project_id = p_project_id
                   ))
               AND (p_metadata_filter IS NULL OR d.metadata @> p_metadata_filter)
+              AND (p_review_status IS NULL OR d.review_status = p_review_status)
             ORDER BY fts_score DESC
             LIMIT candidate_count
         ),
@@ -260,6 +271,7 @@ BEGIN
                       WHERE dp.document_id = d.id AND dp.project_id = p_project_id
                   ))
               AND (p_metadata_filter IS NULL OR d.metadata @> p_metadata_filter)
+              AND (p_review_status IS NULL OR d.review_status = p_review_status)
             ORDER BY
                 CASE
                     WHEN p_use_upgrade AND c.embedding_upgrade IS NOT NULL
@@ -724,7 +736,9 @@ CREATE OR REPLACE FUNCTION cerefox_search_docs(
     p_metadata_filter        JSONB DEFAULT NULL,
     -- NULL flows through to cerefox_hybrid_search, which resolves the
     -- caller > cerefox_config > built-in chain in one place (#133).
-    p_min_term_coverage      FLOAT DEFAULT NULL
+    p_min_term_coverage      FLOAT DEFAULT NULL,
+    -- #240: optional review-status filter, applied inside cerefox_hybrid_search.
+    p_review_status          TEXT  DEFAULT NULL
 )
 RETURNS TABLE (
     document_id              UUID,
@@ -765,7 +779,8 @@ AS $$
             p_project_id      := p_project_id,
             p_min_score       := p_min_score,
             p_metadata_filter := p_metadata_filter,
-            p_min_term_coverage := p_min_term_coverage
+            p_min_term_coverage := p_min_term_coverage,
+            p_review_status   := p_review_status
         )
     ),
     best_per_doc AS (
@@ -1379,7 +1394,12 @@ $$;
 --   p_metadata        : JSONB metadata. NULL = "not provided" → create uses '{}',
 --                       update keeps the existing metadata (v0.11.1). Pass '{}'
 --                       explicitly to clear all metadata.
---   p_review_status   : 'approved' or 'pending_review' (based on author_type)
+--   p_review_status   : ACCEPTED AND IGNORED since 0.16.0 (#241). The status is
+--                       decided here from p_author_type alone (agent →
+--                       pending_review, user → approved), so every transport
+--                       behaves the same. The `review_workflow_enabled` flag
+--                       only governs what surfaces show (0.16.1).
+--                       Kept in the signature so no caller breaks.
 --   p_chunks          : JSONB array of chunk objects, each with:
 --                        chunk_index, heading_path, heading_level, title,
 --                        content, char_count, embedding (float[]), embedder (text)
@@ -1564,9 +1584,20 @@ BEGIN
             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;
+    -- Review status is decided HERE, not by the caller (#241), from the
+    -- author type alone: an agent write is 'pending_review', a person's is
+    -- 'approved'. The `review_workflow_enabled` flag is deliberately NOT
+    -- consulted (0.16.1): it governs what the surfaces show and enforce, not
+    -- what is stored, so a store that turns the workflow off and later back on
+    -- sees exactly the statuses it would have had all along. 0.16.0 wrote
+    -- 'approved' for every author while the flag was off; that made a stored
+    -- 'approved' mean two different things depending on when it was written.
+    -- p_review_status is not consulted either — six clients used to compute
+    -- it and they could not have agreed on a store-level policy.
+    v_status := CASE
+                    WHEN p_author_type = 'agent' THEN 'pending_review'
+                    ELSE 'approved'
+                END;
 
     -- Count chunks and total chars from the input
     v_chunk_count := jsonb_array_length(p_chunks);
@@ -2704,6 +2735,9 @@ DECLARE
         'version_retention_hours', 'version_cleanup_enabled',
         -- Optional features, off by default (iteration 29).
         'relations_enabled',
+        -- #241: the review workflow. Off on fresh installs, on for stores that
+        -- predate the flag. Read by cerefox_ingest_document on every write.
+        'review_workflow_enabled',
         -- Iteration 33: flag writes that push a document past this many chars
         -- (0 = off). Partial edits make writes cheap, so an insert-only agent
         -- never assembles the document and never sees it grow past its split
@@ -3057,6 +3091,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.16.1 (v1.13.1): cerefox_ingest_document no longer consults
+    -- `review_workflow_enabled` — review_status follows author_type whatever
+    -- the flag says; the flag governs visibility/enforcement only. RPC-only,
+    -- no migration (server deploy re-applies rpcs.sql).
+    -- 0.16.0 (#241, #240): `review_workflow_enabled` config key (seeded false
+    -- on fresh installs, true by migration 0031 on existing ones);
+    -- cerefox_ingest_document decides review_status itself from author_type
+    -- + the flag, p_review_status is ignored; p_review_status filter on
+    -- cerefox_hybrid_search / cerefox_search_docs, applied before the limit.
+    -- 0.15.0 (iteration 39): cerefox_rename_document.
+    -- 0.14.0 (#147/#219): store-level writes audited in-RPC.
     -- 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
@@ -3079,7 +3124,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.15.0'::TEXT;
+    SELECT '0.16.1'::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.15.0
+-- @version: 0.16.1
 -- 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 —
@@ -55,7 +55,10 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     total_chars     INT         NOT NULL DEFAULT 0,
     -- review_status: human governance flag. 'approved' = validated by human,
     -- 'pending_review' = modified by agent, not yet reviewed.
-    -- Content is searchable in both states.
+    -- Content is searchable in both states. Written ONLY by
+    -- cerefox_ingest_document, from author_type alone. The store-level
+    -- `review_workflow_enabled` flag (#241) governs whether any surface shows
+    -- or enforces the column; it never changes what is stored (0.16.1).
     review_status   TEXT        NOT NULL DEFAULT 'approved',
     -- lifecycle_status: where this document stands relative to the graph —
     -- 'active' | 'superseded' | 'stale' | 'archived'. Distinct from
@@ -402,6 +405,14 @@ ON CONFLICT (key) DO NOTHING;
 INSERT INTO cerefox_config (key, value)
 VALUES ('relations_enabled', 'false')
 ON CONFLICT (key) DO NOTHING;
+-- The review workflow (agent writes land pending_review, a person approves)
+-- is OFF on a fresh install (#241): most stores have no reviewer, and a queue
+-- nobody drains is noise. Migration 0031 seeds TRUE on stores that predate the
+-- flag, so an upgrade never changes behaviour. Only this seed and that
+-- migration ever write the value; the toggle itself is `cerefox config set`.
+INSERT INTO cerefox_config (key, value)
+VALUES ('review_workflow_enabled', 'false')
+ON CONFLICT (key) DO NOTHING;
 
 
 -- ── Usage log ────────────────────────────────────────────────────────────────