@voyant-travel/catalog 0.117.2

package/dist/services/indexer-service.test.js

@@ -0,0 +1,176 @@
+import { describe, expect, it } from "vitest";
+import { createFieldPolicyRegistry, defineFieldPolicy } from "../contract.js";
+import { createIndexerService } from "./indexer-service.js";
+function createStubAdapter() {
+    const calls = [];
+    const capabilities = {
+        supportsKeywordSearch: true,
+        supportsHybridSearch: false,
+        supportsVectorFields: false,
+        vectorDimensions: null,
+        maxVectorsPerDocument: null,
+        supportsCrossAudienceFederation: false,
+        supportsAdminDenormalization: false,
+    };
+    return {
+        capabilities,
+        calls,
+        async ensureCollection(slice) {
+            calls.push({ op: "ensureCollection", slice });
+        },
+        async upsert(slice, documents) {
+            calls.push({ op: "upsert", slice, documents });
+        },
+        async delete(slice, ids) {
+            calls.push({ op: "delete", slice, ids });
+        },
+        async search(slice, _request) {
+            calls.push({ op: "search", slice });
+            return { hits: [], total: 0 };
+        },
+        async bulkReindex(slice, _stream, _options) {
+            calls.push({ op: "bulkReindex", slice });
+        },
+    };
+}
+const merchandisable = {
+    class: "merchandisable",
+    merge: "replace",
+    editRole: "marketing",
+    overrideFriction: "none",
+    snapshot: "on-book",
+};
+const productsRegistry = createFieldPolicyRegistry(defineFieldPolicy([{ path: "title", ...merchandisable, visibility: ["staff", "customer"] }]));
+const cruisesRegistry = createFieldPolicyRegistry(defineFieldPolicy([{ path: "name", ...merchandisable, visibility: ["staff", "customer"] }]));
+const productSlices = [
+    { vertical: "products", locale: "en-GB", audience: "staff-admin", market: "default" },
+    { vertical: "products", locale: "en-GB", audience: "customer", market: "default" },
+];
+const cruiseSlices = [
+    { vertical: "cruises", locale: "en-GB", audience: "customer", market: "default" },
+];
+describe("IndexerService", () => {
+    it("ensures collections across every configured slice", async () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: [...productSlices, ...cruiseSlices],
+            registries: new Map([
+                ["products", productsRegistry],
+                ["cruises", cruisesRegistry],
+            ]),
+        });
+        await service.ensureCollections();
+        const ensureCalls = adapter.calls.filter((c) => c.op === "ensureCollection");
+        expect(ensureCalls).toHaveLength(3);
+    });
+    it("reindexes one entity across only its vertical's slices", async () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: [...productSlices, ...cruiseSlices],
+            registries: new Map([
+                ["products", productsRegistry],
+                ["cruises", cruisesRegistry],
+            ]),
+        });
+        await service.reindexEntity("products", "prod_xyz", async (entityId, slice) => ({
+            id: entityId,
+            fields: { title: `${slice.audience} title` },
+        }));
+        const upsertCalls = adapter.calls.filter((c) => c.op === "upsert");
+        expect(upsertCalls).toHaveLength(2);
+        expect(upsertCalls.every((c) => c.slice.vertical === "products")).toBe(true);
+        // Each slice received its own document with audience-specific fields.
+        expect(upsertCalls[0]?.documents?.[0]?.fields.title).toBe("staff-admin title");
+        expect(upsertCalls[1]?.documents?.[0]?.fields.title).toBe("customer title");
+    });
+    it("reindexEntityForSlice writes to exactly one slice", async () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: [...productSlices, ...cruiseSlices],
+            registries: new Map([
+                ["products", productsRegistry],
+                ["cruises", cruisesRegistry],
+            ]),
+        });
+        const customerSlice = productSlices[1];
+        await service.reindexEntityForSlice(customerSlice, "prod_xyz", async () => ({
+            id: "prod_xyz",
+            fields: { title: "customer title" },
+        }));
+        const upsertCalls = adapter.calls.filter((c) => c.op === "upsert");
+        expect(upsertCalls).toHaveLength(1);
+        expect(upsertCalls[0]?.slice).toEqual(customerSlice);
+    });
+    it("deletes one entity from every slice configured for its vertical", async () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: [...productSlices, ...cruiseSlices],
+            registries: new Map([
+                ["products", productsRegistry],
+                ["cruises", cruisesRegistry],
+            ]),
+        });
+        await service.deleteEntity("products", "prod_xyz");
+        const deleteCalls = adapter.calls.filter((c) => c.op === "delete");
+        expect(deleteCalls).toHaveLength(2);
+        expect(deleteCalls.every((c) => c.ids?.includes("prod_xyz"))).toBe(true);
+    });
+    it("deletes stale slice documents when the document builder returns null", async () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: productSlices,
+            registries: new Map([["products", productsRegistry]]),
+        });
+        await service.reindexEntity("products", "prod_xyz", async (_entityId, slice) => slice.audience === "customer" ? null : { id: "prod_xyz", fields: {} });
+        const upsertCalls = adapter.calls.filter((c) => c.op === "upsert");
+        expect(upsertCalls).toHaveLength(1);
+        expect(upsertCalls[0]?.slice.audience).toBe("staff-admin");
+        const deleteCalls = adapter.calls.filter((c) => c.op === "delete");
+        expect(deleteCalls).toHaveLength(1);
+        expect(deleteCalls[0]?.slice.audience).toBe("customer");
+        expect(deleteCalls[0]?.ids).toEqual(["prod_xyz"]);
+    });
+    it("deletes stale single-slice documents when the slice builder returns null", async () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: productSlices,
+            registries: new Map([["products", productsRegistry]]),
+        });
+        const customerSlice = productSlices[1];
+        await service.reindexEntityForSlice(customerSlice, "prod_xyz", async () => null);
+        expect(adapter.calls.filter((c) => c.op === "upsert")).toHaveLength(0);
+        const deleteCalls = adapter.calls.filter((c) => c.op === "delete");
+        expect(deleteCalls).toHaveLength(1);
+        expect(deleteCalls[0]?.slice).toEqual(customerSlice);
+        expect(deleteCalls[0]?.ids).toEqual(["prod_xyz"]);
+    });
+    it("throws when reindexing for a vertical without a registered registry", async () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: [{ vertical: "phantom", locale: "en-GB", audience: "customer", market: "default" }],
+            registries: new Map(),
+        });
+        await expect(service.ensureCollections()).rejects.toThrow(/no field-policy registry/);
+    });
+    it("slicesForVertical filters down correctly", () => {
+        const adapter = createStubAdapter();
+        const service = createIndexerService({
+            adapter,
+            slices: [...productSlices, ...cruiseSlices],
+            registries: new Map([
+                ["products", productsRegistry],
+                ["cruises", cruisesRegistry],
+            ]),
+        });
+        expect(service.slicesForVertical("products")).toHaveLength(2);
+        expect(service.slicesForVertical("cruises")).toHaveLength(1);
+        expect(service.slicesForVertical("phantom")).toHaveLength(0);
+    });
+});

