@cerefox/memory 0.11.1 → 1.0.0-beta.1

package/dist/server-assets/_shared/mcp-auth/index.ts

@@ -0,0 +1,352 @@
+/**
+ * mcp-auth — in-function authentication for the `cerefox-mcp` Edge Function.
+ *
+ * Context: to be an OAuth 2.1 protected resource server, `cerefox-mcp` must serve
+ * unauthenticated discovery routes and issue its own 401 challenges. That requires
+ * deploying it with `--no-verify-jwt` (the Supabase gateway otherwise rejects the
+ * request before the function runs). With the gateway gate removed, **this module
+ * becomes the only auth gate** — see the invariants in
+ * `docs/specs/oauth-mcp-server-design.md` §5–6.
+ *
+ * Two accepted credentials (design §5):
+ *   Path 1 — an optional static Bearer, constant-time compared against an
+ *            explicitly-set value. Left unset by cerefox-mcp since iter-28E (its
+ *            static path is the Cerefox access token, checked in the EF via
+ *            _shared/ef-auth); kept here as a generic, fail-closed capability.
+ *   Path 2 — an OAuth 2.1 access token: a project-signed JWT validated against the
+ *            project JWKS (asymmetric alg allowlist, iss/aud/exp/nbf, owner `sub`).
+ *
+ * Portability: this file uses ONLY Web Platform globals (`crypto.subtle`, `fetch`,
+ * `atob`, `TextEncoder`) — no `node:`, `jsr:`, or `npm:` imports — so the identical
+ * source runs under Deno (the Edge Function) and Bun (`bun test`). JWT verification
+ * is implemented directly on SubtleCrypto rather than pulling in `jose`; ES256/RS256
+ * JWS signatures are already in the raw formats SubtleCrypto's `verify` expects.
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type AuthPath = "static" | "oauth";
+
+export interface AuthSuccess {
+  ok: true;
+  path: AuthPath;
+  /** The authenticated subject (owner user id) for OAuth; undefined for static. */
+  sub?: string;
+}
+
+export interface AuthFailure {
+  ok: false;
+  /** Machine-readable reason, also used to shape the WWW-Authenticate challenge. */
+  reason:
+    | "no_token"
+    | "malformed_token"
+    | "bad_signature"
+    | "bad_claims"
+    | "not_owner"
+    | "no_verifier";
+  /** Human detail for logs (never returned to the client). */
+  detail?: string;
+}
+
+export type AuthResult = AuthSuccess | AuthFailure;
+
+interface Jwk {
+  kty: string;
+  kid?: string;
+  alg?: string;
+  crv?: string;
+  n?: string;
+  e?: string;
+  x?: string;
+  y?: string;
+  use?: string;
+}
+
+interface Jwks {
+  keys: Jwk[];
+}
+
+export interface McpAuthConfig {
+  /** Expected token issuer, e.g. `https://<ref>.supabase.co/auth/v1`. */
+  issuer: string;
+  /** JWKS URL, e.g. `<issuer>/.well-known/jwks.json`. */
+  jwksUri: string;
+  /** Expected `aud` claim. Supabase issues `"authenticated"`. */
+  expectedAudience: string;
+  /**
+   * Pinned owner user id. When set, an OAuth token's `sub` MUST equal it. When
+   * null/undefined the OAuth path FAILS CLOSED (rejects) unless `allowAnyUser` is
+   * true — because with Supabase's default email sign-ups on, an unpinned server
+   * would accept any self-registered user's token (design §6 / Finding 3).
+   */
+  ownerUserId?: string | null;
+  /**
+   * Explicit opt-out of the owner pin: accept any validly-signed `authenticated`
+   * token when `ownerUserId` is unset. For deliberate multi-user / sign-ups-disabled
+   * setups only. Default false (fail closed when unpinned).
+   */
+  allowAnyUser?: boolean;
+  /**
+   * Expected value for the optional static-Bearer path. When null/undefined the
+   * static path is disabled and rejects everything (fail-closed — never
+   * accept-all). cerefox-mcp leaves this null since iter-28E (its static path is
+   * the Cerefox access token, validated in the EF via `_shared/ef-auth`).
+   */
+  staticBearer?: string | null;
+  /** Accepted JWS algorithms. Default `["ES256", "RS256"]`. Never HS256/none. */
+  allowedAlgs?: string[];
+  /** Clock skew tolerance in seconds. Default 60. */
+  clockSkewSec?: number;
+  /** JWKS cache TTL in seconds. Default 600. */
+  jwksCacheTtlSec?: number;
+  /** Injectable clock (ms since epoch). Default `Date.now`. */
+  now?: () => number;
+  /** Injectable fetch (for tests). Default global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface McpAuthenticator {
+  authenticate(authorizationHeader: string | null): Promise<AuthResult>;
+}
+
+// ── Base64url / encoding helpers ─────────────────────────────────────────────
+
+function base64UrlToBytes(input: string): Uint8Array {
+  const b64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4));
+  const bin = atob(b64 + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * Copy a view's bytes into a fresh, plain `ArrayBuffer`. SubtleCrypto expects a
+ * `BufferSource`; under strict typed-array generics (TS 5.7) a `Uint8Array` may be
+ * inferred as `ArrayBufferLike`-backed, so we normalize to `ArrayBuffer` here.
+ */
+function toArrayBuffer(view: Uint8Array): ArrayBuffer {
+  return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength) as ArrayBuffer;
+}
+
+function base64UrlToString(input: string): string {
+  return new TextDecoder().decode(base64UrlToBytes(input));
+}
+
+/**
+ * Length-independent constant-time string comparison. Iterates over the longer
+ * length so the loop count doesn't leak which operand is shorter, and folds a
+ * length mismatch into the result rather than short-circuiting.
+ */
+export function constantTimeEqual(a: string, b: string): boolean {
+  const ab = new TextEncoder().encode(a);
+  const bb = new TextEncoder().encode(b);
+  const len = Math.max(ab.length, bb.length);
+  let diff = ab.length ^ bb.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (ab[i] ?? 0) ^ (bb[i] ?? 0);
+  }
+  return diff === 0;
+}
+
+// ── JWT verification (SubtleCrypto) ──────────────────────────────────────────
+
+interface JwtHeader {
+  alg: string;
+  kid?: string;
+  typ?: string;
+}
+
+interface JwtPayload {
+  iss?: string;
+  sub?: string;
+  aud?: string | string[];
+  exp?: number;
+  nbf?: number;
+  iat?: number;
+  role?: string;
+  client_id?: string;
+  [k: string]: unknown;
+}
+
+function importParamsFor(alg: string, jwk: Jwk): {
+  importAlgo: EcKeyImportParams | RsaHashedImportParams;
+  verifyAlgo: EcdsaParams | AlgorithmIdentifier;
+} | null {
+  if (alg === "ES256" && jwk.kty === "EC") {
+    return {
+      importAlgo: { name: "ECDSA", namedCurve: "P-256" },
+      verifyAlgo: { name: "ECDSA", hash: { name: "SHA-256" } },
+    };
+  }
+  if (alg === "RS256" && jwk.kty === "RSA") {
+    return {
+      importAlgo: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+      verifyAlgo: { name: "RSASSA-PKCS1-v1_5" },
+    };
+  }
+  return null;
+}
+
+async function verifyJwtSignature(
+  token: string,
+  header: JwtHeader,
+  jwks: Jwks,
+): Promise<boolean> {
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  const [headerB64, payloadB64, sigB64] = parts;
+
+  // Select the key by kid; if the token has no kid, accept a lone matching key.
+  const candidates = jwks.keys.filter((k) => {
+    if (header.kid) return k.kid === header.kid;
+    return true;
+  });
+  if (candidates.length === 0) return false;
+
+  const signature = toArrayBuffer(base64UrlToBytes(sigB64));
+  const signed = toArrayBuffer(new TextEncoder().encode(`${headerB64}.${payloadB64}`));
+
+  for (const jwk of candidates) {
+    const params = importParamsFor(header.alg, jwk);
+    if (!params) continue;
+    try {
+      const key = await crypto.subtle.importKey(
+        "jwk",
+        jwk as JsonWebKey,
+        params.importAlgo,
+        false,
+        ["verify"],
+      );
+      const ok = await crypto.subtle.verify(params.verifyAlgo, key, signature, signed);
+      if (ok) return true;
+    } catch {
+      // try the next candidate key
+    }
+  }
+  return false;
+}
+
+// ── Authenticator factory ────────────────────────────────────────────────────
+
+const BEARER_PREFIX = "Bearer ";
+
+export function createMcpAuthenticator(config: McpAuthConfig): McpAuthenticator {
+  const allowedAlgs = config.allowedAlgs ?? ["ES256", "RS256"];
+  const clockSkewSec = config.clockSkewSec ?? 60;
+  const jwksCacheTtlSec = config.jwksCacheTtlSec ?? 600;
+  const now = config.now ?? (() => Date.now());
+  const fetchImpl = config.fetchImpl ?? fetch;
+
+  // Isolate-lifetime JWKS cache (closure state). Key rotation is picked up on
+  // TTL expiry or isolate recycle.
+  let cache: { jwks: Jwks; fetchedAt: number } | null = null;
+
+  async function getJwks(): Promise<Jwks | null> {
+    if (cache && now() - cache.fetchedAt < jwksCacheTtlSec * 1000) {
+      return cache.jwks;
+    }
+    try {
+      const resp = await fetchImpl(config.jwksUri);
+      if (!resp.ok) return cache?.jwks ?? null;
+      const jwks = (await resp.json()) as Jwks;
+      if (!jwks || !Array.isArray(jwks.keys)) return cache?.jwks ?? null;
+      cache = { jwks, fetchedAt: now() };
+      return jwks;
+    } catch {
+      // On a transient fetch failure, fall back to a still-cached set if any;
+      // otherwise fail closed (caller rejects).
+      return cache?.jwks ?? null;
+    }
+  }
+
+  function validateClaims(payload: JwtPayload): AuthResult {
+    const nowSec = Math.floor(now() / 1000);
+
+    if (payload.iss !== config.issuer) {
+      return { ok: false, reason: "bad_claims", detail: `iss=${payload.iss} want=${config.issuer}` };
+    }
+    const auds = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    if (!auds.includes(config.expectedAudience)) {
+      return {
+        ok: false,
+        reason: "bad_claims",
+        detail: `aud=${JSON.stringify(payload.aud)} want=${config.expectedAudience}`,
+      };
+    }
+    if (typeof payload.exp !== "number" || payload.exp + clockSkewSec < nowSec) {
+      return { ok: false, reason: "bad_claims", detail: `expired (exp=${payload.exp})` };
+    }
+    if (typeof payload.nbf === "number" && payload.nbf - clockSkewSec > nowSec) {
+      return { ok: false, reason: "bad_claims", detail: "not yet valid" };
+    }
+    if (!payload.sub) {
+      return { ok: false, reason: "bad_claims", detail: "missing sub" };
+    }
+    if (config.ownerUserId) {
+      if (payload.sub !== config.ownerUserId) {
+        return { ok: false, reason: "not_owner", detail: `sub=${payload.sub} owner=${config.ownerUserId}` };
+      }
+    } else if (!config.allowAnyUser) {
+      // Fail closed: no owner pinned and no explicit opt-out. Accepting here would
+      // let any self-registered user in (Supabase email sign-ups default on).
+      return {
+        ok: false,
+        reason: "not_owner",
+        detail: "owner not pinned; set CEREFOX_OAUTH_OWNER_ID (or CEREFOX_OAUTH_ALLOW_ANY_USER=true to opt out)",
+      };
+    }
+    return { ok: true, path: "oauth", sub: payload.sub };
+  }
+
+  async function authenticate(authorizationHeader: string | null): Promise<AuthResult> {
+    if (!authorizationHeader || !authorizationHeader.startsWith(BEARER_PREFIX)) {
+      return { ok: false, reason: "no_token" };
+    }
+    const token = authorizationHeader.slice(BEARER_PREFIX.length).trim();
+    if (!token) return { ok: false, reason: "no_token" };
+
+    // Path 1 — legacy static Bearer (constant-time). Fail-closed when unset.
+    if (config.staticBearer && constantTimeEqual(token, config.staticBearer)) {
+      return { ok: true, path: "static" };
+    }
+
+    // Path 2 — OAuth access token (JWT against JWKS).
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return { ok: false, reason: "malformed_token", detail: "not a JWT" };
+    }
+    let header: JwtHeader;
+    let payload: JwtPayload;
+    try {
+      header = JSON.parse(base64UrlToString(parts[0])) as JwtHeader;
+      payload = JSON.parse(base64UrlToString(parts[1])) as JwtPayload;
+    } catch {
+      return { ok: false, reason: "malformed_token", detail: "bad JSON" };
+    }
+
+    // Algorithm allowlist BEFORE any crypto — reject none/HS256 outright, which
+    // is what defends against alg-confusion with the HS256 legacy anon JWT.
+    if (!allowedAlgs.includes(header.alg)) {
+      return { ok: false, reason: "bad_signature", detail: `alg ${header.alg} not allowed` };
+    }
+
+    const jwks = await getJwks();
+    if (!jwks) return { ok: false, reason: "no_verifier", detail: "JWKS unavailable" };
+
+    const verified = await verifyJwtSignature(token, header, jwks);
+    if (!verified) {
+      return {
+        ok: false,
+        reason: "bad_signature",
+        detail: `signature invalid (alg=${header.alg} kid=${header.kid} jwks_kids=${
+          jwks.keys.map((k) => k.kid).join(",")
+        })`,
+      };
+    }
+
+    return validateClaims(payload);
+  }
+
+  return { authenticate };
+}

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

