@memberjunction/search-engine 5.49.0 → 5.51.0

package/dist/generic/ScopeExplanation.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview The shape of a scope decision — what a search WOULD be able to reach, and why.
+ *
+ * Everything the dimensional-scope work added is a decision made from inputs that are gone by
+ * the time anyone asks about them. A grant applied because a time window happened to be open;
+ * a dimension was discarded because it was caller-authored on a ServerDerived key; a lane was
+ * skipped because its filter lost a clause. Each of those is invisible afterwards — the result
+ * set looks the same whether it was correctly bounded or accidentally widened, so neither an
+ * administrator configuring a scope nor an auditor reconstructing an incident can tell.
+ *
+ * `ScopeExplanation` is that decision, captured. It is used in two places deliberately:
+ *
+ *   1. **Before** a search — `SearchEngine.ExplainScope()` runs the entire resolution chain
+ *      (entitlement → dimensions → lane filters) and returns this WITHOUT querying anything.
+ *      "As this user, on this date, with this skill active: what could this reach?"
+ *   2. **After** a search — the same object is serialized into
+ *      `SearchExecutionLog.ScopeDecisionJSON`.
+ *
+ * One shape for both is the point. The preview an administrator approves is structurally the
+ * record the audit log keeps, so a claim made at configuration time is checkable against what
+ * actually ran, rather than being two representations that can quietly disagree.
+ *
+ * @module @memberjunction/search-engine
+ */
+/**
+ * Render an explanation as human-readable lines.
+ *
+ * Kept as a pure function next to the type rather than inside the engine so a CLI, an
+ * Explorer panel, or a test can format one without constructing a `SearchEngine`.
+ */
+export function SummarizeExplanation(explanation) {
+    const lines = [];
+    lines.push(`Scope: ${explanation.ScopeName} (${explanation.ScopeID})`);
+    const ent = explanation.Entitlement;
+    lines.push(`  Reachable: ${explanation.Reachable ? 'YES' : 'NO'} — ` +
+        (ent
+            ? `entitlement ${ent.Allowed ? 'granted' : 'DENIED'} at ${ent.Level} via ${ent.Source}`
+            : 'entitlement not evaluated at this layer'));
+    if (ent)
+        lines.push(`  Why: ${ent.Reason}`);
+    if (explanation.Dimensions.length) {
+        lines.push('  Dimensions:');
+        for (const d of explanation.Dimensions) {
+            const bound = d.Restricts ? ' [BOUND]' : '';
+            const note = d.Note ? ` — ${d.Note}` : '';
+            lines.push(`    ${d.Name}${bound} = ${JSON.stringify(d.Value)} (${d.Provenance})${note}`);
+        }
+    }
+    else {
+        lines.push('  Dimensions: none declared (legacy scope — the caller context passes through unchecked)');
+    }
+    lines.push('  Lanes:');
+    if (!explanation.Lanes.length) {
+        lines.push('    (NONE CONFIGURED — this scope is UNSCOPED: providers apply no filter)');
+    }
+    for (const lane of explanation.Lanes) {
+        lines.push(`    [${lane.Status}] ${lane.Kind}: ${lane.Target}`);
+        if (lane.RequiredMetadataKeys?.length) {
+            lines.push(`        requires: ${lane.RequiredMetadataKeys.join(', ')}`);
+        }
+        if (lane.RenderedFilter) {
+            lines.push(`        filter: ${lane.RenderedFilter.substring(0, 200)}`);
+        }
+        if (lane.Reason) {
+            lines.push(`        SKIPPED: ${lane.Reason}`);
+        }
+    }
+    for (const d of explanation.Diagnostics)
+        lines.push(`  note: ${d}`);
+    return lines;
+}
+//# sourceMappingURL=ScopeExplanation.js.map