package/dist/services/overlay-service.d.ts

@@ -0,0 +1,108 @@
+/**
+ * OverlayService — drizzle-bound entry point for the catalog overlay store.
+ *
+ * Wraps the pure `resolveOverlay` logic (in `../overlay/resolver.ts`) with
+ * the DB queries verticals actually need: fetch active overlays for an
+ * entity, write a new overlay row, soft-delete an overlay, list by origin,
+ * and the all-in-one `resolveEntityView` helper that fetches + resolves in
+ * one call.
+ *
+ * Functions take an `AnyDrizzleDb` as their first parameter to match the
+ * existing voyant convention (see `packages/products/src/service.ts`). Pure
+ * resolver logic stays separate and remains unit-testable without a DB.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.2 for the design.
+ */
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+import type { FieldPolicyRegistry, Visibility } from "../contract.js";
+import { type OverlayLookup, type ResolvedView, type ResolverOverlay, type ResolverScope } from "../overlay/resolver.js";
+import { OVERLAY_DEFAULT_SCOPE, type OverlayOrigin, type SelectCatalogOverlay } from "../overlay/schema.js";
+/**
+ * Fetch all active (not soft-deleted) overlays for an entity in one query.
+ * The resolver expects this exact shape; downstream callers pass the result
+ * straight into `resolveOverlay`.
+ */
+export declare function fetchOverlaysForEntity(db: AnyDrizzleDb, entityModule: string, entityId: string): Promise<ResolverOverlay[]>;
+/**
+ * Batched form of `fetchOverlaysForEntity`: fetch all active overlays for
+ * many entities of one module in a single query, grouped by entity id.
+ *
+ * Every requested id is present in the returned map (entities without
+ * overlays map to an empty array), so callers can index without null
+ * checks. Pass the per-entity array straight into
+ * `resolveEntityViewWithOverlays` — the result is identical to calling
+ * `resolveEntityView` once per entity, minus the N-1 round trips.
+ */
+export declare function fetchOverlaysForEntities(db: AnyDrizzleDb, entityModule: string, entityIds: ReadonlyArray<string>): Promise<Map<string, ResolverOverlay[]>>;
+/**
+ * Resolve an entity's view in one call: fetch overlays, run the resolver,
+ * return the merged view filtered by the actor's visibility.
+ *
+ * The caller supplies the source projection (typically gathered from the
+ * vertical's own service layer) and the requesting scope. Verticals call
+ * this in their `getEntity` / `listEntities` paths.
+ */
+export declare function resolveEntityView(db: AnyDrizzleDb, registry: FieldPolicyRegistry, entityModule: string, entityId: string, sourceProjection: ReadonlyMap<string, unknown>, scope: ResolverScope): Promise<ResolvedView>;
+/**
+ * Lower-level helper for callers that have already fetched overlays (e.g.
+ * batch read-paths that pre-fetch overlays for many entities in one query).
+ */
+export declare function resolveEntityViewWithOverlays(registry: FieldPolicyRegistry, sourceProjection: ReadonlyMap<string, unknown>, overlays: OverlayLookup, scope: ResolverScope): ResolvedView;
+/**
+ * List overlay rows by their origin discriminator. Used by revert / re-sync
+ * workflows ("show me everything Sanity wrote in the last week", "revert
+ * all AI-generated overlays on this entity").
+ */
+export interface OverlayOriginFilter {
+    kind: OverlayOrigin["kind"];
+    /** Kind-specific narrowing — e.g. `provider: "sanity"` for `kind: "cms"`. */
+    match?: Partial<OverlayOrigin>;
+}
+export declare function listOverlaysByOrigin(db: AnyDrizzleDb, filter: OverlayOriginFilter, options?: {
+    includeDeleted?: boolean;
+    limit?: number;
+}): Promise<SelectCatalogOverlay[]>;
+/**
+ * Input for writing a single overlay row. Variant axes default to
+ * `OVERLAY_DEFAULT_SCOPE`.
+ */
+export interface WriteOverlayInput {
+    entity_module: string;
+    entity_id: string;
+    field_path: string;
+    locale?: string;
+    audience?: Visibility | typeof OVERLAY_DEFAULT_SCOPE;
+    market?: string;
+    value: unknown;
+    origin: OverlayOrigin;
+}
+/**
+ * Write or replace an overlay row for the given variant tuple.
+ *
+ * If a row already exists for `(entity_module, entity_id, field_path,
+ * locale, audience, market)` and is not soft-deleted, this updates its
+ * value, origin, and `updated_at`. The partial unique index on the active
+ * rows guarantees idempotency.
+ *
+ * Last-write-wins is the default conflict-resolution policy (see
+ * architecture §5.2.3); per-field canonical-writer config is deferred.
+ *
+ * Note: this function does not validate that the field policy permits an
+ * overlay write (e.g. that `merge` is not `source-only` or that the actor's
+ * `editRole` matches). Callers are responsible for policy validation; the
+ * service-layer caller typically wraps this with a check against the
+ * vertical's `FieldPolicyRegistry`.
+ */
+export declare function writeOverlay(db: AnyDrizzleDb, input: WriteOverlayInput): Promise<SelectCatalogOverlay>;
+/**
+ * Soft-delete an overlay row by setting `deleted_at`. The row is preserved
+ * for retention / restore but no longer participates in resolver merges.
+ */
+export declare function softDeleteOverlay(db: AnyDrizzleDb, id: string): Promise<void>;
+/**
+ * Restore a soft-deleted overlay by clearing `deleted_at`. Used by source
+ * reconnection (§5.10.5) when an entity comes back within the retention
+ * window.
+ */
+export declare function restoreOverlay(db: AnyDrizzleDb, id: string): Promise<void>;
+//# sourceMappingURL=overlay-service.d.ts.map

