@voyant-travel/catalog 0.117.2

package/dist/overlay/resolver.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Overlay resolver — applies editorial overlays to a source projection,
+ * walking the variant fallback chain.
+ *
+ * Variant axes are `locale`, `audience`, `market`. The resolver walks an
+ * 8-step fallback (most-specific → least-specific) and applies the matching
+ * overlay value using the merge rule from the field policy.
+ *
+ * Pure logic: no DB access, no IO. Callers fetch overlays by entity in one
+ * query, pass them in here as `OverlayLookup`, and get back the resolved
+ * field value tree.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.2.1 for the fallback
+ * chain and §7.1 for the split rule that keeps merging predictable.
+ */
+import type { FieldPolicy, FieldPolicyRegistry, Visibility } from "../contract.js";
+import { OVERLAY_DEFAULT_SCOPE } from "./schema.js";
+/** A single overlay row reduced to what the resolver needs. */
+export interface ResolverOverlay {
+    field_path: string;
+    locale: string;
+    audience: Visibility | typeof OVERLAY_DEFAULT_SCOPE;
+    market: string;
+    value: unknown;
+}
+/**
+ * The variant-scoped query the caller is asking the resolver to satisfy.
+ * Returned values reflect overlays applicable to this exact tuple, with
+ * fallbacks down through `default` sentinels.
+ */
+export interface ResolverScope {
+    locale: string;
+    audience: Visibility;
+    market: string;
+    /** The actor making the request — used for visibility filtering. */
+    actor: Visibility;
+}
+/**
+ * Set of overlay rows fetched for a single entity. The resolver indexes
+ * them internally by `(field_path, locale, audience, market)` for the
+ * fallback walk.
+ */
+export type OverlayLookup = ReadonlyArray<ResolverOverlay>;
+/**
+ * Resolved-view emitter. Given a per-entity source projection and the
+ * applicable overlays, returns the per-(field_path → value) map after
+ * applying the variant fallback chain, the merge rule, and the visibility
+ * filter for the requesting actor.
+ */
+export interface ResolvedView {
+    /** Resolved values keyed by field path. */
+    values: Map<string, unknown>;
+    /**
+     * Fields the resolver intentionally omitted because they are not visible
+     * to the requesting actor. Useful for debug / "preview as audience X"
+     * views; consumers should not display these.
+     */
+    hidden: Set<string>;
+    /**
+     * Per-field provenance: which variant slice satisfied the lookup. `null`
+     * means the source projection's value was used (no overlay applied).
+     */
+    provenance: Map<string, ResolvedFieldProvenance | null>;
+}
+export interface ResolvedFieldProvenance {
+    locale: string;
+    audience: Visibility | typeof OVERLAY_DEFAULT_SCOPE;
+    market: string;
+}
+/**
+ * The 8-step variant fallback chain, ordered from most-specific to
+ * least-specific. The resolver walks this list and stops at the first
+ * overlay it finds for the requested field path.
+ */
+export declare function variantFallbackChain(scope: ResolverScope): Array<{
+    locale: string;
+    audience: string;
+    market: string;
+}>;
+/**
+ * Applies the field policy's merge rule to combine a source value with an
+ * overlay value. Returns the resolved value.
+ *
+ * Throws if `merge: "source-only"` is configured but an overlay was passed —
+ * this means the overlay-write path validation failed and a forbidden
+ * override slipped through; refuse to honor it at read time.
+ */
+export declare function applyMerge(policy: FieldPolicy, sourceValue: unknown, overlayValue: unknown): unknown;
+/**
+ * Resolves a source projection plus a set of overlays into a final view for
+ * the requesting `(locale, audience, market)` scope, filtered by the actor's
+ * visibility.
+ *
+ * The source projection is keyed by field path; only fields present in the
+ * registry are considered. Fields whose policy hides them from the actor's
+ * audience are placed in `hidden`, not `values`.
+ */
+export declare function resolveOverlay(registry: FieldPolicyRegistry, sourceProjection: ReadonlyMap<string, unknown>, overlays: OverlayLookup, scope: ResolverScope): ResolvedView;
+/** Visibility check: is the field visible to the requesting actor? */
+export declare function isVisibleTo(policy: FieldPolicy, actor: Visibility): boolean;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/overlay/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/overlay/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAa,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC7F,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnD,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,UAAU,GAAG,OAAO,qBAAqB,CAAA;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,UAAU,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,KAAK,EAAE,UAAU,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,eAAe,CAAC,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B;;;;OAIG;IACH,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACnB;;;OAGG;IACH,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,UAAU,GAAG,OAAO,qBAAqB,CAAA;IACnD,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,GACnB,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAa7D;AAyCD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,OAAO,EACpB,YAAY,EAAE,OAAO,GACpB,OAAO,CAET;AAiDD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,mBAAmB,EAC7B,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,aAAa,GACnB,YAAY,CAoCd;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAE3E"}