package/dist/generic/ScopeExplanation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeExplanation.js","sourceRoot":"","sources":["../../src/generic/ScopeExplanation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAqHH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAA6B;IAC9D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,UAAU,WAAW,CAAC,SAAS,KAAK,WAAW,CAAC,OAAO,GAAG,CAAC,CAAC;IACvE,MAAM,GAAG,GAAG,WAAW,CAAC,WAAW,CAAC;IACpC,KAAK,CAAC,IAAI,CACN,gBAAgB,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK;QACzD,CAAC,GAAG;YACA,CAAC,CAAC,eAAe,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC,KAAK,QAAQ,GAAG,CAAC,MAAM,EAAE;YACvF,CAAC,CAAC,yCAAyC,CAAC,CACnD,CAAC;IACF,IAAI,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5C,IAAI,WAAW,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,GAAG,KAAK,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC,CAAC;QAC9F,CAAC;IACL,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CAAC,0FAA0F,CAAC,CAAC;IAC3G,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;IAC5F,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAChE,IAAI,IAAI,CAAC,oBAAoB,EAAE,MAAM,EAAE,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAClD,CAAC;IACL,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/generic/ScopeFilterGuard.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Guard for a scope's rendered filter values.
+ *
+ * A scope's `MetadataFilter` is where tenant and permission push-down lives for every
+ * external-index lane. The providers previously applied it behind a bare type guard:
+ *
+ * ```typescript
+ * if (idx.MetadataFilter && typeof idx.MetadataFilter === 'string') { body.filter = idx.MetadataFilter; }
+ * ```
+ *
+ * That conflates two very different situations. If no filter was authored, running
+ * unfiltered is correct. But if a filter **was** authored and merely arrived in an
+ * unusable shape — a template that failed to render, a JSON filter that didn't parse,
+ * an object where the lane needs a string — the guard fell through and the lane ran
+ * **completely unfiltered**, silently dropping the tenant predicate. Breaking the
+ * filter was therefore the cheapest way to defeat it.
+ *
+ * This module makes the distinction explicit so a lane can fail closed:
+ *
+ *   - `absent`   — nothing authored; run unfiltered (unchanged behaviour)
+ *   - `usable`   — apply it
+ *   - `unusable` — a filter was authored but cannot be applied; the caller MUST skip
+ *                  the lane rather than query without it
+ *
+ * @module @memberjunction/search-engine
+ */
+/**
+ * Outcome of checking a scope's rendered filter value for a particular lane.
+ *
+ * `unusable` is the case that matters: it means an author intended a restriction that
+ * the lane cannot express, so proceeding would silently widen the search.
+ */
+export type ScopeFilterCheck<T> = {
+    Status: 'absent';
+} | {
+    Status: 'usable';
+    Value: T;
+} | {
+    Status: 'unusable';
+    Reason: string;
+};
+/**
+ * Check a filter for a lane that needs a **string** (Azure AI Search OData `$filter`,
+ * Typesense `filter_by`).
+ *
+ * An object here means the scope's template rendered JSON for a lane that cannot consume
+ * it — authored intent that cannot be applied, hence `unusable` rather than ignored.
+ */
+export declare function CheckScopeStringFilter(raw: unknown): ScopeFilterCheck<string>;
+/**
+ * Check a filter for a lane that needs a structured **object** (Elasticsearch /
+ * OpenSearch filter DSL).
+ *
+ * A leftover string means the rendered template never parsed as JSON — usually a render
+ * failure or malformed JSON in the scope definition.
+ */
+export declare function CheckScopeObjectFilter(raw: unknown): ScopeFilterCheck<object>;
+/**
+ * Check a **rendered** scope template against its source, for fields that RESTRICT
+ * (`ExtraFilter`, `MetadataFilter`, `ExternalIndexConfig`).
+ *
+ * This catches the two ways a restriction can evaporate during rendering, neither of which
+ * the value alone can reveal — by the time a provider sees the constraint, the source
+ * template has been discarded, so "authored but rendered to nothing" is indistinguishable
+ * from "never authored":
+ *
+ *  1. **Rendered empty.** `RenderScopeTemplate` runs Nunjucks with `throwOnUndefined: false`,
+ *     so a mistyped dimension (`SecondaryScopes.EffectiveChanneID`) makes a `{% if %}` guard
+ *     false and the entire restricting clause silently disappears — the lane then runs
+ *     unrestricted. (We deliberately do NOT flip `throwOnUndefined`: legitimate templates
+ *     output optional dimensions, and flipping it would break them all.)
+ *  2. **Template leaked through.** On a render error `RenderScopeTemplate` returns the RAW
+ *     template, so `{% if %}`/`{{ }}` syntax reaches a filter as literal text.
+ *
+ * @param source   the un-rendered template from the scope row
+ * @param rendered the output of RenderScopeTemplate / RenderScopeJsonTemplate
+ */
+export declare function CheckRenderedTemplate(source: string | null | undefined, rendered: unknown): ScopeFilterCheck<unknown>;
+/**
+ * Parse a `RequiredMetadataKeys` declaration into a list of key names.
+ *
+ * Accepts a JSON array (`["OrganizationID","ContentSourceID"]`) or a comma-separated
+ * string, because both shapes turn up in hand-authored metadata. Returns an empty array
+ * when nothing is declared.
+ *
+ * @throws {Error} when a value IS declared but cannot be parsed. A malformed contract must
+ *   not silently degrade to "no contract" — that would turn a typo into an unguarded lane,
+ *   which is the exact failure this feature exists to prevent.
+ */
+export declare function ParseRequiredMetadataKeys(raw: string | null | undefined): string[];
+/**
+ * Check that a **rendered** metadata filter actually constrains on every key its scope
+ * declared in `RequiredMetadataKeys`.
+ *
+ * This catches the failure mode {@link CheckRenderedTemplate} structurally cannot: a filter
+ * that rendered **partially**. A realistic scope filter is several optional clauses —
+ *
+ * ```
+ * {"OrganizationID": "{{ ctx.PrimaryScopeRecordID }}"
+ *  {% if ctx.SecondaryScopes.EffectiveChannelID %}, "ContentSourceID": {...}{% endif %}}
+ * ```
+ *
+ * — and if the channel dimension is absent (a mistyped dimension name, a caller that omitted
+ * it, a value the dimension resolver discarded as spoofed) the org clause still renders. The
+ * filter is non-empty, contains no leftover template syntax, and passes every other guard,
+ * yet the lane now searches the entire tenant instead of the one channel. The restriction
+ * did not fail; it evaporated, and nothing downstream can tell the difference.
+ *
+ * Declaring the keys makes the author's intent checkable. The check is deliberately a
+ * **presence** test rather than a semantic one: proving that a filter genuinely restricts on
+ * a key would mean interpreting five different provider filter dialects. Presence is cheap,
+ * dialect-agnostic, and catches the whole vanished-clause class, which is what actually
+ * happens in practice.
+ *
+ * @param rendered the rendered filter — a JSON string, or an already-parsed object
+ * @param requiredKeys key names from `ParseRequiredMetadataKeys`
+ */
+export declare function CheckRequiredMetadataKeys(rendered: unknown, requiredKeys: string[]): ScopeFilterCheck<unknown>;
+/**
+ * Check a filter for a lane that needs **JSON** and will accept either an already-parsed
+ * object or a JSON string it can parse itself (vector metadata filters).
+ *
+ * A string that fails to parse is `unusable`. This is the specific path that previously
+ * dropped the whole filter — including the tenant clause — and queried the entire index.
+ */
+export declare function CheckScopeJsonFilter(raw: unknown): ScopeFilterCheck<object>;
+//# sourceMappingURL=ScopeFilterGuard.d.ts.map

