@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/_internal/server/features/search/index-build/artifact-store.d.ts

@@ -0,0 +1,89 @@
+import type { SearchIndexArtifact } from "../../../../shared/search/index-record";
+import type { Firestore } from "firebase-admin/firestore";
+import type { Bucket } from "@google-cloud/storage";
+export declare const SEARCH_INDEX_COLLECTION = "searchIndex";
+export declare const SEARCH_INDEX_MANIFEST_ID = "manifest";
+/**
+ * 🛑 A declared ceiling, and the build FAILS rather than truncating.
+ *
+ * Deliberately the opposite of `buildSearchTxt`'s `MAX_TOKENS`, which this
+ * codebase complains about in four separate places for silently slicing. A
+ * short artifact is a search index missing rows, and nothing downstream can
+ * tell that from a small catalogue. 1.5 MB against a measured 384 KB leaves
+ * roughly 4x headroom; if it is ever hit, that is a real signal.
+ */
+export declare const SEARCH_INDEX_MAX_BYTES = 1500000;
+export interface SearchIndexManifest {
+    schema: number;
+    version: number;
+    builtAt: string;
+    lastFullAt: string | null;
+    storagePath: string;
+    recordCount: number;
+    bytes: number;
+    perType: Record<string, number>;
+    /** Set by the content triggers; cleared when a build consumes it. */
+    dirty: boolean;
+}
+type ManifestDb = Firestore;
+type StorageBucket = Bucket;
+export declare function manifestRef(db: ManifestDb): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+export declare function readManifest(db: ManifestDb): Promise<SearchIndexManifest | null>;
+/**
+ * Mark the index stale. Called from the content triggers.
+ *
+ * 🛑 READ-THEN-WRITE, guarding on a BOOLEAN — never a deep compare.
+ * Root Cause #92's trigger cost 12 million invocations a day because its
+ * no-op guard used `JSON.stringify`, which is key-order sensitive and so
+ * never matched. A boolean cannot have that failure mode, and the read means
+ * a burst of 50 product writes costs 50 reads and exactly ONE write.
+ *
+ * Never throws: a failed dirty-mark delays the index by one cadence, and
+ * failing the product write that triggered it would be far worse.
+ */
+export declare function markSearchIndexDirty(db: ManifestDb, job: string): Promise<void>;
+export declare function storagePathFor(version: number): string;
+export interface PublishResult {
+    storagePath: string;
+    bytes: number;
+    pruned: number;
+}
+/**
+ * Write the artifact and prune older versions.
+ *
+ * The object carries `public, max-age=31536000, immutable` because the URL
+ * contains the version — a new build is a new URL, so nothing ever needs
+ * revalidating.
+ */
+export declare function publishArtifact(bucket: StorageBucket, artifact: SearchIndexArtifact): Promise<PublishResult>;
+/**
+ * Mirror the manifest to Storage so the client needs no Firebase SDK.
+ *
+ * Writes only the four fields a browser has any business reading — `dirty`,
+ * `lastFullAt` and `perType` are build bookkeeping, and publishing "the index
+ * is currently stale" to every visitor tells them nothing they can act on.
+ * The shape is `SearchIndexManifestPublic`, declared beside the URL builders.
+ *
+ * ## 🛑 60 seconds, and the number is load-bearing in both directions
+ *
+ * This is the ONLY uncacheable-for-long hop in the whole design, so it sets
+ * the floor on how fast a new build reaches a visitor — and the ceiling on
+ * how often a returning visitor pays for a request. The artifact behind it is
+ * `immutable`, so a client that re-reads the manifest and finds the same
+ * version does one small conditional fetch and no download at all.
+ *
+ * Too long and the 15-minute build cadence is a lie; too short and every
+ * visitor re-requests it per page view for a document that changes a few
+ * times an hour.
+ *
+ * ## Written LAST, and failing it does not fail the build
+ *
+ * A published artifact with a stale manifest serves the previous index for up
+ * to a minute — correct, just behind. A manifest pointing at an artifact that
+ * was never written is a 404 on the client's critical path. So the order is
+ * artifact, then Firestore, then this; and a throw here is logged, not
+ * propagated, because the Firestore manifest (which is what the NEXT build
+ * reads) is already correct by this point.
+ */
+export declare function publishManifestMirror(bucket: StorageBucket, manifest: SearchIndexManifest): Promise<void>;
+export {};