package/dist/overlay/resolver.js

@@ -0,0 +1,167 @@
+/**
+ * Overlay resolver — applies editorial overlays to a source projection,
+ * walking the variant fallback chain.
+ *
+ * Variant axes are `locale`, `audience`, `market`. The resolver walks an
+ * 8-step fallback (most-specific → least-specific) and applies the matching
+ * overlay value using the merge rule from the field policy.
+ *
+ * Pure logic: no DB access, no IO. Callers fetch overlays by entity in one
+ * query, pass them in here as `OverlayLookup`, and get back the resolved
+ * field value tree.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.2.1 for the fallback
+ * chain and §7.1 for the split rule that keeps merging predictable.
+ */
+import { OVERLAY_DEFAULT_SCOPE } from "./schema.js";
+/**
+ * The 8-step variant fallback chain, ordered from most-specific to
+ * least-specific. The resolver walks this list and stops at the first
+ * overlay it finds for the requested field path.
+ */
+export function variantFallbackChain(scope) {
+    const D = OVERLAY_DEFAULT_SCOPE;
+    const { locale, audience, market } = scope;
+    return [
+        { locale, audience, market },
+        { locale, audience, market: D },
+        { locale, audience: D, market },
+        { locale, audience: D, market: D },
+        { locale: D, audience, market },
+        { locale: D, audience, market: D },
+        { locale: D, audience: D, market },
+        { locale: D, audience: D, market: D },
+    ];
+}
+/**
+ * Indexes overlay rows by `(field_path, locale, audience, market)` for the
+ * resolver's fallback walk. Idempotent — passing the same overlay twice
+ * produces a deterministic last-write-wins (by array position) result.
+ */
+function indexOverlays(overlays) {
+    const byField = new Map();
+    for (const overlay of overlays) {
+        let inner = byField.get(overlay.field_path);
+        if (!inner) {
+            inner = new Map();
+            byField.set(overlay.field_path, inner);
+        }
+        const key = `${overlay.locale}|${overlay.audience}|${overlay.market}`;
+        inner.set(key, overlay);
+    }
+    return byField;
+}
+/**
+ * Looks up the overlay for a single field path under the variant fallback
+ * chain. Returns the first match, or `undefined` if no overlay applies at
+ * any fallback level.
+ */
+function lookupOverlay(byField, fieldPath, scope) {
+    const inner = byField.get(fieldPath);
+    if (!inner)
+        return undefined;
+    for (const variant of variantFallbackChain(scope)) {
+        const key = `${variant.locale}|${variant.audience}|${variant.market}`;
+        const hit = inner.get(key);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * Applies the field policy's merge rule to combine a source value with an
+ * overlay value. Returns the resolved value.
+ *
+ * Throws if `merge: "source-only"` is configured but an overlay was passed —
+ * this means the overlay-write path validation failed and a forbidden
+ * override slipped through; refuse to honor it at read time.
+ */
+export function applyMerge(policy, sourceValue, overlayValue) {
+    return mergeByRule(policy.merge, sourceValue, overlayValue, policy.path);
+}
+function mergeByRule(rule, sourceValue, overlayValue, path) {
+    switch (rule) {
+        case "source-only":
+            throw new Error(`field "${path}" has merge: "source-only" but received an overlay value (overlay-write validation should have rejected this)`);
+        case "replace":
+            return overlayValue;
+        case "additive-set": {
+            const sourceArray = Array.isArray(sourceValue) ? sourceValue : [];
+            const overlayArray = Array.isArray(overlayValue) ? overlayValue : [];
+            // Preserve insertion order; first occurrence wins on duplicates.
+            const seen = new Set();
+            const merged = [];
+            for (const item of [...sourceArray, ...overlayArray]) {
+                if (!seen.has(item)) {
+                    seen.add(item);
+                    merged.push(item);
+                }
+            }
+            return merged;
+        }
+        case "additive-list": {
+            const sourceArray = Array.isArray(sourceValue) ? sourceValue : [];
+            const overlayArray = Array.isArray(overlayValue) ? overlayValue : [];
+            return [...sourceArray, ...overlayArray];
+        }
+        case "list-position": {
+            const sourceArray = Array.isArray(sourceValue) ? [...sourceValue] : [];
+            // overlayValue is a sparse array: positions to override.
+            const overlay = overlayValue;
+            for (const [posStr, value] of Object.entries(overlay)) {
+                const pos = Number(posStr);
+                if (Number.isInteger(pos) && pos >= 0) {
+                    sourceArray[pos] = value;
+                }
+            }
+            return sourceArray;
+        }
+    }
+}
+/**
+ * Resolves a source projection plus a set of overlays into a final view for
+ * the requesting `(locale, audience, market)` scope, filtered by the actor's
+ * visibility.
+ *
+ * The source projection is keyed by field path; only fields present in the
+ * registry are considered. Fields whose policy hides them from the actor's
+ * audience are placed in `hidden`, not `values`.
+ */
+export function resolveOverlay(registry, sourceProjection, overlays, scope) {
+    const indexed = indexOverlays(overlays);
+    const values = new Map();
+    const hidden = new Set();
+    const provenance = new Map();
+    for (const [path, sourceValue] of sourceProjection) {
+        const policy = registry.resolve(path);
+        if (!policy) {
+            // Field exists in the source projection but not in the registry. The
+            // resolver leaves it out — the registry is authoritative about which
+            // fields are part of the catalog projection.
+            continue;
+        }
+        // Visibility filter: skip fields not visible to the requesting actor.
+        if (!isVisibleTo(policy, scope.actor)) {
+            hidden.add(path);
+            continue;
+        }
+        const overlay = lookupOverlay(indexed, path, scope);
+        if (overlay && policy.merge !== "source-only") {
+            values.set(path, applyMerge(policy, sourceValue, overlay.value));
+            provenance.set(path, {
+                locale: overlay.locale,
+                audience: overlay.audience,
+                market: overlay.market,
+            });
+        }
+        else {
+            values.set(path, sourceValue);
+            provenance.set(path, null);
+        }
+    }
+    return { values, hidden, provenance };
+}
+/** Visibility check: is the field visible to the requesting actor? */
+export function isVisibleTo(policy, actor) {
+    return policy.visibility.includes(actor);
+}

package/dist/overlay/resolver.test.d.ts

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

package/dist/overlay/resolver.test.d.ts.map

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

package/dist/overlay/resolver.test.js

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+import { createFieldPolicyRegistry, defineFieldPolicy } from "../contract.js";
+import { applyMerge, resolveOverlay, variantFallbackChain, } from "./resolver.js";
+import { OVERLAY_DEFAULT_SCOPE } from "./schema.js";
+const merchandisable = {
+    class: "merchandisable",
+    merge: "replace",
+    editRole: "marketing",
+    overrideFriction: "none",
+    snapshot: "on-book",
+};
+describe("variantFallbackChain", () => {
+    it("walks 8 steps from most-specific to least-specific", () => {
+        const scope = {
+            locale: "en-GB",
+            audience: "customer",
+            market: "UK",
+            actor: "customer",
+        };
+        const chain = variantFallbackChain(scope);
+        expect(chain).toHaveLength(8);
+        expect(chain[0]).toEqual({ locale: "en-GB", audience: "customer", market: "UK" });
+        expect(chain[7]).toEqual({
+            locale: OVERLAY_DEFAULT_SCOPE,
+            audience: OVERLAY_DEFAULT_SCOPE,
+            market: OVERLAY_DEFAULT_SCOPE,
+        });
+    });
+});
+describe("applyMerge", () => {
+    const policy = (merge) => ({
+        path: "field",
+        class: "merchandisable",
+        merge,
+        drift: "none",
+        reindex: "none",
+        snapshot: "never",
+        query: "blob-only",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: null,
+    });
+    it("replace returns the overlay value", () => {
+        expect(applyMerge(policy("replace"), "source", "overlay")).toBe("overlay");
+    });
+    it("additive-set unions arrays preserving first-occurrence order", () => {
+        expect(applyMerge(policy("additive-set"), ["a", "b"], ["b", "c"])).toEqual(["a", "b", "c"]);
+    });
+    it("additive-list concatenates arrays without dedupe", () => {
+        expect(applyMerge(policy("additive-list"), ["a"], ["a", "b"])).toEqual(["a", "a", "b"]);
+    });
+    it("list-position sparsely overrides positions", () => {
+        expect(applyMerge(policy("list-position"), ["x", "y", "z"], { 1: "Y" })).toEqual([
+            "x",
+            "Y",
+            "z",
+        ]);
+    });
+    it("source-only throws when an overlay is passed", () => {
+        expect(() => applyMerge({ ...policy("replace"), merge: "source-only" }, "source", "overlay")).toThrow(/source-only/);
+    });
+});
+describe("resolveOverlay", () => {
+    const policies = defineFieldPolicy([
+        { path: "title", ...merchandisable, localized: true, visibility: ["staff", "customer"] },
+        { path: "description", ...merchandisable, visibility: ["staff", "customer"] },
+        {
+            path: "internal_notes",
+            ...merchandisable,
+            editRole: "ops",
+            visibility: ["staff"],
+        },
+    ]);
+    const registry = createFieldPolicyRegistry(policies);
+    it("applies an exact-match overlay and records provenance", () => {
+        const source = new Map([["title", "Source title"]]);
+        const overlays = [
+            {
+                field_path: "title",
+                locale: "en-GB",
+                audience: "customer",
+                market: "UK",
+                value: "Marketing title",
+            },
+        ];
+        const view = resolveOverlay(registry, source, overlays, {
+            locale: "en-GB",
+            audience: "customer",
+            market: "UK",
+            actor: "customer",
+        });
+        expect(view.values.get("title")).toBe("Marketing title");
+        expect(view.provenance.get("title")).toEqual({
+            locale: "en-GB",
+            audience: "customer",
+            market: "UK",
+        });
+    });
+    it("falls back from market=UK to market=default when no UK overlay exists", () => {
+        const source = new Map([["title", "Source title"]]);
+        const overlays = [
+            {
+                field_path: "title",
+                locale: "en-GB",
+                audience: "customer",
+                market: OVERLAY_DEFAULT_SCOPE,
+                value: "Default-market title",
+            },
+        ];
+        const view = resolveOverlay(registry, source, overlays, {
+            locale: "en-GB",
+            audience: "customer",
+            market: "UK",
+            actor: "customer",
+        });
+        expect(view.values.get("title")).toBe("Default-market title");
+        expect(view.provenance.get("title")?.market).toBe(OVERLAY_DEFAULT_SCOPE);
+    });
+    it("returns the source value when no overlay matches at any fallback level", () => {
+        const source = new Map([["title", "Source title"]]);
+        const view = resolveOverlay(registry, source, [], {
+            locale: "en-GB",
+            audience: "customer",
+            market: "UK",
+            actor: "customer",
+        });
+        expect(view.values.get("title")).toBe("Source title");
+        expect(view.provenance.get("title")).toBeNull();
+    });
+    it("hides fields not visible to the requesting actor", () => {
+        const source = new Map([
+            ["title", "Source title"],
+            ["internal_notes", "Internal note"],
+        ]);
+        const view = resolveOverlay(registry, source, [], {
+            locale: "en-GB",
+            audience: "customer",
+            market: OVERLAY_DEFAULT_SCOPE,
+            actor: "customer",
+        });
+        expect(view.values.has("title")).toBe(true);
+        expect(view.values.has("internal_notes")).toBe(false);
+        expect(view.hidden.has("internal_notes")).toBe(true);
+    });
+    it("ignores overlays whose field is not in the registry", () => {
+        const source = new Map([["title", "Source title"]]);
+        const overlays = [
+            {
+                field_path: "title",
+                locale: "en-GB",
+                audience: "customer",
+                market: OVERLAY_DEFAULT_SCOPE,
+                value: "Marketing title",
+            },
+        ];
+        const view = resolveOverlay(registry, source, overlays, {
+            locale: "en-GB",
+            audience: "customer",
+            market: OVERLAY_DEFAULT_SCOPE,
+            actor: "customer",
+        });
+        // Source contains "title", but not "phantom" — the resolver should
+        // skip "phantom" because it's not in the registry, but apply title.
+        const sourceWithPhantom = new Map([
+            ["title", "Source title"],
+            ["phantom", "shouldn't appear"],
+        ]);
+        const phantomView = resolveOverlay(registry, sourceWithPhantom, overlays, {
+            locale: "en-GB",
+            audience: "customer",
+            market: OVERLAY_DEFAULT_SCOPE,
+            actor: "customer",
+        });
+        expect(phantomView.values.has("phantom")).toBe(false);
+        expect(view.values.get("title")).toBe("Marketing title");
+    });
+});