brains-mcp 1.61.2

package/dist/search/postgresIndex.js

@@ -0,0 +1,1610 @@
+/**
+ * postgresIndex.ts
+ *
+ * Supabase Postgres-backed search and listing index for wiki pages.
+ *
+ * Mirrors the SqliteSearchIndex public surface so callers can swap between
+ * backends without changing their code.  Uses the Supabase PostgREST REST API
+ * (no extra SDK dependency — same raw-fetch pattern as SupabaseStorageClient).
+ *
+ * Auto-selected when STORAGE_BACKEND=supabase.  Override with SEARCH_BACKEND=sqlite|scan.
+ *
+ * Table schema: scripts/supabase-pages-index.sql
+ */
+import { extractWikiLinks } from "../wiki/links.js";
+import { generateEmbedding, buildEmbeddingInput, isEmbeddingEnabled } from "./embeddings.js";
+// ─── Singleton management ────────────────────────────────────────────────────
+let instance = null;
+export function getPostgresSearchIndex() {
+    if (!instance)
+        instance = new PostgresSearchIndex();
+    return instance;
+}
+// ─── Main class ──────────────────────────────────────────────────────────────
+export class PostgresSearchIndex {
+    supabaseUrl;
+    serviceRoleKey;
+    baseUrl;
+    linksBaseUrl;
+    archivedPagesBaseUrl;
+    eventsBaseUrl;
+    headers;
+    constructor() {
+        this.supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+        this.serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+        this.baseUrl = `${this.supabaseUrl}/rest/v1/pages`;
+        this.linksBaseUrl = `${this.supabaseUrl}/rest/v1/wiki_links`;
+        this.archivedPagesBaseUrl = `${this.supabaseUrl}/rest/v1/archived_pages`;
+        this.eventsBaseUrl = `${this.supabaseUrl}/rest/v1/wiki_events`;
+        this.headers = {
+            "content-type": "application/json",
+            "apikey": this.serviceRoleKey,
+            "authorization": `Bearer ${this.serviceRoleKey}`,
+        };
+    }
+    isConfigured() {
+        return this.supabaseUrl.length > 0 && this.serviceRoleKey.length > 0;
+    }
+    /**
+     * Lightweight connectivity check. Uses a HEAD + count=exact to verify the
+     * Supabase REST endpoint is reachable without fetching any row data.
+     */
+    async ping(userId = "") {
+        if (!this.isConfigured())
+            return { ok: false, error: "not configured" };
+        try {
+            const params = new URLSearchParams({ select: "name" });
+            if (userId)
+                params.set("user_id", `eq.${userId}`);
+            const res = await fetch(`${this.baseUrl}?${params}`, {
+                method: "HEAD",
+                headers: { ...this.headers, prefer: "count=exact" },
+            });
+            if (!res.ok)
+                return { ok: false, error: `HTTP ${res.status}` };
+            const range = res.headers.get("content-range");
+            const rowCount = range ? parseInt(range.split("/")[1] ?? "", 10) : undefined;
+            return { ok: true, ...(Number.isFinite(rowCount) ? { rowCount } : {}) };
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /**
+     * Count active (non-archived) pages for a user. Returns 0 when not configured
+     * or when the request fails. Uses HEAD + count=exact to avoid fetching rows.
+     */
+    async countActivePages(userId) {
+        if (!this.isConfigured() || !userId)
+            return 0;
+        try {
+            const params = new URLSearchParams({ select: "name" });
+            params.set("user_id", `eq.${userId}`);
+            params.set("status", "neq.archived");
+            const res = await fetch(`${this.baseUrl}?${params}`, {
+                method: "HEAD",
+                headers: { ...this.headers, prefer: "count=exact" },
+            });
+            if (!res.ok)
+                return 0;
+            const range = res.headers.get("content-range");
+            if (!range)
+                return 0;
+            const count = parseInt(range.split("/")[1] ?? "", 10);
+            return Number.isFinite(count) ? count : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Append one activity event.
+     *
+     * Replaces the read-modify-write of log.md that every page write used to
+     * perform: Storage has no append primitive, so appending to a 460 KB file
+     * meant moving ~920 KB and took 2.6-3.6s measured against production. An
+     * indexed insert is O(1) (GH #417).
+     *
+     * Throws on failure so callers can decide — the write paths log a warning
+     * rather than failing the page write, but a silent no-op is what let the
+     * old log.md problem go unnoticed, so the error is not swallowed here.
+     */
+    async appendEvent(input) {
+        if (!this.isConfigured())
+            throw new Error("Postgres not configured");
+        const res = await fetch(this.eventsBaseUrl, {
+            method: "POST",
+            headers: { ...this.headers, prefer: "return=minimal" },
+            body: JSON.stringify({
+                user_id: input.userId,
+                type: input.type,
+                title: input.title,
+                ...(input.detail !== undefined ? { detail: input.detail } : {}),
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`wiki_events insert failed (${res.status}): ${body.slice(0, 200)}`);
+        }
+    }
+    /**
+     * Read activity events for one user since a cutoff date (inclusive,
+     * `YYYY-MM-DD`). Newest first. Returns null when Postgres is unavailable so
+     * the caller can fall back to parsing log.md rather than silently reporting
+     * no activity.
+     */
+    async listEvents(userId, sinceDate, limit = 5000) {
+        if (!this.isConfigured())
+            return null;
+        try {
+            const params = new URLSearchParams();
+            params.set("select", "ts,type,title");
+            params.set("user_id", `eq.${userId}`);
+            params.set("ts", `gte.${sinceDate}`);
+            params.set("order", "ts.desc");
+            params.set("limit", String(limit));
+            const res = await fetch(`${this.eventsBaseUrl}?${params}`, { headers: this.headers });
+            if (!res.ok)
+                return null;
+            const rows = (await res.json());
+            return rows.map((r) => ({
+                date: r.ts.slice(0, 10),
+                type: String(r.type ?? "").toLowerCase(),
+                title: r.title,
+            }));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Fetch every row matching `params`, following limit/offset until exhausted.
+     *
+     * PostgREST clamps a result set to its configured max-rows (1000 here) and
+     * returns 200 OK. A truncated response is byte-identical to a complete one —
+     * no error, no flag — so any "fetch everything then aggregate in JS" call site
+     * silently computes on partial input and returns a confident wrong answer.
+     * That has now happened four times: the bundle folder filter undercounted 164
+     * against 213 (#432), listProjectInventory lost a whole project whose pages
+     * all fell in the truncated tail (#445), and audit_index reported ~174
+     * fabricated unindexed pages by diffing a capped snapshot against full
+     * storage (#449).
+     *
+     * Callers that need a whole table must route through here rather than issuing
+     * an unbounded request. Returns null on transport/HTTP failure, which callers
+     * must treat as "unknown" — never as "empty", since that is exactly how a
+     * partial read becomes a wrong answer.
+     *
+     * Pages by keyset (`name > last seen`), not by offset, and always sorts by
+     * `name.asc`. Two reasons, both of which offset paging gets wrong:
+     *
+     *  - **Never infer the end from a short page.** `rows.length < pageSize` is
+     *    only "the end" if pageSize happens to be ≤ the server's max-rows. That
+     *    is a Supabase dashboard setting on a different system, and staging and
+     *    prod are configured independently. If max-rows is ever lowered below
+     *    pageSize, the first page comes back short and an offset walk stops
+     *    there — silently returning a truncated list from the very helper written
+     *    to prevent that, with no round-number tell to notice it by. Keyset walks
+     *    until a page comes back empty, so it is correct whatever the cap is.
+     *  - **Offset is not stable against concurrent writes.** A page created with
+     *    an earlier-sorting name mid-walk shifts every later row down by one and
+     *    drops exactly one real page from the snapshot. During an audit that page
+     *    then looks unindexed, and cleanup would "repair" it by overwriting its
+     *    DB row from Storage. Keyset resumes from a value, not a position, so an
+     *    insert behind the cursor cannot displace anything.
+     *
+     * Requires `name` in the select — it is the cursor. Returns null if it is
+     * missing rather than looping.
+     */
+    async fetchAllRows(params, pageSize = 1000) {
+        if (!Number.isInteger(pageSize) || pageSize < 1) {
+            throw new RangeError(`fetchAllRows: pageSize must be a positive integer, got ${pageSize}`);
+        }
+        const out = [];
+        let after;
+        for (;;) {
+            // Copy per iteration: never mutate the caller's object, and never let the
+            // previous page's cursor accumulate alongside the new one.
+            const p = new URLSearchParams(params);
+            p.set("order", "name.asc");
+            p.set("limit", String(pageSize));
+            if (after !== undefined)
+                p.append("name", `gt.${after}`);
+            let rows;
+            try {
+                const res = await fetch(`${this.baseUrl}?${p}`, { headers: this.headers });
+                if (!res.ok)
+                    return null;
+                const body = await res.json();
+                // A 200 carrying a non-array body (proxy error page, gateway
+                // interstitial) must be "unknown", not a spread that throws. Parsing
+                // stays inside the try for the same reason: a body truncated mid-stream
+                // rejects here, and the contract is null-on-failure.
+                if (!Array.isArray(body))
+                    return null;
+                rows = body;
+            }
+            catch {
+                return null;
+            }
+            out.push(...rows);
+            if (rows.length === 0)
+                return out;
+            const last = rows[rows.length - 1].name;
+            if (typeof last !== "string" || last === after)
+                return null; // no cursor, or no progress
+            after = last;
+        }
+    }
+    /**
+     * Every indexed page name for a user, complete — not capped at max-rows.
+     *
+     * Exists because audit_index compares the index against storage, and a
+     * truncated index snapshot makes every missing row look like an unindexed
+     * page. Applies the same exclusions as listPages so the two agree on what
+     * counts as a page.
+     *
+     * Returns null if any page of the walk fails. Callers must not fall back to a
+     * partial list — an incomplete audit is worse than no audit, because it
+     * invites a "repair" of pages that were never broken.
+     */
+    async listAllPageNames(userId = "") {
+        if (!this.isConfigured())
+            return null;
+        try {
+            const p = new URLSearchParams();
+            p.set("select", "name");
+            p.set("user_id", `eq.${userId}`);
+            p.append("name", "not.like.page-versions/%");
+            p.append("name", "not.in.(index.md,log.md)");
+            const rows = await this.fetchAllRows(p);
+            return rows ? rows.map((r) => r.name) : null;
+        }
+        catch {
+            // Defence in depth. audit_index's refuse-to-report-drift path keys off a
+            // null return; letting an exception escape would bypass it and surface a
+            // raw stack instead of "retry the audit".
+            return null;
+        }
+    }
+    /**
+     * One row per project: slug, page count, and the root readme's title/aliases.
+     *
+     * Two requests rather than one per project. Aliases come from the readme's
+     * frontmatter and are how a nickname reaches the right project — the
+     * cressida/nessie case, where the slug never appears in what the user typed.
+     *
+     * Anchored to `projects/<slug>/readme.md` exactly. A looser match picks up
+     * nested readmes — cetera-pds alone has nine — and reports one project many
+     * times (GH #430).
+     */
+    async listProjectInventory(userId) {
+        if (!this.isConfigured())
+            return null;
+        try {
+            // Paginate. A `limit` above PostgREST's configured max-rows is silently
+            // clamped, so a single large request looks complete and is not: this wiki
+            // has 1,029 pages under projects/ against a 1,000-row cap, and
+            // retropie-pi4's 13 pages all fell in the truncated tail — the project
+            // vanished from the inventory entirely and resolved to nothing.
+            //
+            // Same failure this file's folder filter had (#432): fetch a capped list,
+            // aggregate client-side, get a confident wrong answer. Paginating keeps
+            // the aggregate honest at the cost of one request per 1,000 pages.
+            const fetchAll = (select, nameFilter) => {
+                const p = new URLSearchParams();
+                p.set("select", select);
+                p.set("user_id", `eq.${userId}`);
+                p.set("name", nameFilter);
+                return this.fetchAllRows(p);
+            };
+            const [nameRows, readmeRows] = await Promise.all([
+                fetchAll("name", "like.projects/%"),
+                fetchAll("name,title,aliases,summary", "like.projects/%/readme.md"),
+            ]);
+            if (!nameRows || !readmeRows)
+                return null;
+            // A sub-project lives at projects/<parent>/projects/<child>/. That nested
+            // `projects/` segment is the marker: a plain subfolder cannot be used as
+            // one, because category folders carry readme.md too (cetera-pds has eight),
+            // so folder shape alone cannot tell a sub-project from canonical/ or
+            // decisions/ (GH #444).
+            //
+            // Child pages count toward the parent as well as themselves. They sit
+            // under the parent's prefix, so a folder-scoped bundle for the parent
+            // genuinely includes them — which is the reason nesting was chosen.
+            const counts = new Map();
+            const parentOf = new Map();
+            for (const r of nameRows) {
+                const parts = r.name.split("/");
+                if (parts.length < 3)
+                    continue; // needs projects/<slug>/<something>
+                const parent = parts[1];
+                counts.set(parent, (counts.get(parent) ?? 0) + 1);
+                if (parts.length >= 5 && parts[2] === "projects") {
+                    const childKey = `${parent}/${parts[3]}`;
+                    counts.set(childKey, (counts.get(childKey) ?? 0) + 1);
+                    parentOf.set(childKey, parent);
+                }
+            }
+            // Aliases come from the readme's explicit `aliases:` frontmatter and
+            // nowhere else. They were previously inferred from tags, which cost three
+            // separate false-match bugs: `oio` on projects/geoffrey means "this is an
+            // OIO vehicle" (membership), and `state` on shop-shelf's readme names a
+            // document kind. Filtering tags that happen to be project slugs caught the
+            // first and missed the second, because the tag vocabulary simply does not
+            // encode the difference between "also called X" and "is about X" (#446).
+            //
+            // No fallback to tags when `aliases:` is absent — a silent fallback
+            // reintroduces the bug the moment someone adds a tag.
+            const meta = new Map();
+            for (const r of readmeRows) {
+                const parts = r.name.split("/");
+                // projects/<slug>/readme.md (3 segments) is a project root;
+                // projects/<parent>/projects/<child>/readme.md (5) is a sub-project.
+                // Anything else is a category folder's readme and must be ignored, or a
+                // single project reports itself many times.
+                const isRoot = parts.length === 3;
+                const isSub = parts.length === 5 && parts[2] === "projects";
+                if (!isRoot && !isSub)
+                    continue;
+                const slug = isRoot ? parts[1] : `${parts[1]}/${parts[3]}`;
+                // A title equal to the path is generator noise, not a real title.
+                const title = r.title && !r.title.startsWith("projects/") ? r.title : undefined;
+                // A project naming itself is not an alias; it is already the slug.
+                const aliases = (r.aliases ?? []).filter((a) => a !== slug && !slug.endsWith(`/${a}`));
+                meta.set(slug, { title, aliases: aliases.length > 0 ? aliases : undefined });
+            }
+            return [...counts.entries()].map(([slug, pageCount]) => ({
+                slug,
+                pageCount,
+                ...(parentOf.has(slug) ? { parentSlug: parentOf.get(slug) } : {}),
+                ...meta.get(slug),
+            }));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Full-text hits per project, for when the slug does not appear in what the
+     * user typed. Returns a slug -> hit-count map.
+     */
+    async countProjectContentHits(context, userId) {
+        const hits = new Map();
+        if (!this.isConfigured())
+            return hits;
+        try {
+            const result = await this.search({ query: context, userId, maxResults: 200 });
+            for (const r of result.results) {
+                const parts = r.name.split("/");
+                if (parts.length < 3 || parts[0] !== "projects")
+                    continue;
+                hits.set(parts[1], (hits.get(parts[1]) ?? 0) + 1);
+            }
+        }
+        catch {
+            // Content ranking is a fallback signal — losing it is not fatal.
+        }
+        return hits;
+    }
+    async countArchivedPages(userId) {
+        if (!this.isConfigured() || !userId)
+            return 0;
+        try {
+            const params = new URLSearchParams({ select: "id" });
+            params.set("user_id", `eq.${userId}`);
+            const res = await fetch(`${this.archivedPagesBaseUrl}?${params}`, {
+                method: "HEAD",
+                headers: { ...this.headers, prefer: "count=exact" },
+            });
+            if (!res.ok)
+                return 0;
+            const range = res.headers.get("content-range");
+            if (!range)
+                return 0;
+            const count = parseInt(range.split("/")[1] ?? "", 10);
+            return Number.isFinite(count) ? count : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async archivePage(input) {
+        if (!this.isConfigured()) {
+            throw new Error("Postgres archive store not configured. Cannot perform archive-on-delete.");
+        }
+        if (!input.userId) {
+            throw new Error("userId is required for archive-on-delete.");
+        }
+        const row = {
+            user_id: input.userId,
+            original_path: input.originalPath,
+            original_folder: input.originalFolder,
+            title: input.title ?? null,
+            tags: input.tags ?? [],
+            content: input.content,
+            revision: input.revision ?? null,
+            size_bytes: input.sizeBytes ?? Buffer.byteLength(input.content, "utf8"),
+            reason: input.reason ?? null,
+            deleted_by: input.deletedBy,
+        };
+        const res = await fetch(this.archivedPagesBaseUrl, {
+            method: "POST",
+            headers: {
+                ...this.headers,
+                prefer: "return=representation",
+            },
+            body: JSON.stringify(row),
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.archivePage failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        const id = rows[0]?.id ?? "";
+        if (!id) {
+            throw new Error("postgresIndex.archivePage succeeded but no archive ID was returned.");
+        }
+        return { id };
+    }
+    async listArchivedPages(options) {
+        if (!this.isConfigured())
+            return [];
+        const params = new URLSearchParams();
+        params.set("select", "id,original_path,original_folder,title,tags,content,revision,size_bytes,reason,deleted_at,deleted_by,restored_at,restored_by");
+        params.set("user_id", `eq.${options.userId}`);
+        params.set("order", "deleted_at.desc");
+        params.set("limit", String(Math.min(Math.max(options.limit ?? 50, 1), 200)));
+        if (!options.includeRestored) {
+            params.set("restored_at", "is.null");
+        }
+        if (options.originalPath) {
+            params.set("original_path", `eq.${options.originalPath}`);
+        }
+        const res = await fetch(`${this.archivedPagesBaseUrl}?${params}`, { headers: this.headers });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.listArchivedPages failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        return rows.map((row) => ({
+            id: row.id,
+            originalPath: row.original_path ?? "",
+            originalFolder: row.original_folder ?? "",
+            title: row.title ?? "",
+            tags: row.tags ?? [],
+            content: row.content ?? "",
+            revision: row.revision ?? "",
+            sizeBytes: row.size_bytes ?? 0,
+            reason: row.reason ?? "",
+            deletedAt: row.deleted_at ?? "",
+            deletedBy: row.deleted_by ?? "",
+            restoredAt: row.restored_at ?? "",
+            restoredBy: row.restored_by ?? "",
+        }));
+    }
+    async getArchivedPageForRestore(input) {
+        const { userId, archiveId, originalPath, deletedAt } = input;
+        if (!this.isConfigured())
+            return null;
+        const params = new URLSearchParams();
+        params.set("select", "id,original_path,original_folder,title,tags,content,revision,size_bytes,reason,deleted_at,deleted_by,restored_at,restored_by");
+        params.set("user_id", `eq.${userId}`);
+        params.set("limit", "1");
+        params.set("order", "deleted_at.desc");
+        if (archiveId) {
+            params.set("id", `eq.${archiveId}`);
+        }
+        else if (originalPath) {
+            params.set("original_path", `eq.${originalPath}`);
+            if (deletedAt)
+                params.set("deleted_at", `eq.${deletedAt}`);
+        }
+        else {
+            return null;
+        }
+        const res = await fetch(`${this.archivedPagesBaseUrl}?${params}`, { headers: this.headers });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.getArchivedPageForRestore failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        const row = rows[0];
+        if (!row)
+            return null;
+        return {
+            id: row.id,
+            originalPath: row.original_path ?? "",
+            originalFolder: row.original_folder ?? "",
+            title: row.title ?? "",
+            tags: row.tags ?? [],
+            content: row.content ?? "",
+            revision: row.revision ?? "",
+            sizeBytes: row.size_bytes ?? 0,
+            reason: row.reason ?? "",
+            deletedAt: row.deleted_at ?? "",
+            deletedBy: row.deleted_by ?? "",
+            restoredAt: row.restored_at ?? "",
+            restoredBy: row.restored_by ?? "",
+        };
+    }
+    async markArchivedPageRestored(archiveId, userId, restoredBy) {
+        if (!this.isConfigured())
+            return;
+        const params = new URLSearchParams();
+        params.set("id", `eq.${archiveId}`);
+        params.set("user_id", `eq.${userId}`);
+        const res = await fetch(`${this.archivedPagesBaseUrl}?${params}`, {
+            method: "PATCH",
+            headers: {
+                ...this.headers,
+                prefer: "return=minimal",
+            },
+            body: JSON.stringify({
+                restored_at: new Date().toISOString(),
+                restored_by: restoredBy,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.markArchivedPageRestored failed (${res.status}): ${await res.text()}`);
+        }
+    }
+    // ── Write operations ────────────────────────────────────────────────────────
+    /**
+     * Insert or update a page in the index.
+     * Non-blocking: callers should fire-and-forget with `.catch(() => {})`.
+     */
+    async upsertPage(name, frontmatter, content, revision, modifiedTime, userId = "", contentModifiedTime) {
+        if (!this.isConfigured())
+            return;
+        // contentModifiedTime is the semantic content-edit time (e.g. frontmatter.updated on import).
+        const contentMod = contentModifiedTime ?? modifiedTime;
+        const row = {
+            user_id: userId,
+            name,
+            title: String(frontmatter.title ?? name),
+            summary: String(frontmatter.summary ?? ""),
+            tags: normalizeTags(frontmatter.tags),
+            // Same normalization as tags: aliases are matched case-insensitively
+            // against tokenized context, so storing them lowercased keeps the
+            // comparison in one place.
+            aliases: normalizeTags(frontmatter.aliases),
+            status: String(frontmatter.status ?? "active"),
+            updated: normalizeDate(frontmatter.updated),
+            revision,
+            modified_time: modifiedTime,
+            created: contentMod,
+            modified: contentMod,
+            content,
+            access_level: typeof frontmatter.access_level === "number" ? frontmatter.access_level : 1,
+            audience: String(frontmatter.audience ?? "internal"),
+        };
+        let res;
+        try {
+            res = await fetch(this.baseUrl, {
+                method: "POST",
+                headers: {
+                    ...this.headers,
+                    prefer: "resolution=merge-duplicates,return=minimal",
+                },
+                body: JSON.stringify(row),
+            });
+        }
+        catch (err) {
+            const message = `postgresIndex.upsertPage request failed for "${name}": ${err instanceof Error ? err.message : String(err)}`;
+            console.error(message);
+            throw new Error(message);
+        }
+        if (!res.ok) {
+            const responseText = await res.text();
+            const message = `postgresIndex.upsertPage failed (${res.status}) for "${name}": ${responseText}${governanceMigrationHint(responseText)}`;
+            console.error(message);
+            throw new Error(message);
+        }
+        // Fire-and-forget embedding generation (non-blocking, same pattern as link sync).
+        if (isEmbeddingEnabled()) {
+            this.generateAndStoreEmbedding(name, row.title, row.summary, content, userId).catch((err) => {
+                console.warn(`[embeddings] Failed to embed "${name}":`, err instanceof Error ? err.message : String(err));
+            });
+        }
+    }
+    /**
+     * Conditionally update a page row only if it still has `expectedRevision`.
+     * Returns false (no throw) when the row's revision has moved or the row is
+     * gone — that's a concurrent-write signal, not an error. Used by
+     * patch_page's CAS retry loop (GH #500): unlike upsertPage's unconditional
+     * merge-duplicates upsert, this scopes the write with a `revision=eq.` filter
+     * so a concurrent writer between read and write can't be silently clobbered.
+     */
+    async casUpdatePage(name, frontmatter, content, expectedRevision, newRevision, modifiedTime, userId = "", contentModifiedTime) {
+        if (!this.isConfigured())
+            return false;
+        const contentMod = contentModifiedTime ?? modifiedTime;
+        const row = {
+            title: String(frontmatter.title ?? name),
+            summary: String(frontmatter.summary ?? ""),
+            tags: normalizeTags(frontmatter.tags),
+            aliases: normalizeTags(frontmatter.aliases),
+            status: String(frontmatter.status ?? "active"),
+            updated: normalizeDate(frontmatter.updated),
+            revision: newRevision,
+            modified_time: modifiedTime,
+            modified: contentMod,
+            content,
+            access_level: typeof frontmatter.access_level === "number" ? frontmatter.access_level : 1,
+            audience: String(frontmatter.audience ?? "internal"),
+        };
+        const params = new URLSearchParams();
+        params.set("user_id", `eq.${userId}`);
+        params.set("name", `eq.${name}`);
+        params.set("revision", `eq.${expectedRevision}`);
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}?${params}`, {
+                method: "PATCH",
+                headers: { ...this.headers, prefer: "return=representation" },
+                body: JSON.stringify(row),
+            });
+        }
+        catch (err) {
+            const message = `postgresIndex.casUpdatePage request failed for "${name}": ${err instanceof Error ? err.message : String(err)}`;
+            console.error(message);
+            throw new Error(message);
+        }
+        if (!res.ok) {
+            const responseText = await res.text();
+            const message = `postgresIndex.casUpdatePage failed (${res.status}) for "${name}": ${responseText}${governanceMigrationHint(responseText)}`;
+            console.error(message);
+            throw new Error(message);
+        }
+        const updatedRows = (await res.json());
+        const applied = updatedRows.length > 0;
+        if (applied && isEmbeddingEnabled()) {
+            this.generateAndStoreEmbedding(name, row.title, row.summary, content, userId).catch((err) => {
+                console.warn(`[embeddings] Failed to embed "${name}":`, err instanceof Error ? err.message : String(err));
+            });
+        }
+        return applied;
+    }
+    /**
+     * Insert a brand-new page row only if one doesn't already exist.
+     * Returns false (no throw) when a concurrent writer already created the
+     * row — that's the insert-side counterpart of casUpdatePage (GH #500):
+     * patch_page's "first write, no row to CAS against" branch previously fell
+     * back to upsertPage's unconditional merge-duplicates upsert, so two
+     * concurrent first writes on the same new page could silently clobber one
+     * another with no conflict ever reported. `resolution=ignore-duplicates`
+     * makes the INSERT a no-op on a (user_id, name) collision instead of
+     * merging, and `return=representation` lets us tell a real insert apart
+     * from a no-op by whether a row came back.
+     */
+    async casInsertPage(name, frontmatter, content, newRevision, modifiedTime, userId = "", contentModifiedTime) {
+        if (!this.isConfigured())
+            return false;
+        const contentMod = contentModifiedTime ?? modifiedTime;
+        const row = {
+            user_id: userId,
+            name,
+            title: String(frontmatter.title ?? name),
+            summary: String(frontmatter.summary ?? ""),
+            tags: normalizeTags(frontmatter.tags),
+            aliases: normalizeTags(frontmatter.aliases),
+            status: String(frontmatter.status ?? "active"),
+            updated: normalizeDate(frontmatter.updated),
+            revision: newRevision,
+            modified_time: modifiedTime,
+            created: contentMod,
+            modified: contentMod,
+            content,
+            access_level: typeof frontmatter.access_level === "number" ? frontmatter.access_level : 1,
+            audience: String(frontmatter.audience ?? "internal"),
+        };
+        let res;
+        try {
+            res = await fetch(this.baseUrl, {
+                method: "POST",
+                headers: {
+                    ...this.headers,
+                    prefer: "resolution=ignore-duplicates,return=representation",
+                },
+                body: JSON.stringify(row),
+            });
+        }
+        catch (err) {
+            const message = `postgresIndex.casInsertPage request failed for "${name}": ${err instanceof Error ? err.message : String(err)}`;
+            console.error(message);
+            throw new Error(message);
+        }
+        if (!res.ok) {
+            const responseText = await res.text();
+            const message = `postgresIndex.casInsertPage failed (${res.status}) for "${name}": ${responseText}${governanceMigrationHint(responseText)}`;
+            console.error(message);
+            throw new Error(message);
+        }
+        const insertedRows = (await res.json());
+        const applied = insertedRows.length > 0;
+        if (applied && isEmbeddingEnabled()) {
+            this.generateAndStoreEmbedding(name, row.title, row.summary, content, userId).catch((err) => {
+                console.warn(`[embeddings] Failed to embed "${name}":`, err instanceof Error ? err.message : String(err));
+            });
+        }
+        return applied;
+    }
+    /**
+     * Generate an embedding for a page and store it in the embedding column.
+     * Called fire-and-forget from upsertPage.
+     */
+    async generateAndStoreEmbedding(name, title, summary, content, userId = "") {
+        if (!this.isConfigured())
+            return;
+        const input = buildEmbeddingInput(title, summary, content);
+        const embedding = await generateEmbedding(input);
+        if (!embedding)
+            return;
+        await this.storeEmbedding(name, userId, embedding);
+    }
+    /**
+     * Write a pre-computed embedding vector to the pages table.
+     * Used by generateAndStoreEmbedding and the backfill script.
+     */
+    async storeEmbedding(name, userId, embedding) {
+        if (!this.isConfigured())
+            return;
+        const params = new URLSearchParams();
+        params.set("user_id", `eq.${userId}`);
+        params.set("name", `eq.${name}`);
+        const res = await fetch(`${this.baseUrl}?${params}`, {
+            method: "PATCH",
+            headers: { ...this.headers, prefer: "return=minimal" },
+            body: JSON.stringify({ embedding: `[${embedding.join(",")}]` }),
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.storeEmbedding failed (${res.status}) for "${name}": ${await res.text()}`);
+        }
+    }
+    /**
+     * Remove a page from the index by name.
+     * Non-blocking: callers should fire-and-forget with `.catch(() => {})`.
+     */
+    async deletePage(name, userId = "") {
+        if (!this.isConfigured())
+            return;
+        const url = `${this.baseUrl}?user_id=eq.${encodeURIComponent(userId)}&name=eq.${encodeURIComponent(name)}`;
+        const res = await fetch(url, {
+            method: "DELETE",
+            headers: this.headers,
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.deletePage failed (${res.status}): ${await res.text()}`);
+        }
+        await this.deleteLinksForSource(name, userId);
+    }
+    /**
+     * Remove multiple pages and their wiki_links in two batch HTTP requests per chunk.
+     * Avoids N×2 serial round-trips when purging or reconciling many rows at once.
+     */
+    async deletePages(names, userId = "") {
+        if (!this.isConfigured() || names.length === 0)
+            return;
+        const CHUNK = 100;
+        for (let i = 0; i < names.length; i += CHUNK) {
+            const chunk = names.slice(i, i + CHUNK);
+            const inClause = chunk.map(escapePostgrestLiteral).join(",");
+            const linksUrl = `${this.linksBaseUrl}?user_id=eq.${encodeURIComponent(userId)}&source=in.(${inClause})`;
+            const linksRes = await fetch(linksUrl, { method: "DELETE", headers: this.headers });
+            if (!linksRes.ok) {
+                throw new Error(`postgresIndex.deletePages links failed (${linksRes.status}): ${await linksRes.text()}`);
+            }
+            const pagesUrl = `${this.baseUrl}?user_id=eq.${encodeURIComponent(userId)}&name=in.(${inClause})`;
+            const pagesRes = await fetch(pagesUrl, { method: "DELETE", headers: this.headers });
+            if (!pagesRes.ok) {
+                throw new Error(`postgresIndex.deletePages failed (${pagesRes.status}): ${await pagesRes.text()}`);
+            }
+        }
+    }
+    async syncPageLinks(name, content, userId = "") {
+        const links = extractWikiLinks(name, content);
+        if (!this.isConfigured())
+            return { linkCount: links.length };
+        await this.deleteLinksForSource(name, userId);
+        if (links.length > 0) {
+            const rows = links.map((link) => ({
+                user_id: userId,
+                source: name,
+                target: link.target,
+                anchor_text: link.anchorText,
+                extracted_at: new Date().toISOString(),
+            }));
+            const writeRes = await fetch(this.linksBaseUrl, {
+                method: "POST",
+                headers: {
+                    ...this.headers,
+                    prefer: "resolution=merge-duplicates,return=minimal",
+                },
+                body: JSON.stringify(rows),
+            });
+            if (!writeRes.ok) {
+                throw new Error(`postgresIndex.syncPageLinks write failed (${writeRes.status}): ${await writeRes.text()}`);
+            }
+        }
+        await this.stampLinksExtractedAt(name, userId);
+        return { linkCount: links.length };
+    }
+    async getOutboundLinkCount(name, userId = "") {
+        if (!this.isConfigured())
+            return 0;
+        const params = new URLSearchParams();
+        params.set("user_id", `eq.${userId}`);
+        params.set("source", `eq.${name}`);
+        const res = await fetch(`${this.linksBaseUrl}?${params}`, {
+            method: "HEAD",
+            headers: { ...this.headers, prefer: "count=exact" },
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.getOutboundLinkCount failed (${res.status}): ${await res.text()}`);
+        }
+        const range = res.headers.get("content-range");
+        if (!range)
+            return 0;
+        const total = Number(range.split("/")[1] ?? "0");
+        return Number.isFinite(total) ? total : 0;
+    }
+    async getBacklinks(name, userId = "", accessLevel) {
+        if (!this.isConfigured())
+            return [];
+        const params = new URLSearchParams();
+        params.set("select", "source");
+        params.set("user_id", `eq.${userId}`);
+        params.set("target", `eq.${name}`);
+        params.set("order", "source.asc");
+        const res = await fetch(`${this.linksBaseUrl}?${params}`, { headers: this.headers });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.getBacklinks failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        const sources = Array.from(new Set(rows.map((row) => row.source)));
+        if (accessLevel === undefined || sources.length === 0)
+            return sources;
+        return this.filterPagesByAccessLevel(sources, userId, accessLevel);
+    }
+    async getRelatedPages(name, userId = "", accessLevel) {
+        if (!this.isConfigured())
+            return [];
+        const targetParams = new URLSearchParams();
+        targetParams.set("select", "target");
+        targetParams.set("user_id", `eq.${userId}`);
+        targetParams.set("source", `eq.${name}`);
+        const sourceRes = await fetch(`${this.linksBaseUrl}?${targetParams}`, { headers: this.headers });
+        if (!sourceRes.ok) {
+            throw new Error(`postgresIndex.getRelatedPages source failed (${sourceRes.status}): ${await sourceRes.text()}`);
+        }
+        const sourceRows = (await sourceRes.json());
+        const targets = Array.from(new Set(sourceRows.map((row) => row.target))).filter(Boolean);
+        if (targets.length === 0)
+            return [];
+        const relatedParams = new URLSearchParams();
+        relatedParams.set("select", "source,target");
+        relatedParams.set("user_id", `eq.${userId}`);
+        relatedParams.set("target", `in.(${targets.map(escapePostgrestLiteral).join(",")})`);
+        const relatedRes = await fetch(`${this.linksBaseUrl}?${relatedParams}`, { headers: this.headers });
+        if (!relatedRes.ok) {
+            throw new Error(`postgresIndex.getRelatedPages related failed (${relatedRes.status}): ${await relatedRes.text()}`);
+        }
+        const relatedRows = (await relatedRes.json());
+        // Resolve allowed sources before scoring to avoid scoring pages that will be filtered.
+        let allowed = null;
+        if (accessLevel !== undefined) {
+            const distinctSources = Array.from(new Set(relatedRows.map((r) => r.source).filter((s) => s && s !== name)));
+            allowed = distinctSources.length > 0
+                ? new Set(await this.filterPagesByAccessLevel(distinctSources, userId, accessLevel))
+                : new Set();
+        }
+        const scores = new Map();
+        for (const row of relatedRows) {
+            if (!row.source || row.source === name)
+                continue;
+            if (allowed !== null && !allowed.has(row.source))
+                continue;
+            scores.set(row.source, (scores.get(row.source) ?? 0) + 1);
+        }
+        return Array.from(scores.entries())
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .map(([source]) => source);
+    }
+    /**
+     * Filter a list of page names to only those where `access_level <= accessLevel`
+     * for the given user. Used to enforce Hive mode governance in link-graph operations.
+     * Queries the `wiki_pages` table (columns: `name`, `user_id`, `access_level`).
+     */
+    async filterPagesByAccessLevel(names, userId, accessLevel) {
+        if (names.length === 0)
+            return [];
+        const params = new URLSearchParams();
+        params.set("select", "name");
+        params.set("user_id", `eq.${userId}`);
+        params.set("name", `in.(${names.map(escapePostgrestLiteral).join(",")})`);
+        params.set("access_level", `lte.${accessLevel}`);
+        const res = await fetch(`${this.baseUrl}?${params}`, { headers: this.headers });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.filterPagesByAccessLevel failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        return rows.map((r) => r.name);
+    }
+    async extractLinksForStalePages(filter) {
+        if (!this.isConfigured())
+            return { pagesProcessed: 0, linksExtracted: 0 };
+        const tags = (filter.tags ?? [])
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0)
+            .map(validateTagFilter);
+        const folder = filter.folder?.trim();
+        if (tags.length === 0 && !folder) {
+            throw new Error("At least one filter is required: tags or folder");
+        }
+        const params = new URLSearchParams();
+        params.set("select", "name,modified_time,links_extracted_at");
+        params.set("user_id", `eq.${filter.userId ?? ""}`);
+        params.set("order", "modified_time.desc");
+        if (folder) {
+            params.set("name", `like.${escapeLikePattern(folder)}%`);
+        }
+        if (tags.length === 1) {
+            params.set("tags", `cs.{${tags[0]}}`);
+        }
+        else if (tags.length > 1) {
+            params.set("or", `(${tags.map((tag) => `tags.cs.{${tag}}`).join(",")})`);
+        }
+        const pagesRes = await fetch(`${this.baseUrl}?${params}`, { headers: this.headers });
+        if (!pagesRes.ok) {
+            throw new Error(`postgresIndex.extractLinksForStalePages list failed (${pagesRes.status}): ${await pagesRes.text()}`);
+        }
+        const rows = (await pagesRes.json());
+        const staleNames = rows.filter((row) => {
+            const extractedAt = row.links_extracted_at ? Date.parse(row.links_extracted_at) : Number.NaN;
+            const modifiedAt = row.modified_time ? Date.parse(row.modified_time) : Number.NaN;
+            if (!Number.isFinite(extractedAt))
+                return true;
+            if (!Number.isFinite(modifiedAt))
+                return false;
+            return extractedAt < modifiedAt;
+        }).map((row) => row.name);
+        let pagesProcessed = 0;
+        let linksExtracted = 0;
+        for (const name of staleNames) {
+            const content = await this.fetchPageContent(name, filter.userId ?? "");
+            const result = await this.syncPageLinks(name, content, filter.userId ?? "");
+            pagesProcessed += 1;
+            linksExtracted += result.linkCount;
+        }
+        return { pagesProcessed, linksExtracted };
+    }
+    async deleteLinksForSource(name, userId = "") {
+        if (!this.isConfigured())
+            return;
+        const url = `${this.linksBaseUrl}?user_id=eq.${encodeURIComponent(userId)}&source=eq.${encodeURIComponent(name)}`;
+        const res = await fetch(url, {
+            method: "DELETE",
+            headers: this.headers,
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.deleteLinksForSource failed (${res.status}): ${await res.text()}`);
+        }
+    }
+    async stampLinksExtractedAt(name, userId = "") {
+        const params = new URLSearchParams();
+        params.set("user_id", `eq.${userId}`);
+        params.set("name", `eq.${name}`);
+        const res = await fetch(`${this.baseUrl}?${params}`, {
+            method: "PATCH",
+            headers: {
+                ...this.headers,
+                prefer: "return=minimal",
+            },
+            body: JSON.stringify({ links_extracted_at: new Date().toISOString() }),
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.stampLinksExtractedAt failed (${res.status}): ${await res.text()}`);
+        }
+    }
+    async fetchPageContent(name, userId = "") {
+        const params = new URLSearchParams();
+        params.set("select", "content");
+        params.set("user_id", `eq.${userId}`);
+        params.set("name", `eq.${name}`);
+        const res = await fetch(`${this.baseUrl}?${params}`, { headers: this.headers });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.fetchPageContent failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        if (rows.length === 0)
+            return "";
+        return rows[0].content ?? "";
+    }
+    /**
+     * Read a single page row from the DB for the hot path (read_page, patch_page).
+     * Returns null when not configured, row not found, or on any error so the
+     * caller can fall back to Supabase Storage transparently.
+     */
+    async fetchPageRow(name, userId = "") {
+        if (!this.isConfigured())
+            return null;
+        const params = new URLSearchParams();
+        params.set("select", "content,revision,modified_time");
+        params.set("user_id", `eq.${userId}`);
+        params.set("name", `eq.${name}`);
+        const res = await fetch(`${this.baseUrl}?${params}`, { headers: this.headers });
+        if (!res.ok)
+            return null;
+        const rows = (await res.json());
+        if (rows.length === 0)
+            return null;
+        const row = rows[0];
+        if (typeof row.content !== "string")
+            return null;
+        return {
+            fileId: name,
+            name,
+            content: row.content,
+            revision: row.revision ?? "",
+            modifiedTime: row.modified_time ?? new Date().toISOString(),
+        };
+    }
+    // ── Read operations ──────────────────────────────────────────────────────────
+    /**
+     * List all pages, with optional tag and status filters.
+     * Returns lightweight entries — no content.
+     */
+    async listPages(options = {}) {
+        const ownRows = await this.listPagesSingleScope(options);
+        if (!options.grantScopes || options.grantScopes.length === 0)
+            return ownRows;
+        const grantRowsArrays = await Promise.all(options.grantScopes.map((scope) => this.listPagesSingleScope({ ...options, userId: scope.userId, pathPrefix: scope.folder, grantScopes: undefined })));
+        const seen = new Set(ownRows.map((r) => r.name));
+        const merged = [...ownRows];
+        for (const rows of grantRowsArrays) {
+            for (const r of rows) {
+                if (seen.has(r.name))
+                    continue;
+                seen.add(r.name);
+                merged.push(r);
+            }
+        }
+        merged.sort((a, b) => (b.modified || "").localeCompare(a.modified || ""));
+        // Best-effort bound for the grant-scoped merge: each sub-scope query is independently
+        // limited/offset, so exact pagination across scopes isn't guaranteed — but the final
+        // response is still capped at `limit` so a caller can never get more than they asked for.
+        return options.limit !== undefined ? merged.slice(0, options.limit) : merged;
+    }
+    async listPagesSingleScope(options = {}) {
+        if (!this.isConfigured())
+            return [];
+        const params = new URLSearchParams();
+        params.set("select", options.compact ? "name,modified,revision" : "name,title,summary,updated,status,tags,created,modified,revision");
+        // Secondary sort on `name` breaks ties deterministically — without it, rows sharing
+        // the same `modified` timestamp (common for bulk imports) can be returned in a
+        // different relative order across separate limit/offset queries, causing a page's
+        // tail to duplicate the next page's head (or, symmetrically, drop a row entirely).
+        // Reproduced on staging: a folder-scoped walk over 847 pages hit the same duplicate
+        // at the same offset boundary across repeated runs.
+        params.set("order", "modified.desc.nullslast,name.asc");
+        params.set("user_id", `eq.${options.userId ?? ""}`);
+        if (options.status) {
+            params.set("status", `eq.${options.status}`);
+        }
+        if (options.tag) {
+            params.set("tags", `cs.{${options.tag}}`);
+        }
+        if (options.accessLevel !== undefined) {
+            params.set("access_level", `lte.${options.accessLevel}`);
+        }
+        if (options.changedAfter) {
+            params.set("modified", `gt.${options.changedAfter}`);
+        }
+        // Exclude version-history snapshots (page-versions/* are internal — not current pages).
+        params.append("name", "not.like.page-versions/%");
+        // Exclude system files at the query level, not after fetching — doing this
+        // client-side after limit/offset silently shrinks a page and desyncs the
+        // pagination window (a page could return fewer than `limit` rows without
+        // signaling it, and the next offset would skip or duplicate rows).
+        params.append("name", "not.in.(index.md,log.md)");
+        if (options.pathPrefix) {
+            params.append("name", `like.${escapeLikePattern(options.pathPrefix)}/%`);
+        }
+        if (options.folder) {
+            params.append("name", `like.${escapeLikePattern(options.folder)}/%`);
+        }
+        if (options.limit !== undefined) {
+            params.set("limit", String(options.limit));
+        }
+        if (options.offset) {
+            params.set("offset", String(options.offset));
+        }
+        const url = `${this.baseUrl}?${params}`;
+        const res = await fetch(url, {
+            headers: { ...this.headers, prefer: "return=representation" },
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.listPages failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        return rows.map((r) => ({
+            name: r.name,
+            title: r.title || r.name,
+            summary: r.summary || "",
+            updated: r.updated ?? "",
+            status: r.status || "active",
+            tags: r.tags ?? [],
+            created: r.created ?? "",
+            modified: r.modified ?? "",
+            ...(r.revision ? { revision: r.revision } : {}),
+        }));
+    }
+    /**
+     * Targeted existence check for health_check's taxonomy verification — point
+     * lookups instead of diffing against a bulk listPages() fetch. A bulk fetch
+     * ordered by modified.desc is bounded by PostgREST's default row cap, so on
+     * wikis past ~1000 pages, old/rarely-touched seed pages silently age out of
+     * the window and false-flag as "missing" (see GH #358). Point lookups by
+     * exact name / folder prefix are correct regardless of wiki size.
+     *
+     * Checks both the clean name and the legacy `users/<userId>/`-prefixed
+     * variant some accounts have from an older populate script, matching the
+     * normalization the bulk-fetch approach used to do.
+     */
+    async checkTaxonomy(userId, requiredSeedPages, requiredFolders) {
+        if (!this.isConfigured() || !userId) {
+            return { missingSeedPages: [...requiredSeedPages], missingFolders: [...requiredFolders] };
+        }
+        const legacyPrefix = `users/${userId}/`;
+        const presentSeedPageNames = async () => {
+            if (requiredSeedPages.length === 0)
+                return new Set();
+            const candidates = requiredSeedPages.flatMap((p) => [p, `${legacyPrefix}${p}`]);
+            const params = new URLSearchParams();
+            params.set("select", "name");
+            params.set("user_id", `eq.${userId}`);
+            params.set("name", `in.(${candidates.map(escapePostgrestLiteral).join(",")})`);
+            const res = await fetch(`${this.baseUrl}?${params}`, { headers: this.headers });
+            if (!res.ok)
+                return new Set();
+            const rows = (await res.json());
+            return new Set(rows.map((r) => r.name));
+        };
+        const folderHasPages = async (folder) => {
+            const params = new URLSearchParams();
+            params.set("select", "name");
+            params.set("user_id", `eq.${userId}`);
+            params.set("or", `(name.like.${escapeLikePattern(folder)}/%,name.like.${escapeLikePattern(legacyPrefix + folder)}/%)`);
+            params.set("limit", "1");
+            const res = await fetch(`${this.baseUrl}?${params}`, { headers: this.headers });
+            if (!res.ok)
+                return false;
+            const rows = (await res.json());
+            return rows.length > 0;
+        };
+        const [presentNames, folderResults] = await Promise.all([
+            presentSeedPageNames(),
+            Promise.all(requiredFolders.map((f) => folderHasPages(f))),
+        ]);
+        const missingSeedPages = requiredSeedPages.filter((p) => !presentNames.has(p) && !presentNames.has(`${legacyPrefix}${p}`));
+        const missingFolders = requiredFolders.filter((_, i) => !folderResults[i]);
+        return { missingSeedPages, missingFolders };
+    }
+    /**
+     * Full-text search using Postgres tsvector / tsquery.
+     * Returns ranked results compatible with IndexedSearchResponse.
+     */
+    async search(options) {
+        const ownResult = await this.searchSingleScope(options);
+        if (!options.grantScopes || options.grantScopes.length === 0)
+            return ownResult;
+        const scopedResults = await Promise.all(options.grantScopes.map((scope) => this.searchSingleScope({ ...options, userId: scope.userId, folder: scope.folder, grantScopes: undefined })));
+        const seen = new Set(ownResult.results.map((r) => r.name));
+        const merged = [...ownResult.results];
+        let totalMatches = ownResult.totalMatches;
+        let candidateCount = ownResult.candidateCount;
+        for (const r of scopedResults) {
+            totalMatches += r.totalMatches;
+            candidateCount += r.candidateCount;
+            for (const item of r.results) {
+                if (seen.has(item.name))
+                    continue;
+                seen.add(item.name);
+                merged.push(item);
+            }
+        }
+        return {
+            results: merged.slice(0, options.maxResults),
+            totalMatches,
+            candidateCount,
+            queryMs: ownResult.queryMs,
+        };
+    }
+    async searchSingleScope(options) {
+        const queryStart = Date.now();
+        if (!this.isConfigured()) {
+            return { results: [], totalMatches: 0, candidateCount: 0, queryMs: 0 };
+        }
+        const q = options.query.trim();
+        if (!q) {
+            return { results: [], totalMatches: 0, candidateCount: 0, queryMs: Date.now() - queryStart };
+        }
+        const tsquery = toTsQuery(q);
+        // AND-first for precision.
+        let rows = await this.runFtsQuery(tsquery, options);
+        // OR fallback: if the AND query returns nothing and there is more than one
+        // content token, retry with OR so that verbose natural-language questions
+        // still surface documents that contain some—but not all—of the query words.
+        // The ranked RPC orders by ts_rank in-DB; when it is unavailable we pull a
+        // wider pool with content and pass orTokens so runFtsQuery re-ranks by
+        // term overlap (the REST filter falls back to recency order).
+        const rawTokens = tokenizeQuery(q);
+        let usedOrFallback = false;
+        if (rows.length === 0 && rawTokens.length > 1) {
+            rows = await this.runFtsQuery(toTsQuery(q, "OR"), options, {
+                withContent: true,
+                candidateLimit: Math.min(options.maxResults * 10, 200),
+                orTokens: stripStopwords(rawTokens),
+            });
+            usedOrFallback = rows.length > 0;
+        }
+        // usedOrFallback is a query-level flag, not a per-row one: the OR fallback
+        // replaces the entire AND result set, so every row in `rows` here came
+        // from the same (fallback or not) query and shares the same flag value.
+        const results = rows.slice(0, options.maxResults).map((r) => ({
+            name: r.name,
+            title: r.title || r.name,
+            summary: r.summary || "",
+            updated: r.updated ?? "",
+            matchedOn: computeMatchedOn(r, q),
+            ...(usedOrFallback ? { fallback: "or" } : {}),
+        }));
+        return {
+            results,
+            totalMatches: rows.length,
+            candidateCount: rows.length,
+            queryMs: Date.now() - queryStart,
+        };
+    }
+    async runFtsQuery(tsquery, options, opts = {}) {
+        if (!tsquery)
+            return [];
+        const candidateLimit = opts.candidateLimit ?? Math.min(options.maxResults * 3, 500);
+        // Prefer the relevance-ordered RPC (ts_rank in-DB). Returns null when the
+        // function isn't deployed, so older deployments fall back transparently.
+        const ranked = await this.runRankedQuery(tsquery, options, candidateLimit);
+        if (ranked !== null)
+            return ranked;
+        // Fallback: PostgREST FTS filter (fts_vector=fts.tsquery), recency-ordered.
+        const params = new URLSearchParams();
+        // content is fetched only when we need to re-rank client-side (OR fallback).
+        params.set("select", `name,title,summary,updated,modified,tags${opts.withContent ? ",content" : ""}`);
+        params.set("fts_vector", `fts.${tsquery}`);
+        params.set("user_id", `eq.${options.userId ?? ""}`);
+        params.set("limit", String(candidateLimit));
+        params.set("order", "modified.desc.nullslast");
+        if (options.tag) {
+            params.set("tags", `cs.{${options.tag}}`);
+        }
+        if (options.accessLevel !== undefined) {
+            params.set("access_level", `lte.${options.accessLevel}`);
+        }
+        if (options.folder) {
+            params.append("name", `like.${escapeLikePattern(options.folder)}/%`);
+        }
+        // Exclude version-history snapshots — same exclusion as listPagesSingleScope.
+        params.append("name", "not.like.page-versions/%");
+        const url = `${this.baseUrl}?${params}`;
+        const res = await fetch(url, {
+            headers: { ...this.headers, prefer: "return=representation" },
+        });
+        if (!res.ok) {
+            throw new Error(`postgresIndex.search query failed (${res.status}): ${await res.text()}`);
+        }
+        const rows = (await res.json());
+        // No in-DB ranking available — re-rank the recency-ordered pool by overlap
+        // when the caller is the OR fallback (orTokens supplied).
+        return opts.orTokens ? rankByOverlap(rows, opts.orTokens) : rows;
+    }
+    /**
+     * Relevance-ordered FTS via the search_pages_ranked RPC (orders by ts_rank in
+     * Postgres). Returns null when the function isn't deployed (PGRST202 / 404) so
+     * the caller can fall back to the REST filter.
+     */
+    async runRankedQuery(tsquery, options, limit) {
+        const params = new URLSearchParams();
+        params.set("select", "name,title,summary,updated,modified,tags");
+        const body = {
+            p_user_id: options.userId ?? "",
+            p_tsquery: tsquery,
+            p_limit: limit,
+            p_access_level: options.accessLevel ?? null,
+            p_tag: options.tag ?? null,
+            p_folder: options.folder ?? null,
+        };
+        let res;
+        try {
+            res = await fetch(`${this.supabaseUrl}/rest/v1/rpc/search_pages_ranked?${params}`, {
+                method: "POST",
+                headers: { ...this.headers, prefer: "return=representation" },
+                body: JSON.stringify(body),
+            });
+        }
+        catch {
+            return null; // network/abort — let the REST filter path try.
+        }
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            const text = await res.text();
+            if (/PGRST202|could not find the function|does not exist/i.test(text))
+                return null;
+            throw new Error(`postgresIndex.search ranked query failed (${res.status}): ${text}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Re-trigger the FTS update trigger for all rows where fts_vector is NULL.
+     * Needed when rows were inserted before the trigger was applied (e.g. after a
+     * Supabase project migration).  Safe to call multiple times — a second call is
+     * a no-op because no null rows remain.
+     */
+    async reindexFts(userId) {
+        if (!this.isConfigured())
+            return { updated: 0 };
+        // Count rows with null fts_vector.
+        const countParams = new URLSearchParams({ select: "name" });
+        countParams.set("fts_vector", "is.null");
+        if (userId !== undefined)
+            countParams.set("user_id", `eq.${userId}`);
+        const countRes = await fetch(`${this.baseUrl}?${countParams}`, {
+            method: "HEAD",
+            headers: { ...this.headers, prefer: "count=exact" },
+        });
+        if (!countRes.ok) {
+            throw new Error(`reindexFts count failed (${countRes.status}): ${await countRes.text()}`);
+        }
+        const range = countRes.headers.get("content-range");
+        const nullCount = range ? parseInt(range.split("/")[1] ?? "0", 10) : 0;
+        if (!Number.isFinite(nullCount) || nullCount <= 0)
+            return { updated: 0 };
+        // PATCH those rows — the BEFORE UPDATE trigger recomputes fts_vector from
+        // the existing title/summary/tags/content columns.
+        const patchParams = new URLSearchParams();
+        patchParams.set("fts_vector", "is.null");
+        if (userId !== undefined)
+            patchParams.set("user_id", `eq.${userId}`);
+        const patchRes = await fetch(`${this.baseUrl}?${patchParams}`, {
+            method: "PATCH",
+            headers: { ...this.headers, prefer: "return=minimal" },
+            body: JSON.stringify({ fts_vector: null }),
+        });
+        if (!patchRes.ok) {
+            throw new Error(`reindexFts patch failed (${patchRes.status}): ${await patchRes.text()}`);
+        }
+        return { updated: nullCount };
+    }
+    /**
+     * Score-based hybrid retrieval: FTS (weight 0.3) + vector cosine similarity (weight 0.7).
+     * Calls the search_pages_hybrid stored function deployed by embedding-migration.sql.
+     * Returns null when the function isn't deployed or embedding is unavailable.
+     */
+    async searchHybrid(options) {
+        if (!this.isConfigured())
+            return null;
+        if (!isEmbeddingEnabled())
+            return null;
+        const q = options.query.trim();
+        if (!q)
+            return null;
+        const embedding = await generateEmbedding(q);
+        if (!embedding)
+            return null;
+        const queryStart = Date.now();
+        const body = {
+            query_text: q,
+            query_embedding: `[${embedding.join(",")}]`,
+            p_user_id: options.userId ?? "",
+            p_max_results: options.maxResults,
+            p_fts_weight: 0.3,
+            p_vec_weight: 0.7,
+            p_access_level: options.accessLevel ?? null,
+            p_tag: options.tag ?? null,
+        };
+        let res;
+        try {
+            res = await fetch(`${this.supabaseUrl}/rest/v1/rpc/search_pages_hybrid`, {
+                method: "POST",
+                headers: { ...this.headers, "content-type": "application/json", prefer: "return=representation" },
+                body: JSON.stringify(body),
+            });
+        }
+        catch {
+            return null;
+        }
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            const text = await res.text();
+            if (/PGRST202|could not find the function|does not exist/i.test(text))
+                return null;
+            throw new Error(`postgresIndex.searchHybrid failed (${res.status}): ${text}`);
+        }
+        const rows = (await res.json());
+        const results = rows.map((r) => ({
+            name: r.name,
+            title: r.title || r.name,
+            summary: r.summary || "",
+            updated: r.updated ?? "",
+            // search_pages_hybrid doesn't return tags, so this synthetic FtsRow always
+            // has tags: [] — hybrid matchedOn can never include "tags". Intentional,
+            // not an oversight, until the RPC is extended to select tags.
+            matchedOn: computeMatchedOn({ name: r.name, title: r.title, summary: r.summary, updated: r.updated, modified: null, tags: [] }, q),
+            hybridScore: r.hybrid_score,
+            ftsScore: r.fts_score,
+            vecScore: r.vec_score,
+        }));
+        return {
+            results,
+            totalMatches: results.length,
+            queryMs: Date.now() - queryStart,
+            backend: "postgres-hybrid",
+        };
+    }
+    /** No-op: connection is stateless (each call is an independent HTTP request). */
+    close() {
+        // nothing to do
+    }
+}
+function normalizeTags(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((t) => String(t).trim().toLowerCase())
+        .filter((t) => t.length > 0);
+}
+// gray-matter parses bare YAML dates (`updated: 2026-04-13`) into JS Date objects.
+// Postgres `date` columns reject `Date.toString()` output ("Mon Apr 13 2026 …"),
+// so coerce to ISO YYYY-MM-DD here. Strings already in that form pass through;
+// anything unparseable becomes null.
+function normalizeDate(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (raw instanceof Date) {
+        return Number.isNaN(raw.getTime()) ? null : raw.toISOString().slice(0, 10);
+    }
+    const s = String(raw).trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(s))
+        return s;
+    const parsed = new Date(s);
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString().slice(0, 10);
+}
+/**
+ * Low-signal English stopwords. Dropped before building the tsquery so that
+ * verbose natural-language questions ("I'm checking our previous chat about…")
+ * don't force every filler word into the match — they bloat the AND query into
+ * a guaranteed miss and flood the OR fallback with noise.
+ */
+const STOPWORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "been", "but", "by", "can", "could",
+    "did", "do", "does", "for", "from", "had", "has", "have", "how", "i", "if", "im",
+    "in", "into", "is", "it", "its", "just", "me", "my", "of", "on", "or", "our",
+    "previous", "remind", "should", "so", "some", "that", "the", "their", "them",
+    "then", "there", "these", "this", "to", "us", "was", "we", "were", "what", "when",
+    "where", "which", "who", "why", "will", "with", "would", "you", "your",
+]);
+/** Lowercase, strip punctuation, split into tokens. */
+export function tokenizeQuery(query) {
+    return query
+        .toLowerCase()
+        .split(/\s+/)
+        .map((t) => t.replace(/[^\p{L}\p{N}_-]/gu, "").trim())
+        .filter((t) => t.length > 0);
+}
+/** Drop stopwords — but never return empty (keep originals if all were stopwords). */
+export function stripStopwords(tokens) {
+    const kept = tokens.filter((t) => !STOPWORDS.has(t));
+    return kept.length > 0 ? kept : tokens;
+}
+/** Below this length a token is too short for word-boundary matching to be a useful signal (e.g. "is", "or"). */
+const MIN_MATCH_TOKEN_LENGTH = 3;
+/**
+ * Tokens usable for a *matched-on* relevance signal: stopwords and sub-3-char
+ * tokens excluded, since both produce false-positive substring hits (e.g. the
+ * stopword "is" or "or" appearing inside "History"/"Editor").
+ */
+export function matchableTokens(query) {
+    return stripStopwords(tokenizeQuery(query)).filter((t) => t.length >= MIN_MATCH_TOKEN_LENGTH);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Prefix match on a word boundary (mirrors the `token:*` prefix semantics used
+ * in the tsquery builder below) — not a bare substring test. Prevents a token
+ * like "type" from being credited for matching inside "stereotype".
+ */
+export function tokenMatchesText(text, token) {
+    return new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegExp(token)}`, "iu").test(text);
+}
+/**
+ * Convert a plain-text query string into a Postgres tsquery expression.
+ * Tokens are joined with prefix matching (`:*`) using the given operator.
+ *
+ * AND (default) keeps **every** token for precision — dropping stopwords here
+ * broadens the match and lets a competing doc outrank the true one under the
+ * recency ordering. OR drops stopwords, since the broad fallback shouldn't be
+ * dominated by filler words like "the"/"our".
+ */
+function toTsQuery(query, operator = "AND") {
+    const all = tokenizeQuery(query);
+    const tokens = operator === "OR" ? stripStopwords(all) : all;
+    if (tokens.length === 0)
+        return "";
+    const sep = operator === "AND" ? " & " : " | ";
+    return tokens.map((t) => `${t}:*`).join(sep);
+}
+/**
+ * Relevance score for the OR fallback: how many distinct query tokens appear in
+ * the row's searchable text. PostgREST can only order by columns (not by
+ * ts_rank without an RPC), so the OR fetch comes back ordered by recency; we
+ * re-rank here so the document matching the most query terms surfaces first
+ * instead of merely the most recently modified one.
+ */
+function overlapScore(row, tokens) {
+    const hay = `${row.title ?? ""} ${row.summary ?? ""} ${(row.tags ?? []).join(" ")} ${row.content ?? ""}`.toLowerCase();
+    let score = 0;
+    for (const t of tokens)
+        if (hay.includes(t))
+            score++;
+    return score;
+}
+/** Stable sort by descending term-overlap; ties keep the incoming (recency) order. */
+export function rankByOverlap(rows, tokens) {
+    return rows
+        .map((row, i) => ({ row, i, score: overlapScore(row, tokens) }))
+        .sort((a, b) => b.score - a.score || a.i - b.i)
+        .map((x) => x.row);
+}
+/**
+ * Per-token field match, not whole-query substring — a multi-word query like
+ * "Lake Garnett event date" must match token-by-token, since it will almost
+ * never appear verbatim in a title/tag/summary even on a real hit.
+ */
+function computeMatchedOn(row, query) {
+    const tokens = matchableTokens(query);
+    const title = row.title?.toLowerCase() ?? "";
+    const summary = row.summary?.toLowerCase() ?? "";
+    const tags = row.tags ?? [];
+    const matched = new Set();
+    for (const t of tokens) {
+        if (tokenMatchesText(title, t))
+            matched.add("title");
+        if (tags.some((tag) => tokenMatchesText(tag.toLowerCase(), t)))
+            matched.add("tags");
+        if (tokenMatchesText(summary, t))
+            matched.add("summary");
+    }
+    return [...matched];
+}
+function governanceMigrationHint(responseText) {
+    if (!/\b(access_level|audience)\b/i.test(responseText))
+        return "";
+    return " Ensure scripts/governance-migration.sql has been applied.";
+}
+function escapePostgrestLiteral(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function escapeLikePattern(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/%/g, "\\%")
+        .replace(/_/g, "\\_")
+        .replace(/\*/g, "\\*");
+}
+function validateTagFilter(value) {
+    if (/[{},()]/.test(value)) {
+        throw new Error("Tag filters cannot contain '{', '}', ',', '(' or ')' characters.");
+    }
+    return value;
+}
+//# sourceMappingURL=postgresIndex.js.map