package/dist/_internal/server/features/search/index-build/artifact-store.js

@@ -0,0 +1,208 @@
+/*
+ * WHY: Where the search artifact lives, and how it is served without a
+ *      Next.js route in front of it.
+ * WHAT: The Firestore manifest singleton, the Storage upload, and the prune.
+ *
+ * ## Why Storage directly rather than an /api route
+ *
+ * A version-addressed object written with `immutable` cache headers is served
+ * by the browser and any CDN in front of the bucket with no function in the
+ * path at all. `storage.rules` is already `allow read: if true` for every
+ * object, so no rules change is needed.
+ *
+ * It is also the only shape that can be deployed AND verified under this
+ * round's constraint of no Vercel deploy: the Function writes the artifact and
+ * it is immediately fetchable. A same-origin `/api/search-index/*` proxy stays
+ * a documented fallback if CORS or egress accounting later argues for it — it
+ * would change the two URLs and nothing else.
+ *
+ * ## 🛑 Old versions MUST be pruned
+ *
+ * Immutable version-addressed objects never overwrite, so without a prune this
+ * accumulates ~384 KB per content change, for ever, against a ~5 GB allowance
+ * the media library already shares. Two versions are kept — the current one
+ * and the one it replaced — so a client that fetched mid-publish is never
+ * orphaned, matching the service worker's `maxEntries: 2`.
+ *
+ * @tag domain:search
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:searchIndexBuild
+ * @tag sideEffects:firestore,storage
+ */
+import { normalizeError } from "../../../../../errors/normalize.js";
+import { serverLogger } from "../../../../../monitoring/server-logger.js";
+import { SEARCH_INDEX_PREFIX, SEARCH_MANIFEST_OBJECT, searchIndexObjectPath, } from "../../../../shared/search/artifact-url.js";
+export const SEARCH_INDEX_COLLECTION = "searchIndex";
+export const SEARCH_INDEX_MANIFEST_ID = "manifest";
+/*
+ * 🛑 `SEARCH_INDEX_PREFIX` and the object paths are IMPORTED, not declared
+ * here. They were declared here first, and the client then needed the same
+ * two strings — which is a mirror, and a mirror of a URL fails in the worst
+ * available way: the builder writes `search-index/v4.json`, the client asks
+ * for `searchIndex/v4.json`, and a 404 is indistinguishable from "the index
+ * has not been built yet" (Root Cause #42). One declaration, in the shared
+ * module both sides already import.
+ */
+/** Current + previous. See the prune note in the header. */
+const KEEP_VERSIONS = 2;
+/**
+ * 🛑 A declared ceiling, and the build FAILS rather than truncating.
+ *
+ * Deliberately the opposite of `buildSearchTxt`'s `MAX_TOKENS`, which this
+ * codebase complains about in four separate places for silently slicing. A
+ * short artifact is a search index missing rows, and nothing downstream can
+ * tell that from a small catalogue. 1.5 MB against a measured 384 KB leaves
+ * roughly 4x headroom; if it is ever hit, that is a real signal.
+ */
+export const SEARCH_INDEX_MAX_BYTES = 1500000;
+export function manifestRef(db) {
+    return db.collection(SEARCH_INDEX_COLLECTION).doc(SEARCH_INDEX_MANIFEST_ID);
+}
+export async function readManifest(db) {
+    const snap = await manifestRef(db).get();
+    if (!snap.exists)
+        return null;
+    /*
+     * Firestore hands back `DocumentData`, which is `Record<string, any>` — the
+     * one place a cast is unavoidable, because the SDK cannot know the shape.
+     * Narrowed to the declared interface at the single read site rather than
+     * left as `DocumentData` for callers to re-cast: the latter is how a
+     * boundary type spreads (Root Cause #98).
+     */
+    return snap.data() ?? null;
+}
+/**
+ * Mark the index stale. Called from the content triggers.
+ *
+ * 🛑 READ-THEN-WRITE, guarding on a BOOLEAN — never a deep compare.
+ * Root Cause #92's trigger cost 12 million invocations a day because its
+ * no-op guard used `JSON.stringify`, which is key-order sensitive and so
+ * never matched. A boolean cannot have that failure mode, and the read means
+ * a burst of 50 product writes costs 50 reads and exactly ONE write.
+ *
+ * Never throws: a failed dirty-mark delays the index by one cadence, and
+ * failing the product write that triggered it would be far worse.
+ */
+export async function markSearchIndexDirty(db, job) {
+    try {
+        const ref = manifestRef(db);
+        const snap = await ref.get();
+        if (snap.exists && snap.data()?.dirty === true)
+            return;
+        await ref.set({ dirty: true }, { merge: true });
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("markSearchIndexDirty failed (non-fatal)", { job, message: e.message });
+    }
+}
+export function storagePathFor(version) {
+    return searchIndexObjectPath(version);
+}
+/**
+ * Write the artifact and prune older versions.
+ *
+ * The object carries `public, max-age=31536000, immutable` because the URL
+ * contains the version — a new build is a new URL, so nothing ever needs
+ * revalidating.
+ */
+export async function publishArtifact(bucket, artifact) {
+    const body = Buffer.from(JSON.stringify(artifact), "utf8");
+    if (body.byteLength > SEARCH_INDEX_MAX_BYTES) {
+        // Loud, not truncated. See SEARCH_INDEX_MAX_BYTES.
+        throw new Error(`search index artifact is ${body.byteLength} bytes, over the declared ` +
+            `${SEARCH_INDEX_MAX_BYTES}. Refusing to publish a silently short index — ` +
+            `raise the ceiling deliberately or find out why it grew.`);
+    }
+    const path = storagePathFor(artifact.version);
+    await bucket.file(path).save(body, {
+        contentType: "application/json; charset=utf-8",
+        metadata: {
+            cacheControl: "public, max-age=31536000, immutable",
+            contentEncoding: undefined,
+        },
+    });
+    let pruned = 0;
+    try {
+        const [files] = await bucket.getFiles({ prefix: `${SEARCH_INDEX_PREFIX}/v` });
+        const versions = files
+            .map((f) => ({ name: f.name, v: Number(/v(\d+)\.json$/.exec(f.name)?.[1] ?? NaN) }))
+            .filter((f) => Number.isFinite(f.v))
+            .sort((a, b) => b.v - a.v);
+        for (const stale of versions.slice(KEEP_VERSIONS)) {
+            await bucket.file(stale.name).delete();
+            pruned++;
+        }
+    }
+    catch (err) {
+        /*
+         * A failed prune is NOT a failed publish. The new artifact is already
+         * live and correct; the cost of leaving an extra 384 KB object behind is
+         * trivial next to failing a build that produced a good index.
+         */
+        const e = normalizeError(err);
+        serverLogger.warn("search index prune failed (artifact is published)", {
+            message: e.message,
+        });
+    }
+    return { storagePath: path, bytes: body.byteLength, pruned };
+}
+/**
+ * Mirror the manifest to Storage so the client needs no Firebase SDK.
+ *
+ * Writes only the four fields a browser has any business reading — `dirty`,
+ * `lastFullAt` and `perType` are build bookkeeping, and publishing "the index
+ * is currently stale" to every visitor tells them nothing they can act on.
+ * The shape is `SearchIndexManifestPublic`, declared beside the URL builders.
+ *
+ * ## 🛑 60 seconds, and the number is load-bearing in both directions
+ *
+ * This is the ONLY uncacheable-for-long hop in the whole design, so it sets
+ * the floor on how fast a new build reaches a visitor — and the ceiling on
+ * how often a returning visitor pays for a request. The artifact behind it is
+ * `immutable`, so a client that re-reads the manifest and finds the same
+ * version does one small conditional fetch and no download at all.
+ *
+ * Too long and the 15-minute build cadence is a lie; too short and every
+ * visitor re-requests it per page view for a document that changes a few
+ * times an hour.
+ *
+ * ## Written LAST, and failing it does not fail the build
+ *
+ * A published artifact with a stale manifest serves the previous index for up
+ * to a minute — correct, just behind. A manifest pointing at an artifact that
+ * was never written is a 404 on the client's critical path. So the order is
+ * artifact, then Firestore, then this; and a throw here is logged, not
+ * propagated, because the Firestore manifest (which is what the NEXT build
+ * reads) is already correct by this point.
+ */
+export async function publishManifestMirror(bucket, manifest) {
+    try {
+        const body = Buffer.from(JSON.stringify({
+            schema: manifest.schema,
+            version: manifest.version,
+            builtAt: manifest.builtAt,
+            recordCount: manifest.recordCount,
+        }), "utf8");
+        await bucket.file(SEARCH_MANIFEST_OBJECT).save(body, {
+            contentType: "application/json; charset=utf-8",
+            metadata: { cacheControl: "public, max-age=60" },
+        });
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * WARN rather than throw. But it is a real symptom: the artifact is live
+         * and no client will ever learn its version, so the index silently stops
+         * advancing while every other signal says the build succeeded. That is
+         * precisely the "confident wrong answer" shape, which is why it is logged
+         * at WARN and not swallowed.
+         */
+        serverLogger.warn("search index manifest mirror failed (artifact is published)", {
+            version: manifest.version,
+            message: e.message,
+        });
+    }
+}