package/dist/generic/ScopeFilterGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeFilterGuard.d.ts","sourceRoot":"","sources":["../../src/generic/ScopeFilterGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IACxB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC9B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ7C;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAO7E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAU7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAkBrH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAsClF;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAiB9G;AAyDD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAoB3E"}

package/dist/generic/ScopeFilterGuard.js

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Guard for a scope's rendered filter values.
+ *
+ * A scope's `MetadataFilter` is where tenant and permission push-down lives for every
+ * external-index lane. The providers previously applied it behind a bare type guard:
+ *
+ * ```typescript
+ * if (idx.MetadataFilter && typeof idx.MetadataFilter === 'string') { body.filter = idx.MetadataFilter; }
+ * ```
+ *
+ * That conflates two very different situations. If no filter was authored, running
+ * unfiltered is correct. But if a filter **was** authored and merely arrived in an
+ * unusable shape — a template that failed to render, a JSON filter that didn't parse,
+ * an object where the lane needs a string — the guard fell through and the lane ran
+ * **completely unfiltered**, silently dropping the tenant predicate. Breaking the
+ * filter was therefore the cheapest way to defeat it.
+ *
+ * This module makes the distinction explicit so a lane can fail closed:
+ *
+ *   - `absent`   — nothing authored; run unfiltered (unchanged behaviour)
+ *   - `usable`   — apply it
+ *   - `unusable` — a filter was authored but cannot be applied; the caller MUST skip
+ *                  the lane rather than query without it
+ *
+ * @module @memberjunction/search-engine
+ */
+/** True when a value carries no authored filter at all (null/undefined/blank string). */
+function isAbsent(raw) {
+    if (raw === null || raw === undefined)
+        return true;
+    return typeof raw === 'string' && raw.trim().length === 0;
+}
+/**
+ * Check a filter for a lane that needs a **string** (Azure AI Search OData `$filter`,
+ * Typesense `filter_by`).
+ *
+ * An object here means the scope's template rendered JSON for a lane that cannot consume
+ * it — authored intent that cannot be applied, hence `unusable` rather than ignored.
+ */
+export function CheckScopeStringFilter(raw) {
+    if (isAbsent(raw))
+        return { Status: 'absent' };
+    if (typeof raw === 'string')
+        return { Status: 'usable', Value: raw };
+    return {
+        Status: 'unusable',
+        Reason: `expected a string filter for this lane but got ${typeof raw}; the scope's MetadataFilter likely rendered JSON for a lane that requires a string`,
+    };
+}
+/**
+ * Check a filter for a lane that needs a structured **object** (Elasticsearch /
+ * OpenSearch filter DSL).
+ *
+ * A leftover string means the rendered template never parsed as JSON — usually a render
+ * failure or malformed JSON in the scope definition.
+ */
+export function CheckScopeObjectFilter(raw) {
+    if (isAbsent(raw))
+        return { Status: 'absent' };
+    if (typeof raw === 'object')
+        return { Status: 'usable', Value: raw };
+    if (typeof raw === 'string') {
+        return {
+            Status: 'unusable',
+            Reason: `expected a structured filter object but got a string; the scope's MetadataFilter did not render to valid JSON: ${raw.trim().substring(0, 120)}`,
+        };
+    }
+    return { Status: 'unusable', Reason: `expected a structured filter object but got ${typeof raw}` };
+}
+/**
+ * Check a **rendered** scope template against its source, for fields that RESTRICT
+ * (`ExtraFilter`, `MetadataFilter`, `ExternalIndexConfig`).
+ *
+ * This catches the two ways a restriction can evaporate during rendering, neither of which
+ * the value alone can reveal — by the time a provider sees the constraint, the source
+ * template has been discarded, so "authored but rendered to nothing" is indistinguishable
+ * from "never authored":
+ *
+ *  1. **Rendered empty.** `RenderScopeTemplate` runs Nunjucks with `throwOnUndefined: false`,
+ *     so a mistyped dimension (`SecondaryScopes.EffectiveChanneID`) makes a `{% if %}` guard
+ *     false and the entire restricting clause silently disappears — the lane then runs
+ *     unrestricted. (We deliberately do NOT flip `throwOnUndefined`: legitimate templates
+ *     output optional dimensions, and flipping it would break them all.)
+ *  2. **Template leaked through.** On a render error `RenderScopeTemplate` returns the RAW
+ *     template, so `{% if %}`/`{{ }}` syntax reaches a filter as literal text.
+ *
+ * @param source   the un-rendered template from the scope row
+ * @param rendered the output of RenderScopeTemplate / RenderScopeJsonTemplate
+ */
+export function CheckRenderedTemplate(source, rendered) {
+    if (isAbsent(source))
+        return { Status: 'absent' };
+    const renderedIsEmpty = rendered === null || rendered === undefined
+        || (typeof rendered === 'string' && rendered.trim().length === 0);
+    if (renderedIsEmpty) {
+        return {
+            Status: 'unusable',
+            Reason: `a restricting template was authored but rendered to nothing, so the restriction would vanish — usually an undefined dimension in a {% if %} guard (Nunjucks runs with throwOnUndefined:false). Template: ${String(source).substring(0, 160)}`,
+        };
+    }
+    if (typeof rendered === 'string' && (rendered.includes('{{') || rendered.includes('{%'))) {
+        return {
+            Status: 'unusable',
+            Reason: `the template did not render — raw template syntax survived into the value, which means RenderScopeTemplate hit an error and returned the source verbatim: ${rendered.substring(0, 160)}`,
+        };
+    }
+    return { Status: 'usable', Value: rendered };
+}
+/**
+ * Parse a `RequiredMetadataKeys` declaration into a list of key names.
+ *
+ * Accepts a JSON array (`["OrganizationID","ContentSourceID"]`) or a comma-separated
+ * string, because both shapes turn up in hand-authored metadata. Returns an empty array
+ * when nothing is declared.
+ *
+ * @throws {Error} when a value IS declared but cannot be parsed. A malformed contract must
+ *   not silently degrade to "no contract" — that would turn a typo into an unguarded lane,
+ *   which is the exact failure this feature exists to prevent.
+ */
+export function ParseRequiredMetadataKeys(raw) {
+    if (isAbsent(raw))
+        return [];
+    const trimmed = String(raw).trim();
+    if (trimmed.startsWith('{')) {
+        // A JSON object is a shape the author clearly meant as structured data. Falling through
+        // to the comma-split branch would turn the entire literal into one nonsense "key name"
+        // that no filter can ever satisfy, permanently skipping the lane with a reason nobody
+        // can act on. Reject it as the malformed declaration it is.
+        throw new Error(`RequiredMetadataKeys must be a JSON array or a comma-separated list of key names, but got a JSON object: ${trimmed.substring(0, 120)}`);
+    }
+    let keys;
+    if (trimmed.startsWith('[')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error(`RequiredMetadataKeys is not valid JSON: ${trimmed.substring(0, 120)}`);
+        }
+        if (!Array.isArray(parsed))
+            throw new Error(`RequiredMetadataKeys must be a JSON array, got ${typeof parsed}`);
+        keys = parsed.map((k) => String(k).trim());
+        if (keys.some((k) => k.length === 0))
+            throw new Error('RequiredMetadataKeys contains a blank key name');
+    }
+    else {
+        keys = trimmed.split(',').map((k) => k.trim()).filter((k) => k.length > 0);
+    }
+    // Metadata keys are identifiers. Anything else is a typo — an unbalanced bracket, a stray
+    // quote — and a typo'd key silently disables the lane forever, since no rendered filter can
+    // contain it. Naming the bad token is far more useful than a lane that never runs.
+    const malformed = keys.filter((k) => !VALID_METADATA_KEY_RE.test(k));
+    if (malformed.length) {
+        throw new Error(`RequiredMetadataKeys contains value(s) that are not valid metadata key names: ${malformed.map((k) => JSON.stringify(k)).join(', ')}`);
+    }
+    return keys;
+}
+/** Metadata key names are identifiers; dots and dashes are allowed for nested/hyphenated labels. */
+const VALID_METADATA_KEY_RE = /^[A-Za-z_][A-Za-z0-9_.\-]*$/;
+/**
+ * Check that a **rendered** metadata filter actually constrains on every key its scope
+ * declared in `RequiredMetadataKeys`.
+ *
+ * This catches the failure mode {@link CheckRenderedTemplate} structurally cannot: a filter
+ * that rendered **partially**. A realistic scope filter is several optional clauses —
+ *
+ * ```
+ * {"OrganizationID": "{{ ctx.PrimaryScopeRecordID }}"
+ *  {% if ctx.SecondaryScopes.EffectiveChannelID %}, "ContentSourceID": {...}{% endif %}}
+ * ```
+ *
+ * — and if the channel dimension is absent (a mistyped dimension name, a caller that omitted
+ * it, a value the dimension resolver discarded as spoofed) the org clause still renders. The
+ * filter is non-empty, contains no leftover template syntax, and passes every other guard,
+ * yet the lane now searches the entire tenant instead of the one channel. The restriction
+ * did not fail; it evaporated, and nothing downstream can tell the difference.
+ *
+ * Declaring the keys makes the author's intent checkable. The check is deliberately a
+ * **presence** test rather than a semantic one: proving that a filter genuinely restricts on
+ * a key would mean interpreting five different provider filter dialects. Presence is cheap,
+ * dialect-agnostic, and catches the whole vanished-clause class, which is what actually
+ * happens in practice.
+ *
+ * @param rendered the rendered filter — a JSON string, or an already-parsed object
+ * @param requiredKeys key names from `ParseRequiredMetadataKeys`
+ */
+export function CheckRequiredMetadataKeys(rendered, requiredKeys) {
+    if (requiredKeys.length === 0)
+        return { Status: 'usable', Value: rendered };
+    if (isAbsent(rendered)) {
+        return {
+            Status: 'unusable',
+            Reason: `this lane declares RequiredMetadataKeys [${requiredKeys.join(', ')}] but no filter was rendered at all, so none of them constrain the search`,
+        };
+    }
+    const present = collectFilterKeys(rendered);
+    const missing = requiredKeys.filter((k) => !present.has(k.toLowerCase()));
+    if (missing.length === 0)
+        return { Status: 'usable', Value: rendered };
+    return {
+        Status: 'unusable',
+        Reason: `the rendered filter does not constrain on required metadata key${missing.length > 1 ? 's' : ''} [${missing.join(', ')}] — the clause was almost certainly dropped because a dimension it depends on was absent or discarded, which would widen this lane. Rendered: ${renderedPreview(rendered)}`,
+    };
+}
+/**
+ * Collect every key name a rendered filter mentions, lowercased.
+ *
+ * For an object (or a JSON string that parses to one) this walks the structure and gathers
+ * property names at every depth, so a key nested inside a provider's boolean wrapper
+ * (`{"$and":[{"OrganizationID":…}]}`) still counts. For a non-JSON string — Azure OData,
+ * Typesense `filter_by` — it falls back to identifier tokens, since those dialects express
+ * a constraint as `Key eq 'value'` rather than as structure.
+ */
+function collectFilterKeys(rendered) {
+    const keys = new Set();
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (node !== null && typeof node === 'object') {
+            for (const [key, value] of Object.entries(node)) {
+                keys.add(key.toLowerCase());
+                walk(value);
+            }
+        }
+    };
+    if (typeof rendered === 'string') {
+        const trimmed = rendered.trim();
+        if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+            try {
+                walk(JSON.parse(trimmed));
+                return keys;
+            }
+            catch {
+                // Not JSON after all — fall through to token scanning.
+            }
+        }
+        // Strip quoted literals BEFORE tokenizing. Without this, a filter that merely mentions
+        // the key name as a VALUE — `Title eq 'ContentSourceID'` — satisfies a contract it does
+        // not actually constrain on, which is a fail-open. The structured path never had this
+        // problem because a JSON walk distinguishes keys from values by position; a flat string
+        // has to earn that distinction by removing the places values live.
+        const withoutLiterals = trimmed.replace(/'(?:[^']|'')*'/g, "''").replace(/"(?:[^"\\]|\\.)*"/g, '""');
+        for (const token of withoutLiterals.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? [])
+            keys.add(token.toLowerCase());
+        return keys;
+    }
+    walk(rendered);
+    return keys;
+}
+/** Short, safe preview of a rendered filter for an error message. */
+function renderedPreview(rendered) {
+    const text = typeof rendered === 'string' ? rendered : JSON.stringify(rendered);
+    return (text ?? '').substring(0, 160);
+}
+/**
+ * Check a filter for a lane that needs **JSON** and will accept either an already-parsed
+ * object or a JSON string it can parse itself (vector metadata filters).
+ *
+ * A string that fails to parse is `unusable`. This is the specific path that previously
+ * dropped the whole filter — including the tenant clause — and queried the entire index.
+ */
+export function CheckScopeJsonFilter(raw) {
+    if (isAbsent(raw))
+        return { Status: 'absent' };
+    if (typeof raw === 'object')
+        return { Status: 'usable', Value: raw };
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed !== null && typeof parsed === 'object')
+                return { Status: 'usable', Value: parsed };
+            return {
+                Status: 'unusable',
+                Reason: `MetadataFilter parsed to a ${typeof parsed} rather than an object: ${trimmed.substring(0, 120)}`,
+            };
+        }
+        catch {
+            return {
+                Status: 'unusable',
+                Reason: `MetadataFilter is not valid JSON: ${trimmed.substring(0, 120)}`,
+            };
+        }
+    }
+    return { Status: 'unusable', Reason: `MetadataFilter has unsupported type ${typeof raw}` };
+}
+//# sourceMappingURL=ScopeFilterGuard.js.map