@@ -1,179 +1,25 @@
 /**
- * Heading-aware markdown chunker.
+ * Chunker + content-hash utilities for the MCP ingest tool.
  *
- * Mirrors:
- * - `src/cerefox/chunking/markdown.py` (Python pipeline)
- * - `supabase/functions/cerefox-ingest/index.ts` (standalone ingest EF)
- *
- * Greedy section accumulation: H1/H2/H3 sections are joined into a buffer
- * until adding the next would exceed `MAX_CHUNK_CHARS`. Oversized sections
- * are paragraph-split. Short documents collapse to a single chunk.
- *
- * The hash of the chunked output (via `_hash.ts:sha256hex(normalizeContent(...))`)
- * must match the Python pipeline byte-for-byte so dedup works across access
- * paths. Don't change chunk boundaries without updating both.
+ * iter-28D Phase 1: the chunker is now the single exact-partition implementation
+ * in `_shared/ingest/chunker.ts` — this module re-exports it (the previous copy
+ * here was removed) and keeps the content-hash helpers used for dedup.
  */
 
-export const MAX_CHUNK_CHARS = 4000;
-
-interface Section {
-  level: number;
-  headings: string[];
-  heading: string;
-  content: string;
-  body: string;
-}
-
-export interface Chunk {
-  heading_path: string[];
-  heading_level: number;
-  title: string;
-  content: string;
-  char_count: number;
-}
-
-function parseSections(text: string): Section[] {
-  const lines = text.split("\n");
-  const sections: Section[] = [];
-  let currentHeadings: string[] = [];
-  let currentLevel = 0;
-  let bodyLines: string[] = [];
-
-  function collectSection() {
-    const body = bodyLines.join("\n").trim();
-    bodyLines = [];
-    let content: string;
-    if (currentLevel > 0) {
-      const headerLine = "#".repeat(currentLevel) + " " +
-        (currentHeadings[currentHeadings.length - 1] ?? "");
-      content = body ? headerLine + "\n\n" + body : headerLine;
-    } else {
-      content = body;
-    }
-    if (!content.trim()) return;
-    sections.push({
-      level: currentLevel,
-      headings: [...currentHeadings],
-      heading: currentHeadings[currentHeadings.length - 1] ?? "",
-      content,
-      body,
-    });
-  }
-
-  for (const line of lines) {
-    const h1 = line.match(/^# (.+)/);
-    const h2 = line.match(/^## (.+)/);
-    const h3 = line.match(/^### (.+)/);
-
-    if (h1) {
-      collectSection();
-      currentHeadings = [h1[1].trim()];
-      currentLevel = 1;
-    } else if (h2) {
-      collectSection();
-      currentHeadings = [currentHeadings[0] ?? "", h2[1].trim()].filter(Boolean);
-      currentLevel = 2;
-    } else if (h3) {
-      collectSection();
-      currentHeadings = [
-        currentHeadings[0] ?? "",
-        currentHeadings[1] ?? "",
-        h3[1].trim(),
-      ].filter(Boolean);
-      currentLevel = 3;
-    } else {
-      bodyLines.push(line);
-    }
-  }
-  collectSection();
-  return sections;
-}
-
-function makeChunk(headings: string[], level: number, content: string): Chunk {
-  const title = headings[headings.length - 1] ?? "";
-  return {
-    heading_path: [...headings],
-    heading_level: level,
-    title,
-    content,
-    char_count: content.length,
-  };
-}
+export {
+  chunkMarkdown,
+  embeddingInputFor,
+  CONTENT_FORMAT_BLIND_STITCH,
+  type ChunkData,
+  type ChunkData as Chunk,
+} from "../ingest/chunker.ts";
 
-export function chunkMarkdown(text: string): Chunk[] {
-  const trimmed = text.trim();
-  if (!trimmed) return [];
-
-  if (trimmed.length <= MAX_CHUNK_CHARS) {
-    return [makeChunk([], 0, trimmed)];
-  }
-
-  const sections = parseSections(trimmed);
-  const chunks: Chunk[] = [];
-
-  let bufParts: string[] = [];
-  let bufHeadings: string[] = [];
-  let bufLevel = 0;
-  let bufChars = 0;
-
-  function flushBuf() {
-    if (bufParts.length === 0) return;
-    chunks.push(makeChunk(bufHeadings, bufLevel, bufParts.join("\n\n")));
-    bufParts = [];
-    bufHeadings = [];
-    bufLevel = 0;
-    bufChars = 0;
-  }
-
-  for (const section of sections) {
-    const { level, headings, heading, content, body } = section;
-
-    if (content.length > MAX_CHUNK_CHARS) {
-      flushBuf();
-      const headerPrefix = level > 0 ? "#".repeat(level) + " " + heading + "\n\n" : "";
-      const bodyToSplit = body || content;
-      const paragraphs = bodyToSplit.split(/\n\n+/);
-      let sub = "";
-      let isFirst = true;
-      for (const para of paragraphs) {
-        const prefix = isFirst ? headerPrefix : "";
-        if (sub.length + prefix.length + para.length + 2 > MAX_CHUNK_CHARS && sub.length > 0) {
-          chunks.push(makeChunk(headings, level, sub.trim()));
-          sub = para;
-          isFirst = false;
-        } else {
-          sub = sub ? sub + "\n\n" + para : prefix + para;
-          isFirst = false;
-        }
-      }
-      if (sub.trim()) chunks.push(makeChunk(headings, level, sub.trim()));
-      continue;
-    }
-
-    const addition = content.length + (bufParts.length > 0 ? 2 : 0);
-
-    if (bufChars + addition <= MAX_CHUNK_CHARS) {
-      if (bufParts.length === 0) {
-        bufHeadings = headings;
-        bufLevel = level;
-      }
-      bufParts.push(content);
-      bufChars += addition;
-    } else {
-      flushBuf();
-      bufParts = [content];
-      bufHeadings = headings;
-      bufLevel = level;
-      bufChars = content.length;
-    }
-  }
-
-  flushBuf();
-  return chunks;
-}
+export const MAX_CHUNK_CHARS = 4000;
 
-/** Content-hash normalization. Must match `pipeline.py::_normalize`
- *  byte-for-byte so cross-runtime dedup works. */
+/**
+ * Content-hash normalization. Kept stable so the content_hash dedup key is
+ * consistent across access paths and over time.
+ */
 export function normalizeContent(text: string): string {
   return text.trim().replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\n{3,}/g, "\n\n");
 }

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

@@ -17,7 +17,13 @@
 
 import type { MCPSupabaseClient } from "./types.ts";
 
-import { chunkMarkdown, normalizeContent, sha256hex } from "./_chunker.ts";
+import {
+  chunkMarkdown,
+  embeddingInputFor,
+  CONTENT_FORMAT_BLIND_STITCH,
+  normalizeContent,
+  sha256hex,
+} from "./_chunker.ts";
 import { embedBatch, OPENAI_MODEL } from "../embeddings/index.ts";
 import { ensureDocumentInProject, setDocumentProjectsByName } from "./_projects.ts";
 import { logUsage } from "./_utils.ts";
@@ -137,7 +143,7 @@ async function handler(
     const chunks = chunkMarkdown(content);
     if (chunks.length === 0) throw new Error("Content produced no chunks");
 
-    const texts = chunks.map((c) => `# ${title}\n${c.content}`);
+    const texts = chunks.map((c) => embeddingInputFor(title, c));
     const embeddings = await embedBatch(texts, ctx.openaiApiKey);
     const totalChars = chunks.reduce((s, c) => s + c.char_count, 0);
 
@@ -165,6 +171,7 @@ async function handler(
       p_source_label: source,
       p_expected_content_hash: expected_content_hash,
       p_last_write_wins: last_write_wins,
+      p_content_format: CONTENT_FORMAT_BLIND_STITCH,
     });
 
     if (ingestErr) throw mapIngestRpcError(ingestErr.message, existingDoc.id);
@@ -214,7 +221,7 @@ async function handler(
       const chunks = chunkMarkdown(content);
       if (chunks.length === 0) throw new Error("Content produced no chunks");
 
-      const texts = chunks.map((c) => `# ${title}\n${c.content}`);
+      const texts = chunks.map((c) => embeddingInputFor(title, c));
       const embeddings = await embedBatch(texts, ctx.openaiApiKey);
       const totalChars = chunks.reduce((s, c) => s + c.char_count, 0);
 
@@ -242,6 +249,7 @@ async function handler(
         p_source_label: source,
         p_expected_content_hash: expected_content_hash,
         p_last_write_wins: last_write_wins,
+      p_content_format: CONTENT_FORMAT_BLIND_STITCH,
       });
 
       if (ingestErr) throw mapIngestRpcError(ingestErr.message, existingDoc.id);
@@ -279,7 +287,7 @@ async function handler(
   const chunks = chunkMarkdown(content);
   if (chunks.length === 0) throw new Error("Content produced no chunks");
 
-  const texts = chunks.map((c) => `# ${title}\n${c.content}`);
+  const texts = chunks.map((c) => embeddingInputFor(title, c));
   const embeddings = await embedBatch(texts, ctx.openaiApiKey);
   const totalChars = chunks.reduce((s, c) => s + c.char_count, 0);
 
@@ -304,6 +312,7 @@ async function handler(
     p_chunks: chunkData,
     p_author: author,
     p_author_type: author_type,
+    p_content_format: CONTENT_FORMAT_BLIND_STITCH,
   });
 
   if (ingestErr || !ingestResult?.length) {

package/dist/server-assets/db/migrations/0012_content_format.sql

@@ -0,0 +1,20 @@
+-- Migration 0012: content_format on cerefox_chunks (iter-28D)
+--
+-- Records how each chunk's content reconstructs into full document text:
+--   1 = legacy    — chunk contents were trimmed sections; reconstruction re-joins
+--                   them with E'\n\n' (the pre-28D behaviour). All existing chunks.
+--   2 = blind-stitch — chunk contents are an exact, gapless partition of the
+--                   document; reconstruction is a plain concatenation (no separator
+--                   synthesized on read). Written by the exact-partition chunker.
+--
+-- Placed on the CHUNK (not the document) so an archived version reconstructs with
+-- its OWN format, since Cerefox uses chunks-anchored versioning
+-- (cerefox_chunks.version_id). The reconstruction RPCs branch on
+-- MAX(content_format) >= 2 per aggregated group.
+--
+-- Adding a NOT NULL column with a constant default is a metadata-only change in
+-- PostgreSQL 11+ (no rewrite of the chunks table). Existing rows read back as 1.
+-- Explanation for users: docs/guides/content-format.md.
+
+ALTER TABLE cerefox_chunks
+    ADD COLUMN IF NOT EXISTS content_format SMALLINT NOT NULL DEFAULT 1;