package/dist/_internal/server/features/search/index-build/build.d.ts

@@ -0,0 +1,57 @@
+import { type IndexDocData } from "./sources";
+import { type SearchIndexArtifact, type SearchIndexRecord } from "../../../../shared/search/index-record";
+/** The minimal Firestore surface this module needs, so it stays testable. */
+interface BuildQuery {
+    where(field: string, op: string, value: unknown): BuildQuery;
+    select(...fields: string[]): BuildQuery;
+    get(): Promise<{
+        docs: Array<{
+            id: string;
+            data(): IndexDocData;
+        }>;
+    }>;
+}
+interface BuildDb {
+    collection(name: string): BuildQuery;
+}
+export interface BuildStats {
+    readonly mode: "full" | "incremental";
+    /** Documents READ. This is the number that has to stay inside the budget. */
+    readonly reads: number;
+    readonly perType: Readonly<Record<string, number>>;
+    /** Documents read but rejected by `toRecord` — unpublished, unjoinable, … */
+    readonly dropped: number;
+    /**
+     * Sources that threw. Non-zero means the artifact is INCOMPLETE for those
+     * types, so the caller must not treat the build as clean — see the
+     * `dirty` handling in `searchIndexBuild`.
+     */
+    readonly failed: number;
+    readonly durationMs: number;
+}
+export interface BuildResult {
+    readonly artifact: SearchIndexArtifact;
+    readonly stats: BuildStats;
+}
+/**
+ * Build from scratch. Reconciles hard deletes by construction, because the
+ * result contains exactly what the sources currently return.
+ */
+export declare function buildFull(db: BuildDb, version: number, now?: Date): Promise<BuildResult>;
+/**
+ * Patch the previous artifact with everything that changed since it was built.
+ *
+ * 🛑 A source that fails here is logged and SKIPPED, not fatal — unlike the
+ * full build. The difference is what the failure costs: a skipped incremental
+ * source leaves that type's records at their previous (correct, slightly
+ * stale) values and the next pass picks them up, whereas a skipped full source
+ * would delete the type from the artifact entirely.
+ */
+export declare function buildIncremental(db: BuildDb, previous: SearchIndexArtifact, since: Date, version: number, now?: Date): Promise<BuildResult>;
+/**
+ * Re-key a record from a previous artifact. Mirrors `keyOf` — both sides key
+ * on `${typeKey}:${slug}`, which is the invariant that makes an incremental
+ * patch REPLACE a changed row rather than add a second copy of it.
+ */
+export declare function keyFromRecord(rec: SearchIndexRecord): string | null;
+export {};