package/dist/services/overlay-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-service.d.ts","sourceRoot":"","sources":["../../src/services/overlay-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AACrE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAEnB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAEL,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAA;AAM7B;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,YAAY,EAChB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,EAAE,CAAC,CAyB5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,YAAY,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,GAC/B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC,CAmCzC;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,mBAAmB,EAC7B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,YAAY,CAAC,CAGvB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,mBAAmB,EAC7B,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,aAAa,GACnB,YAAY,CAEd;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC3B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;CAC/B;AAED,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA2BjC;AAMD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,qBAAqB,CAAA;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,aAAa,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,oBAAoB,CAAC,CA0C/B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnF;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhF"}

package/dist/services/overlay-service.js

@@ -0,0 +1,211 @@
+/**
+ * OverlayService — drizzle-bound entry point for the catalog overlay store.
+ *
+ * Wraps the pure `resolveOverlay` logic (in `../overlay/resolver.ts`) with
+ * the DB queries verticals actually need: fetch active overlays for an
+ * entity, write a new overlay row, soft-delete an overlay, list by origin,
+ * and the all-in-one `resolveEntityView` helper that fetches + resolves in
+ * one call.
+ *
+ * Functions take an `AnyDrizzleDb` as their first parameter to match the
+ * existing voyant convention (see `packages/products/src/service.ts`). Pure
+ * resolver logic stays separate and remains unit-testable without a DB.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.2 for the design.
+ */
+import { newId } from "@voyant-travel/db/lib/typeid";
+import { and, eq, inArray, isNull, sql } from "drizzle-orm";
+import { resolveOverlay, } from "../overlay/resolver.js";
+import { catalogOverlayTable, OVERLAY_DEFAULT_SCOPE, } from "../overlay/schema.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Reads
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Fetch all active (not soft-deleted) overlays for an entity in one query.
+ * The resolver expects this exact shape; downstream callers pass the result
+ * straight into `resolveOverlay`.
+ */
+export async function fetchOverlaysForEntity(db, entityModule, entityId) {
+    const rows = await db
+        .select({
+        field_path: catalogOverlayTable.field_path,
+        locale: catalogOverlayTable.locale,
+        audience: catalogOverlayTable.audience,
+        market: catalogOverlayTable.market,
+        value: catalogOverlayTable.value,
+    })
+        .from(catalogOverlayTable)
+        .where(and(eq(catalogOverlayTable.entity_module, entityModule), eq(catalogOverlayTable.entity_id, entityId), isNull(catalogOverlayTable.deleted_at)));
+    return rows.map((row) => ({
+        field_path: row.field_path,
+        locale: row.locale,
+        audience: row.audience,
+        market: row.market,
+        value: row.value,
+    }));
+}
+/**
+ * Batched form of `fetchOverlaysForEntity`: fetch all active overlays for
+ * many entities of one module in a single query, grouped by entity id.
+ *
+ * Every requested id is present in the returned map (entities without
+ * overlays map to an empty array), so callers can index without null
+ * checks. Pass the per-entity array straight into
+ * `resolveEntityViewWithOverlays` — the result is identical to calling
+ * `resolveEntityView` once per entity, minus the N-1 round trips.
+ */
+export async function fetchOverlaysForEntities(db, entityModule, entityIds) {
+    const byEntity = new Map();
+    for (const id of entityIds) {
+        if (!byEntity.has(id))
+            byEntity.set(id, []);
+    }
+    if (byEntity.size === 0)
+        return byEntity;
+    const rows = await db
+        .select({
+        entity_id: catalogOverlayTable.entity_id,
+        field_path: catalogOverlayTable.field_path,
+        locale: catalogOverlayTable.locale,
+        audience: catalogOverlayTable.audience,
+        market: catalogOverlayTable.market,
+        value: catalogOverlayTable.value,
+    })
+        .from(catalogOverlayTable)
+        .where(and(eq(catalogOverlayTable.entity_module, entityModule), inArray(catalogOverlayTable.entity_id, [...byEntity.keys()]), isNull(catalogOverlayTable.deleted_at)));
+    for (const row of rows) {
+        byEntity.get(row.entity_id)?.push({
+            field_path: row.field_path,
+            locale: row.locale,
+            audience: row.audience,
+            market: row.market,
+            value: row.value,
+        });
+    }
+    return byEntity;
+}
+/**
+ * Resolve an entity's view in one call: fetch overlays, run the resolver,
+ * return the merged view filtered by the actor's visibility.
+ *
+ * The caller supplies the source projection (typically gathered from the
+ * vertical's own service layer) and the requesting scope. Verticals call
+ * this in their `getEntity` / `listEntities` paths.
+ */
+export async function resolveEntityView(db, registry, entityModule, entityId, sourceProjection, scope) {
+    const overlays = await fetchOverlaysForEntity(db, entityModule, entityId);
+    return resolveOverlay(registry, sourceProjection, overlays, scope);
+}
+/**
+ * Lower-level helper for callers that have already fetched overlays (e.g.
+ * batch read-paths that pre-fetch overlays for many entities in one query).
+ */
+export function resolveEntityViewWithOverlays(registry, sourceProjection, overlays, scope) {
+    return resolveOverlay(registry, sourceProjection, overlays, scope);
+}
+export async function listOverlaysByOrigin(db, filter, options = {}) {
+    // agent-quality: raw-sql reviewed -- JSONB origin discriminator uses parameterized values; Drizzle has no helper for the `->>` JSON key predicate here.
+    const conditions = [sql `${catalogOverlayTable.origin}->>'kind' = ${filter.kind}`];
+    if (filter.match) {
+        for (const [key, value] of Object.entries(filter.match)) {
+            if (key === "kind")
+                continue;
+            // agent-quality: raw-sql reviewed -- Origin match keys come from the typed overlay-origin filter and values stay parameterized.
+            conditions.push(sql `${catalogOverlayTable.origin}->>${key} = ${String(value)}`);
+        }
+    }
+    if (!options.includeDeleted) {
+        // agent-quality: raw-sql reviewed -- Literal deleted_at null predicate is scoped to the overlay table.
+        conditions.push(sql `${catalogOverlayTable.deleted_at} IS NULL`);
+    }
+    if (options.limit != null) {
+        return db
+            .select()
+            .from(catalogOverlayTable)
+            .where(and(...conditions))
+            .limit(options.limit);
+    }
+    return db
+        .select()
+        .from(catalogOverlayTable)
+        .where(and(...conditions));
+}
+/**
+ * Write or replace an overlay row for the given variant tuple.
+ *
+ * If a row already exists for `(entity_module, entity_id, field_path,
+ * locale, audience, market)` and is not soft-deleted, this updates its
+ * value, origin, and `updated_at`. The partial unique index on the active
+ * rows guarantees idempotency.
+ *
+ * Last-write-wins is the default conflict-resolution policy (see
+ * architecture §5.2.3); per-field canonical-writer config is deferred.
+ *
+ * Note: this function does not validate that the field policy permits an
+ * overlay write (e.g. that `merge` is not `source-only` or that the actor's
+ * `editRole` matches). Callers are responsible for policy validation; the
+ * service-layer caller typically wraps this with a check against the
+ * vertical's `FieldPolicyRegistry`.
+ */
+export async function writeOverlay(db, input) {
+    const locale = input.locale ?? OVERLAY_DEFAULT_SCOPE;
+    const audience = input.audience ?? OVERLAY_DEFAULT_SCOPE;
+    const market = input.market ?? OVERLAY_DEFAULT_SCOPE;
+    // Insert with ON CONFLICT for the active-row composite unique key.
+    // Drizzle's onConflictDoUpdate is the right primitive here.
+    const inserted = await db
+        .insert(catalogOverlayTable)
+        .values({
+        id: newId("catalog_overlay"),
+        entity_module: input.entity_module,
+        entity_id: input.entity_id,
+        field_path: input.field_path,
+        locale,
+        audience,
+        market,
+        value: input.value,
+        origin: input.origin,
+    })
+        .onConflictDoUpdate({
+        target: [
+            catalogOverlayTable.entity_module,
+            catalogOverlayTable.entity_id,
+            catalogOverlayTable.field_path,
+            catalogOverlayTable.locale,
+            catalogOverlayTable.audience,
+            catalogOverlayTable.market,
+        ],
+        targetWhere: isNull(catalogOverlayTable.deleted_at),
+        set: {
+            value: input.value,
+            origin: input.origin,
+            updated_at: new Date(),
+        },
+    })
+        .returning();
+    if (!inserted[0]) {
+        throw new Error("writeOverlay: insert returned no rows");
+    }
+    return inserted[0];
+}
+/**
+ * Soft-delete an overlay row by setting `deleted_at`. The row is preserved
+ * for retention / restore but no longer participates in resolver merges.
+ */
+export async function softDeleteOverlay(db, id) {
+    await db
+        .update(catalogOverlayTable)
+        .set({ deleted_at: new Date(), updated_at: new Date() })
+        .where(eq(catalogOverlayTable.id, id));
+}
+/**
+ * Restore a soft-deleted overlay by clearing `deleted_at`. Used by source
+ * reconnection (§5.10.5) when an entity comes back within the retention
+ * window.
+ */
+export async function restoreOverlay(db, id) {
+    await db
+        .update(catalogOverlayTable)
+        .set({ deleted_at: null, updated_at: new Date() })
+        .where(eq(catalogOverlayTable.id, id));
+}