package/dist/generic/ScopeFilterGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeFilterGuard.js","sourceRoot":"","sources":["../../src/generic/ScopeFilterGuard.ts"],"names":[],"mappings":"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"}

package/dist/generic/ScopeTemplateRenderer.d.ts

@@ -17,13 +17,23 @@
  *
  * @module @memberjunction/search-engine
  */
+import { type ScopeLaneKind } from './ScopeValueEscaper.js';
 import { SearchContext } from './search.types.js';
 /**
  * Render a scope template string with the supplied SearchContext. Returns the original
  * string unchanged when `template` is null/empty. Returns the original string on render
  * failure (logged via LogError) so a single bad template does not bring down a search.
  */
-export declare function RenderScopeTemplate(template: string | null | undefined, context: SearchContext | undefined, extraData?: Record<string, unknown>): string;
+export declare function RenderScopeTemplate(template: string | null | undefined, context: SearchContext | undefined, extraData?: Record<string, unknown>, 
+/**
+ * The dialect this template renders into (§5.4). Every interpolated context value is escaped
+ * for it automatically, so an author never has to remember.
+ *
+ * Defaults to `'none'` rather than to a guess: this function also renders NON-filter fields
+ * (`UserSearchString`, query transforms) where the value becomes search text, and escaping
+ * those would corrupt the query rather than protect it. Filter call sites pass their real kind.
+ */
+laneKind?: ScopeLaneKind): string;
 /**
  * Render and parse a JSON-valued scope template (used for `MetadataFilter` values).
  * Returns:
@@ -32,5 +42,5 @@ export declare function RenderScopeTemplate(template: string | null | undefined,
  *   - the raw rendered string when it is non-empty but not JSON (provider can decide what to do)
  *   - `undefined` when render fails outright
  */
