@cerefox/memory 1.1.0-beta.5 → 1.1.0-beta.6

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.1.0-beta.5";
+var PKG_VERSION = "1.1.0-beta.6";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -78094,7 +78094,7 @@ async function action27(options) {
   println(c.bold(`Reindexing ${chunks.length} chunk(s) ${reindexAll ? "(--all)" : "(stale only)"}${dryRun ? " — DRY RUN" : ""}`));
   warnLargeBulkWrite({
     count: chunks.length,
-    threshold: 1000,
+    threshold: 5000,
     unit: "chunk",
     batchHint: "reindex in stages with --document-id"
   });
@@ -78189,7 +78189,7 @@ async function action28(options) {
   }
   warnLargeBulkWrite({
     count: targets.length,
-    threshold: 200,
+    threshold: 1000,
     unit: "document",
     batchHint: "run it in batches with --limit 100"
   });

package/dist/server-assets/db/migrations/0015_conflict_errcode_pt409.sql

@@ -0,0 +1,51 @@
+-- 0015_conflict_errcode_pt409.sql — stop a permanent conflict masquerading as
+-- a retryable one.
+--
+-- `cerefox_ingest_document` raised CEREFOX_CONFLICT under SQLSTATE '40001'
+-- (serialization_failure). In PostgreSQL, 40001 is the one class that promises
+-- "this failure was transient — retry the transaction and it may succeed", and
+-- PostgREST maps it to a retryable HTTP status. But an optimistic-concurrency
+-- conflict is DETERMINISTIC: the same request, carrying the same stale token,
+-- fails identically forever. Retry-aware infrastructure took the promise at
+-- face value and looped with no exit condition.
+--
+-- Measured on a live project before the fix:
+--
+--   * ONE HTTP request with a stale token executed the function 68,825 times
+--     in 125 seconds, then returned 504 Gateway Timeout.
+--   * The loop OUTLIVED the client: it kept running after the 504, passing
+--     153,000 executions before the backend was terminated by hand.
+--   * A contributor hit the same loop for roughly a day: ~47 MILLION calls,
+--     which exhausted their project's Disk IO budget and required killing a
+--     hung connection to stop.
+--   * The identical probe raising PT409 executed exactly ONCE and returned
+--     409 Conflict in 636 ms.
+--
+-- Two changes, both in `cerefox_ingest_document`:
+--
+--   1. Conflicts now raise SQLSTATE 'PT409'. PostgREST's PTxxx convention maps
+--      it to HTTP 409 Conflict, which nothing retries.
+--   2. A blank (empty or whitespace) expected_content_hash is treated as
+--      ABSENT rather than stale, so it raises CEREFOX_TOKEN_REQUIRED (400)
+--      instead of a conflict. '' is not NULL, so it used to slip past the
+--      absent-token branch into the conflict branch — and could never match a
+--      real hash, making it a permanent failure. That is the exact shape that
+--      triggered the incident.
+--
+-- Client detection is unaffected: every transport matches on the
+-- `CEREFOX_CONFLICT:` / `CEREFOX_TOKEN_REQUIRED:` message prefix, never on the
+-- SQLSTATE.
+--
+-- This migration only re-applies `rpcs.sql`, which `cerefox server deploy`
+-- does anyway. It exists so the schema version moves and operators are told to
+-- redeploy — the fix is inert until the RPC is replaced.
+--
+-- Idempotent: safe to re-run.
+
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0015: CEREFOX_CONFLICT now raises PT409 (HTTP 409) instead of 40001. '
+        'The change lives in rpcs.sql, which is re-applied by `cerefox server deploy`. '
+        'Until that runs, stale-token conflicts remain retryable by infrastructure.';
+END $$;

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

@@ -1253,7 +1253,7 @@ $$;
 --   p_expected_content_hash : optimistic-concurrency token (iter-32). On the UPDATE
 --                       path this must equal the document's current content_hash —
 --                       the caller proves they based their edit on the live version.
---                       Mismatch → CEREFOX_CONFLICT (SQLSTATE 40001). Absent (NULL)
+--                       Mismatch → CEREFOX_CONFLICT (SQLSTATE PT409 → HTTP 409). Absent (NULL)
 --                       without p_last_write_wins → CEREFOX_TOKEN_REQUIRED (22023).
 --                       Ignored on the CREATE path.
 --   p_last_write_wins : explicit opt-out of the concurrency check (filesystem-sync
@@ -1368,7 +1368,17 @@ BEGIN
         -- choose last-write-wins. Message prefixes are machine-detectable:
         -- transport handlers map them to agent-first retry instructions.
         IF NOT p_last_write_wins THEN
-            IF p_expected_content_hash IS NULL THEN
+            -- A blank token is an ABSENT token, not a stale one.
+            --
+            -- '' is not NULL, so an empty string used to skip the
+            -- TOKEN_REQUIRED branch and fall into the conflict branch below:
+            -- it can never equal a real hash, so it failed deterministically
+            -- and forever. That is precisely the shape that drove the retry
+            -- storm — a permanent failure reported as a retryable one. Even
+            -- with PT409 now closing the loop, classifying it as a conflict is
+            -- wrong: nobody read '' from a document, so the caller has not
+            -- followed the read-before-write contract, which is a 400.
+            IF NULLIF(BTRIM(p_expected_content_hash), '') IS NULL THEN
                 RAISE EXCEPTION
                     'CEREFOX_TOKEN_REQUIRED: content updates require expected_content_hash (the content_hash you read) or last_write_wins=true. Current hash: %',
                     v_current_hash
@@ -1377,7 +1387,27 @@ BEGIN
                 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
-                    USING ERRCODE = '40001';  -- serialization_failure
+                    -- PT409 → HTTP 409 Conflict (PostgREST's PTxxx convention).
+                    --
+                    -- This was '40001' (serialization_failure) until v1.1.0-beta.6,
+                    -- which was a category error with severe consequences. 40001 is
+                    -- the ONE PostgreSQL class that promises "this was transient,
+                    -- retry and it may succeed" — but a stale-token conflict is
+                    -- DETERMINISTIC: the same request fails identically forever.
+                    -- Retry-aware layers took the promise at face value and looped.
+                    --
+                    -- Measured on a real project: one HTTP request carrying a stale
+                    -- hash executed this function 68,825 times in 125s before the
+                    -- gateway returned 504 — and kept going after the client was
+                    -- gone, passing 153,000 executions before the backend was killed
+                    -- manually. A contributor hit the same loop for ~24h and 47
+                    -- MILLION calls, which is what depleted their Disk IO budget.
+                    -- The same probe raising PT409 executed exactly ONCE and
+                    -- returned 409 in 636ms.
+                    --
+                    -- Rule of thumb: never raise a permanent application error under
+                    -- a SQLSTATE whose contract says "retryable".
+                    USING ERRCODE = 'PT409';
             END IF;
         END IF;
 
@@ -2234,7 +2264,7 @@ 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.
-    SELECT '0.10.1'::TEXT;
+    SELECT '0.10.2'::TEXT;
 $$;
 
 -- ── 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.10.1
+-- @version: 0.10.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 —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.1.0-beta.5",
+  "version": "1.1.0-beta.6",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",