@cerefox/memory 1.15.0 → 1.15.2

package/dist/frontend/index.html

@@ -15,8 +15,8 @@
       href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap"
     />
     <title>Cerefox</title>
-    <script type="module" crossorigin src="/app/assets/index-DUY9wimN.js"></script>
-    <link rel="stylesheet" crossorigin href="/app/assets/index-Dm_zCch4.css">
+    <script type="module" crossorigin src="/app/assets/index-DWeD_pcf.js"></script>
+    <link rel="stylesheet" crossorigin href="/app/assets/index-B0H_N4if.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server-assets/_shared/ef-meta/index.ts

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.15.0";
+export const EF_VERSION = "1.15.2";
 
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.15.0";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.15.0";
+export const CEREFOX_VERSION = "1.15.2";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -46,7 +46,7 @@ export const CEREFOX_VERSION = "1.15.0";
  * `cut_release.ts` ONLY when EF source changed since the last tag; doctor
  * uses it to stay silent on label-only drift.
  */
-export const EF_LAST_CHANGED = "1.14.5";
+export const EF_LAST_CHANGED = "1.15.2";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/embeddings/onnx-embedder.ts

@@ -65,6 +65,12 @@ async function loadTransformers(): Promise<typeof transformersModule> {
   // eszip for the EF) from statically resolving the ~30 MB package + native
   // onnxruntime binary. Resolved at runtime from node_modules.
   const spec = "@huggingface/transformers";
+  // onnxruntime 1.29+ ships Microsoft usage telemetry (a device id plus usage
+  // events, queued on disk and posted to mobile.events.data.microsoft.com).
+  // This is the embedder that exists so nothing leaves the machine, so opt out
+  // before the native library loads. `??=`: an operator who sets it explicitly
+  // (to anything) keeps their choice.
+  process.env.ORT_DISABLE_TELEMETRY ??= "1";
   transformersModule = await import(spec);
   const dir = getCacheDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });

package/dist/server-assets/db/migrations/0032_derive_grants.sql