-export declare function RenderScopeJsonTemplate(template: string | null | undefined, context: SearchContext | undefined, extraData?: Record<string, unknown>): unknown;
+export declare function RenderScopeJsonTemplate(template: string | null | undefined, context: SearchContext | undefined, extraData?: Record<string, unknown>, laneKind?: ScopeLaneKind): unknown;
 //# sourceMappingURL=ScopeTemplateRenderer.d.ts.map

package/dist/generic/ScopeTemplateRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScopeTemplateRenderer.d.ts","sourceRoot":"","sources":["../../src/generic/ScopeTemplateRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAwC/C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,MAAM,CAmBR;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAWT"}
+{"version":3,"file":"ScopeTemplateRenderer.d.ts","sourceRoot":"","sources":["../../src/generic/ScopeTemplateRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAwC/C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;AACnC;;;;;;;GAOG;AACH,QAAQ,GAAE,aAAsB,GACjC,MAAM,CA6BR;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,GAAE,aAAsB,GACjC,OAAO,CAWT"}

package/dist/generic/ScopeTemplateRenderer.js

@@ -18,6 +18,7 @@
  * @module @memberjunction/search-engine
  */
 import nunjucks from 'nunjucks';
+import { EscapeScopeValueDeep } from './ScopeValueEscaper.js';
 import { LogError } from '@memberjunction/core';
 /** Environment used for all ad-hoc scope template rendering. */
 const env = new nunjucks.Environment(null, {
@@ -64,16 +65,35 @@ env.addFilter('jsonparse', (value) => {
  * string unchanged when `template` is null/empty. Returns the original string on render
  * failure (logged via LogError) so a single bad template does not bring down a search.
  */
-export function RenderScopeTemplate(template, context, extraData) {
+export function RenderScopeTemplate(template, context, extraData, 
+/**
+ * The dialect this template renders into (§5.4). Every interpolated context value is escaped
+ * for it automatically, so an author never has to remember.
+ *
+ * Defaults to `'none'` rather than to a guess: this function also renders NON-filter fields
+ * (`UserSearchString`, query transforms) where the value becomes search text, and escaping
+ * those would corrupt the query rather than protect it. Filter call sites pass their real kind.
+ */
+laneKind = 'none') {
     if (!template)
         return '';
     if (!template.includes('{{') && !template.includes('{%')) {
         // No templating syntax — skip the renderer entirely
         return template;
     }
+    // `context` is escaped for the lane; `contextRaw` is the untouched original. Deliberate raw
+    // insertion is therefore spelled `{{ contextRaw.X }}` — one grep finds every such site, which
+    // is the point. A post-escape `| raw` filter could not do this: by the time a filter runs the
+    // original value is already gone.
     const data = {
-        context: context ?? {},
-        ...(extraData ?? {})
+        context: EscapeScopeValueDeep(context ?? {}, laneKind),
+        contextRaw: context ?? {},
+        // extraData is escaped too. It previously spread in un-escaped, which meant the one exported
+        // function whose entire job is escaping had a silent bypass sitting in its signature. No
+        // in-repo caller passes it today, so this was latent rather than live — but leaving an
+        // unescaped channel in a security primitive is how a future caller introduces an injection
+        // without touching this file or noticing anything.
+        ...EscapeScopeValueDeep(extraData ?? {}, laneKind)
     };
     try {
         return env.renderString(template, data);
@@ -92,10 +112,10 @@ export function RenderScopeTemplate(template, context, extraData) {
  *   - the raw rendered string when it is non-empty but not JSON (provider can decide what to do)
  *   - `undefined` when render fails outright
  */
-export function RenderScopeJsonTemplate(template, context, extraData) {
+export function RenderScopeJsonTemplate(template, context, extraData, laneKind = 'json') {
     if (!template)
         return undefined;
-    const rendered = RenderScopeTemplate(template, context, extraData);
+    const rendered = RenderScopeTemplate(template, context, extraData, laneKind);
     const trimmed = rendered.trim();
     if (!trimmed)
         return undefined;

package/dist/generic/ScopeTemplateRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"ScopeTemplateRenderer.js","sourceRoot":"","sources":["../../src/generic/ScopeTemplateRenderer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScopeTemplateRenderer.js","sourceRoot":"","sources":["../../src/generic/ScopeTemplateRenderer.ts"],"names":[],"mappings":"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"}