package/dist/_internal/server/features/search/index-build/build.js

@@ -0,0 +1,285 @@
+/*
+ * WHY: Turn the public collections into one small artifact the browser can
+ *      search locally, WITHOUT the read cost that makes the obvious version
+ *      impossible.
+ * WHAT: Full and incremental builds, plus the stats a caller must log.
+ *
+ * ## 🛑 THE READ BUDGET IS THE DESIGN. Read this before changing the cadence.
+ *
+ * Firestore bills **per document read regardless of `select()`** — projection
+ * cuts egress, not read count. So the naive version, a full rebuild every 15
+ * minutes, is `96 × 3,730 ≈ 358,000 reads/day` against a **50,000/day** free
+ * tier. Seven times over, for a feature nobody asked to be expensive. Hourly
+ * is still ~89,000.
+ *
+ * Hence two modes:
+ *
+ *   idle        manifest says not dirty               1 read       ~90/day
+ *   incremental `updatedAt > lastBuiltAt` per source  13 + changed ~200/day
+ *   full        everything; reconciles hard deletes   3,730        3,730/day
+ *
+ * ≈ 4,000 reads/day, about 8% of the tier.
+ *
+ * 🛑 THE INCREMENTAL CLAUSE NEEDS A COMPOSITE INDEX PER SOURCE, and an earlier
+ * version of this header claimed the opposite.
+ *
+ * A LONE range clause on `updatedAt` needs nothing — Firestore auto-creates
+ * single-field ascending indexes. But every source that also carries a
+ * `where` equality (`status == published`, `categoryType == brand`,
+ * `isActive == true`) combines equality + range, and that DOES require a
+ * composite. Only `category`, `part` and `model` — the three with no `where`
+ * — are index-free.
+ *
+ * Found by running the job against production, not by reading it: the FULL
+ * build has no range clause and passed cleanly, so nothing surfaced until the
+ * first INCREMENTAL pass returned `9 FAILED_PRECONDITION` for brand, store,
+ * blog and every other filtered source. Exactly the Root Cause #59 shape the
+ * old comment claimed immunity from.
+ *
+ * The indexes are declared in `appkit/firebase/base/firestore.indexes.json`.
+ * Adding a source with a `where` means adding its `(field, updatedAt)` pair
+ * there too, or that source silently stops updating incrementally.
+ *
+ * ## Unpublish vs hard delete — different mechanisms, say which is which
+ *
+ * **Unpublish is handled incrementally.** A product flipped `published ->
+ * draft` still has a fresh `updatedAt`, so the builder re-reads it, finds it
+ * fails the source's filter, and REMOVES it from the artifact within the
+ * cadence. That is the case that matters, because it is the one that happens.
+ *
+ * **A hard delete is invisible to an `updatedAt` query** and is reconciled by
+ * the daily full pass. Worst case is a dead link for up to 24 h, which is link
+ * rot rather than disclosure. Tombstone machinery would be real complexity for
+ * the rarer half of a split that can be described in two sentences.
+ *
+ * @tag domain:search
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:searchIndexBuild
+ * @tag sideEffects:firestore-read
+ */
+import { normalizeError } from "../../../../../errors/normalize.js";
+import { serverLogger } from "../../../../../monitoring/server-logger.js";
+import { hidePublicTestData } from "../../tester/visibility.js";
+import { INDEX_TYPES, PUBLIC_INDEX_SOURCES, typeIndexFor, } from "./sources.js";
+import { INDEX_UPDATED_AT_FIELD, SEARCH_INDEX_SCHEMA_VERSION, } from "../../../../shared/search/index-record.js";
+/**
+ * The patch key, derived from the source's own `slugOf` so the REMOVE path and
+ * the ADD path cannot disagree — and so re-keying a previous artifact (which
+ * has only the slug) lands on the same string.
+ */
+function typeKeyFor(source, d) {
+    return source.typeKeyOf ? source.typeKeyOf(d) : source.typeKey;
+}
+function keyOf(source, id, d) {
+    const slug = source.slugOf(id, d);
+    return slug ? `${typeKeyFor(source, d)}:${slug}` : null;
+}
+async function readSource(db, source, since) {
+    let q = db.collection(source.collection);
+    for (const [field, value] of source.where ?? [])
+        q = q.where(field, "==", value);
+    /*
+     * 🛑 The incremental clause is applied INSTEAD OF nothing, not in addition
+     * to a page limit. An unbounded `updatedAt >` on a quiet collection returns
+     * a handful of rows; on a reseed it returns everything, which is correct —
+     * a reseed genuinely did change everything.
+     */
+    if (since)
+        q = q.where(INDEX_UPDATED_AT_FIELD, ">", since);
+    const snap = await q.select(...source.select, "isTestData", INDEX_UPDATED_AT_FIELD).get();
+    /*
+     * Firestore bills a minimum of one read for a query that matches nothing,
+     * so an idle incremental pass still costs one per source. Counting it is
+     * the difference between a budget and a guess.
+     */
+    return { docs: snap.docs, reads: Math.max(1, snap.docs.length) };
+}
+function toRecords(source, docs) {
+    const kept = [];
+    const removed = [];
+    let dropped = 0;
+    /*
+     * 🛑 `hidePublicTestData` is NOT optional here, and this call site differs
+     * from every other one. Elsewhere a sandbox row that slips through is shown
+     * to one viewer on one render. Here it is baked into a shared, immutable,
+     * CDN-cached body and published to everyone for the life of that version.
+     */
+    /*
+     * 🛑 An INTERSECTION, not a cast. `IndexDocData` is `Record<string,
+     * unknown>`, whose index signature makes `isTestData` an `unknown` and so
+     * fails `TestDataFlagged`. The lazy fix is `as any`, which would also
+     * silence the fact that `hidePublicTestData` is generic and preserves the
+     * row type — including `__id`, which the loop below needs. Naming the shape
+     * keeps both ends type-checked.
+     */
+    const rows = docs.map((d) => ({ ...d.data(), __id: d.id }));
+    const visible = hidePublicTestData(rows);
+    for (const row of visible) {
+        const id = row.__id;
+        const key = keyOf(source, id, row);
+        // No derivable slug means no href and no stable identity — such a row
+        // cannot be a search result at all, so it is dropped rather than keyed
+        // under something invented.
+        if (!key) {
+            dropped++;
+            continue;
+        }
+        const rec = source.toRecord(id, row);
+        if (!rec) {
+            dropped++;
+            // A document that fails `toRecord` on an INCREMENTAL pass is usually a
+            // row that just became non-public — so it must be removed, not ignored.
+            removed.push(key);
+            continue;
+        }
+        /*
+         * 🛑 Resolved per DOCUMENT, not per source. `products` holds all nine
+         * listing types and each has its own detail route, so a single type index
+         * for the collection would send every auction to /products/{slug} —
+         * Root Cause #48, rebuilt.
+         */
+        const typeKey = typeKeyFor(source, row);
+        const typeIdx = typeIndexFor(typeKey);
+        if (typeIdx < 0) {
+            dropped++;
+            continue;
+        }
+        const slug = key.slice(typeKey.length + 1);
+        const tuple = rec.facets === undefined
+            ? [typeIdx, rec.title, rec.detail, slug]
+            : [typeIdx, rec.title, rec.detail, slug, rec.facets];
+        kept.push([key, tuple]);
+    }
+    return { kept, removed, dropped };
+}
+function envelope(version, keyed, builtAt) {
+    return {
+        schema: SEARCH_INDEX_SCHEMA_VERSION,
+        version,
+        builtAt: builtAt.toISOString(),
+        types: INDEX_TYPES,
+        // Sorted by key so two builds over identical data produce identical bytes,
+        // which is what makes "did anything actually change" answerable.
+        r: Object.keys(keyed)
+            .sort()
+            .map((k) => keyed[k]),
+    };
+}
+/**
+ * Build from scratch. Reconciles hard deletes by construction, because the
+ * result contains exactly what the sources currently return.
+ */
+export async function buildFull(db, version, now = new Date()) {
+    const started = Date.now();
+    const keyed = {};
+    const perType = {};
+    let reads = 0;
+    let dropped = 0;
+    for (const source of PUBLIC_INDEX_SOURCES) {
+        try {
+            const { docs, reads: r } = await readSource(db, source, null);
+            reads += r;
+            const out = toRecords(source, docs);
+            for (const [k, rec] of out.kept) {
+                keyed[k] = rec;
+                const tk = INDEX_TYPES[rec[0]]?.key ?? source.typeKey;
+                perType[tk] = (perType[tk] ?? 0) + 1;
+            }
+            dropped += out.dropped;
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            /*
+             * 🛑 A failing source does NOT silently shrink the artifact. A full
+             * build that quietly omits `products` would publish a search index
+             * missing a third of the site and report success — the exact shape of
+             * every silent-degradation bug this codebase keeps recording.
+             */
+            serverLogger.error("searchIndexBuild: source failed during FULL build — aborting", {
+                source: source.typeKey,
+                collection: source.collection,
+                error: e.message,
+            });
+            throw err;
+        }
+    }
+    return {
+        artifact: envelope(version, keyed, now),
+        stats: {
+            mode: "full",
+            reads,
+            perType,
+            dropped,
+            failed: 0,
+            durationMs: Date.now() - started,
+        },
+    };
+}
+/**
+ * Patch the previous artifact with everything that changed since it was built.
+ *
+ * 🛑 A source that fails here is logged and SKIPPED, not fatal — unlike the
+ * full build. The difference is what the failure costs: a skipped incremental
+ * source leaves that type's records at their previous (correct, slightly
+ * stale) values and the next pass picks them up, whereas a skipped full source
+ * would delete the type from the artifact entirely.
+ */
+export async function buildIncremental(db, previous, since, version, now = new Date()) {
+    const started = Date.now();
+    // Re-key the previous artifact. The tuple carries no id, so the key is
+    // rebuilt from type + slug — which is why `slug` must be stable per record.
+    const keyed = {};
+    for (const rec of previous.r) {
+        const key = keyFromRecord(rec);
+        if (key)
+            keyed[key] = rec;
+    }
+    const perType = {};
+    let reads = 0;
+    let dropped = 0;
+    let failed = 0;
+    for (const source of PUBLIC_INDEX_SOURCES) {
+        try {
+            const { docs, reads: r } = await readSource(db, source, since);
+            reads += r;
+            const out = toRecords(source, docs);
+            for (const k of out.removed)
+                delete keyed[k];
+            for (const [k, rec] of out.kept)
+                keyed[k] = rec;
+            perType[source.typeKey] = out.kept.length;
+            dropped += out.dropped;
+        }
+        catch (err) {
+            failed++;
+            const e = normalizeError(err);
+            serverLogger.warn("searchIndexBuild: source failed during INCREMENTAL build — skipped", {
+                source: source.typeKey,
+                collection: source.collection,
+                error: e.message,
+            });
+        }
+    }
+    return {
+        artifact: envelope(version, keyed, now),
+        stats: {
+            mode: "incremental",
+            reads,
+            perType,
+            dropped,
+            failed,
+            durationMs: Date.now() - started,
+        },
+    };
+}
+/**
+ * Re-key a record from a previous artifact. Mirrors `keyOf` — both sides key
+ * on `${typeKey}:${slug}`, which is the invariant that makes an incremental
+ * patch REPLACE a changed row rather than add a second copy of it.
+ */
+export function keyFromRecord(rec) {
+    const type = INDEX_TYPES[rec[0]];
+    return type ? `${type.key}:${rec[3]}` : null;
+}