package/dist/services/overlay-service.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=overlay-service.test.d.ts.map

package/dist/services/overlay-service.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-service.test.d.ts","sourceRoot":"","sources":["../../src/services/overlay-service.test.ts"],"names":[],"mappings":""}

package/dist/services/overlay-service.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { fetchOverlaysForEntities } from "./overlay-service.js";
+function drizzleStub(methods) {
+    return methods;
+}
+/**
+ * Minimal mock for the `db.select({...}).from(...).where(...)` chain the
+ * batched overlay fetch issues. Every `select` call is counted so tests can
+ * assert the one-query contract.
+ */
+function mockDb(rows) {
+    let selectCalls = 0;
+    const db = drizzleStub({
+        select: () => {
+            selectCalls++;
+            return {
+                from: () => ({
+                    where: async () => rows,
+                }),
+            };
+        },
+    });
+    return { db, selectCount: () => selectCalls };
+}
+const overlayRow = (entityId, fieldPath, value) => ({
+    entity_id: entityId,
+    field_path: fieldPath,
+    locale: "en-GB",
+    audience: "customer",
+    market: "default",
+    value,
+});
+describe("fetchOverlaysForEntities", () => {
+    it("fetches overlays for many entities in one query, grouped by entity id", async () => {
+        const { db, selectCount } = mockDb([
+            overlayRow("prod_a", "name", "A!"),
+            overlayRow("prod_b", "name", "B!"),
+            overlayRow("prod_a", "description", "Desc A"),
+        ]);
+        const result = await fetchOverlaysForEntities(db, "products", ["prod_a", "prod_b"]);
+        expect(selectCount()).toBe(1);
+        expect(result.get("prod_a")).toEqual([
+            {
+                field_path: "name",
+                locale: "en-GB",
+                audience: "customer",
+                market: "default",
+                value: "A!",
+            },
+            {
+                field_path: "description",
+                locale: "en-GB",
+                audience: "customer",
+                market: "default",
+                value: "Desc A",
+            },
+        ]);
+        expect(result.get("prod_b")).toHaveLength(1);
+    });
+    it("pre-seeds every requested id so entities without overlays map to []", async () => {
+        const { db } = mockDb([overlayRow("prod_a", "name", "A!")]);
+        const result = await fetchOverlaysForEntities(db, "products", ["prod_a", "prod_none"]);
+        expect(result.get("prod_none")).toEqual([]);
+        expect([...result.keys()]).toEqual(["prod_a", "prod_none"]);
+    });
+    it("returns an empty map without querying when no ids are passed", async () => {
+        const { db, selectCount } = mockDb([]);
+        const result = await fetchOverlaysForEntities(db, "products", []);
+        expect(result.size).toBe(0);
+        expect(selectCount()).toBe(0);
+    });
+    it("dedupes repeated ids (one map entry, one query)", async () => {
+        const { db, selectCount } = mockDb([overlayRow("prod_a", "name", "A!")]);
+        const result = await fetchOverlaysForEntities(db, "products", ["prod_a", "prod_a"]);
+        expect(selectCount()).toBe(1);
+        expect(result.size).toBe(1);
+        expect(result.get("prod_a")).toHaveLength(1);
+    });
+});

package/dist/services/snapshot-builder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snapshot-builder.test.d.ts.map

package/dist/services/snapshot-builder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-builder.test.d.ts","sourceRoot":"","sources":["../../src/services/snapshot-builder.test.ts"],"names":[],"mappings":""}