@@ -0,0 +1,55 @@
+-- 0032_derive_grants.sql — derive the Data API grant list instead of listing it
+--
+-- Issue: the explicit-grant block (0013, #26) names its tables in a hand-written
+-- ARRAY. That array has to match the set of `cerefox_*` tables, and it drifted:
+-- `cerefox_document_relations` was added to schema.sql and never added to the
+-- array. On an UPGRADE path that table is fine (0014 grants it inline), and on
+-- the self-hosted stack `roles.sql` grants broadly via its own PostgREST wiring
+-- — so the gap is invisible everywhere except the case nobody runs by hand: a
+-- FRESH cloud deploy, where `ALTER DEFAULT PRIVILEGES` cannot help because it
+-- only affects tables created AFTER it runs.
+--
+-- From 2026-10-30 Supabase stops granting Data API access to new tables in
+-- `public` automatically, so a missing grant stops being cosmetic and becomes a
+-- 42501 the first time anything reaches that table over PostgREST.
+--
+-- The fix is the one this project keeps arriving at: derive the list. Every
+-- `cerefox_*` table in `public` is granted, so a new table cannot be forgotten.
+-- Idempotent and safe to re-run.
+--
+-- `anon` and `authenticated` still get NOTHING, deliberately: every Cerefox
+-- client authenticates with a service-role-equivalent key, and the RPCs are
+-- SECURITY DEFINER. Supabase's migration note suggests granting all three
+-- roles; doing so here would widen the surface for no caller.
+
+DO $$
+DECLARE t TEXT;
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
+        RAISE NOTICE 'service_role absent (self-hosted stack) — grants skipped; roles.sql wires PostgREST';
+        RETURN;
+    END IF;
+
+    GRANT USAGE ON SCHEMA public TO service_role;
+
+    -- Derived from the catalogue, not from a list someone has to remember.
+    FOR t IN
+        SELECT c.relname
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = 'public'
+          AND c.relkind = 'r'
+          AND c.relname LIKE 'cerefox\_%'
+    LOOP
+        EXECUTE format(
+            'GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE public.%I TO service_role', t
+        );
+    END LOOP;
+
+    -- Tables created LATER by the deploying role inherit the same grants. This
+    -- is belt-and-braces next to the loop above, not a substitute for it: it
+    -- cannot retro-grant anything that already exists, which is exactly how
+    -- cerefox_document_relations slipped through.
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public
+        GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO service_role;
+END $$;

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

@@ -3091,6 +3091,11 @@ 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.2 (#26 follow-up): the Data API grant list is DERIVED from pg_class
+    -- rather than a hand-written array that has to match the set of tables. The
+    -- array had drifted (cerefox_document_relations), which only a FRESH cloud
+    -- deploy would have surfaced, and only after Supabase stops granting new
+    -- public tables automatically on 2026-10-30. Migration 0032.
     -- 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,
@@ -3124,7 +3129,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.16.1'::TEXT;
+    SELECT '0.16.2'::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.16.1
+-- @version: 0.16.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 —
@@ -482,21 +482,29 @@ ALTER TABLE cerefox_document_relations    ENABLE ROW LEVEL SECURITY;
 -- Guarded: on the local (World B) stack this file deploys BEFORE roles.sql
 -- creates service_role, so missing-role must be a no-op (roles.sql re-runs the
 -- grants implicitly via its own PostgREST wiring; the next deploy picks them up).
+-- DERIVED from the catalogue, never listed. The list used to be a hand-written
+-- ARRAY and it drifted: cerefox_document_relations was added above and never
+-- added to the array, so a FRESH cloud deploy left that table with no Data API
+-- grant. Upgrades hid it (migration 0014 grants it inline) and the self-hosted
+-- stack hid it (roles.sql grants broadly), which is why it survived unnoticed.
+-- ALTER DEFAULT PRIVILEGES below cannot cover it either — that only affects
+-- tables created AFTER it runs. See migration 0032.
 DO $$
 DECLARE t TEXT;
 BEGIN
     IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
         GRANT USAGE ON SCHEMA public TO service_role;
-        FOREACH t IN ARRAY ARRAY[
-            'cerefox_projects', 'cerefox_documents', 'cerefox_document_versions',
-            'cerefox_audit_log', 'cerefox_document_projects', 'cerefox_chunks',
-            'cerefox_migrations', 'cerefox_config', 'cerefox_usage_log'
-        ] LOOP
-            IF to_regclass('public.' || t) IS NOT NULL THEN
-                EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE public.%I TO service_role', t);
-            END IF;
+        FOR t IN
+            SELECT c.relname
+            FROM pg_class c
+            JOIN pg_namespace n ON n.oid = c.relnamespace
+            WHERE n.nspname = 'public'
+              AND c.relkind = 'r'
+              AND c.relname LIKE 'cerefox\_%'
+        LOOP
+            EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE public.%I TO service_role', t);
         END LOOP;
-        -- Future cerefox_* tables created by the deploying role keep working.
+        -- Tables created LATER by the deploying role inherit the same grants.
         ALTER DEFAULT PRIVILEGES IN SCHEMA public
             GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO service_role;
     END IF;

package/docs/guides/ops-scripts.md

@@ -29,6 +29,16 @@ The canonical scripts are **TypeScript**, run with [Bun](https://bun.sh) (instal
 | `backup_create.ts` | `bun scripts/backup_create.ts` |
 | `backup_restore.ts` | `bun scripts/backup_restore.ts` |
 | `reindex_all.ts` | `bun scripts/reindex_all.ts` |
+| `cerefox_export.ts` | `bun scripts/cerefox_export.ts` |
+| `gen_openapi.ts` | `bun scripts/gen_openapi.ts` |
+| `cut_release.ts` | `bun scripts/cut_release.ts` (see [RELEASING.md](../../RELEASING.md)) |
+
+The remaining files under `scripts/` are not run by hand: `bundle_help.ts`,
+`bundle_package_docs.ts` and `bundle_server_assets.ts` are `prepublishOnly` steps,
+and `check_ef_parity.ts` and `check_help_bundle.ts` are CI checks.
+`_shared/__tests__/ops-scripts-documented.test.ts` holds that split, so a new
+script has to be either documented here or deliberately classified — it cannot be
+silently forgotten.
 
 Use the `.ts` scripts. The former `.py` equivalents were **removed at v1.0.0** — update any
 cron jobs / CI / make targets that still invoke a `python scripts/*.py` path.
@@ -230,6 +240,92 @@ The backup directory (`./backup-data/` by default) is gitignored. Back up the ba
 
 ---
 
+## cerefox_export.ts — Export every document as markdown files
+
+A one-way dump for local browsing, grepping and offline copies. **Not** a restore
+path: use `backup_create.ts` / `backup_restore.ts` for that.
+
+```bash
+bun scripts/cerefox_export.ts <target-folder>
+bun scripts/cerefox_export.ts <target-folder> --project "My Project"
+bun scripts/cerefox_export.ts <target-folder> --force          # allow a non-empty target
+bun scripts/cerefox_export.ts <target-folder> --no-metadata    # content only
+```
+
+Layout — one folder per project, documents with no project at the root:
+
+```
+<target>/<project-slug>/<title-slug>.md              the reconstructed markdown
+<target>/<project-slug>/<title-slug>-metadata.md     the metadata sidecar
+```
+
+A document in several projects is written **once per project** (copies), so each
+folder stands alone.
+
+### The metadata sidecar
+
+Each document gets a `-metadata.md` beside it, so an exported file is
+self-describing rather than anonymous prose. It carries the document id, source,
+**every** project membership (not just the folder that copy is in), created and
+updated timestamps, character and chunk counts, the metadata keys as a table, and
+the **`content_hash`** — the concurrency token, so an exported copy can be edited
+and re-ingested with `expected_content_hash`.
+
+`review_status` appears only when the store has the review workflow enabled; when
+it is off the field is absent from every other surface, and an export is not the
+place to resurrect it.
+
+Markdown rather than JSON so the sidecars are readable in the same editor as the
+documents. Pass `--no-metadata` for the older content-only behaviour.
+
+Two naming details worth knowing:
+
+- Title collisions get a numeric suffix (`doc-2.md`), and the sidecar follows the
+  file it describes (`doc-2-metadata.md`).
+- A document whose own title ends in "metadata" produces a content file named
+  exactly like another document's sidecar (`foo-metadata.md` is both the export
+  of "Foo Metadata" and the sidecar of "Foo"). Sidecar names share the same
+  uniqueness domain as content files, so whichever is written second gets the
+  numeric suffix and neither can overwrite the other. A real store contains such
+  a pair.
+
+## gen_openapi.ts — Regenerate the OpenAPI document
+
+`docs/api/openapi.json` describes `/api/v1` in OpenAPI 3.1, for callers that embed
+Cerefox instead of using MCP or the CLI. Point any OpenAPI tool at it to generate
+a client or a tool set.
+
+```bash
+bun scripts/gen_openapi.ts             # write docs/api/openapi.json
+bun scripts/gen_openapi.ts --check     # fail if the committed file is stale (CI)
+bun scripts/gen_openapi.ts --stdout    # print, write nothing
+```
+
+**Run it after changing a route, a summary in [`api.md`](api.md), or a zod schema
+in `_shared/schemas/`.** You will not forget silently:
+`_shared/__tests__/api-openapi-spec.test.ts` fails when the committed artifact is
+not what the generator produces.
+
+It is assembled from three sources rather than written, so no fact about the API
+is authored twice:
+
+| Part of the spec | Comes from |
+|---|---|
+| paths and methods | the route registrations in `packages/memory/src/web/routes/` |
+| summaries | the endpoint table in `docs/guides/api.md` |
+| request/response shapes | the zod schemas in `_shared/schemas/` |
+
+Two things worth knowing about what it does *not* claim:
+
+- **Coverage is stated, not implied.** `x-cerefox-coverage` in the document lists
+  how many routes carry a response schema, which routes legitimately return
+  something other than JSON, and which are unmodelled. An unmodelled route gets
+  **no** schema rather than a guessed one.
+- **`info.version` is the API's, not the release's.** It moves when `/api/v1`
+  changes. Binding it to the package version made the committed artifact stale at
+  every release cut — which broke the v1.15.1 npm publish — and churned every
+  generated client on patch releases that did not touch the API.
+
 ## sync_docs.ts — Sync project documentation into Cerefox
 
 Ingests `README.md`, `AGENT_GUIDE.md`, `AGENT_QUICK_REFERENCE.md`, and every Markdown file under `docs/` into your Cerefox knowledge base, updating existing documents in-place. Run this any time after editing documentation so AI agents always have access to the current state of the project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "description": "Cerefox \u2014 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",
@@ -40,27 +40,27 @@
   ],
   "dependencies": {
     "@hono/node-server": "^2.1.1",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "@supabase/supabase-js": "^2.45.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@supabase/supabase-js": "^2.117.2",
     "cli-progress": "^3.12.0",
     "commander": "^15.0.0",
-    "hono": "^4.13.7",
-    "mammoth": "^1.9.0",
+    "hono": "^4.13.9",
+    "mammoth": "^1.13.0",
     "ora": "^9.4.0",
     "picocolors": "^1.0.0",
     "postgres": "^3.4.9",
     "prompts": "^2.4.2",
-    "smol-toml": "^1.6.1",
+    "smol-toml": "^1.9.0",
     "zod": "^4.6.5"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "^4.2.0",
+    "@huggingface/transformers": "^4.3.0",
     "onnxruntime-node": "^1.21.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.2",
     "@types/cli-progress": "^3.11.5",
-    "@types/node": "^24.13.3",
+    "@types/node": "^24.19.0",
     "@types/prompts": "^2.4.9",
     "typescript": "^6.0.3"
   },