@memberjunction/search-engine 5.49.0 → 5.51.0

package/dist/generic/ScopeDimensionResolver.js

@@ -0,0 +1,464 @@
+/**
+ * @fileoverview Resolves a scope's declared Search Context dimensions.
+ *
+ * `SearchScope.SearchContextConfig` has always documented `dimensions[]`,
+ * `inheritanceMode` and `strictValidation` — but nothing read it. Dimensions therefore
+ * arrived as a free-form bag that **any** caller could author, including an LLM writing a
+ * tool call: `parseSecondaryScopes` type-cleaned the JSON and handed it straight to the
+ * template renderer. A value anyone in the call chain can set is a narrowing convenience,
+ * not an access bound, which is why apps that encoded a boundary as a dimension were doing
+ * something the platform could not honour.
+ *
+ * This resolver makes the declaration enforceable:
+ *
+ *  - **`trust: 'ServerDerived'` ⇒ caller values for that key are DISCARDED**, and the value
+ *    is derived by the engine (an approved `MJ: Queries` row, or a declared default). This is
+ *    the anti-spoof rule and the reason a dimension can now carry an access decision.
+ *  - **`valueType` is enforced.** A value failing its grammar REJECTS the search rather than
+ *    being coerced or silently dropped.
+ *  - **`freetext` is forbidden on a restricting dimension** — free text interpolated into a
+ *    filter cannot be made safe by validation; it belongs in the query, not the bound.
+ *  - **`narrowingOf` is a lattice meet**, so a caller can only ever narrow a server-derived
+ *    dimension. Never widen.
+ *  - **`strictValidation` has teeth** — an undeclared caller key rejects the search.
+ *
+ * Backwards compatibility is the design constraint: a scope whose `SearchContextConfig` is
+ * null or has no dimensions is returned **untouched**, so every existing scope behaves
+ * exactly as before.
+ *
+ * @module @memberjunction/search-engine
+ */
+import { LogStatus, RunQuery } from '@memberjunction/core';
+/** Thrown when resolution cannot proceed safely. Callers must fail the search closed. */
+export class ScopeDimensionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScopeDimensionError';
+    }
+}
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+export class ScopeDimensionResolver {
+    /**
+     * Resolve the effective Search Context for a scope.
+     *
+     * @throws {ScopeDimensionError} when a declared dimension cannot be resolved safely —
+     *   the caller MUST fail the search rather than proceed with a partial bound.
+     */
+    async Resolve(input) {
+        const diagnostics = [];
+        const config = this.parseConfig(input.Scope);
+        // No declaration ⇒ legacy behaviour, untouched. This is what keeps every existing
+        // scope working byte-for-byte.
+        if (!config || !config.dimensions?.length) {
+            return { Context: input.CallerContext, Diagnostics: diagnostics, Provenance: [] };
+        }
+        const callerScopes = input.CallerContext?.SecondaryScopes ?? {};
+        const declared = new Map(config.dimensions.map((d) => [d.name, d]));
+        this.rejectUndeclaredKeys(config, declared, callerScopes, input.Scope);
+        this.validateDeclaration(config, input.Scope);
+        const resolved = {};
+        const provenance = [];
+        for (const dim of this.orderByDependency(config.dimensions)) {
+            // §5.12 — an ADVISORY dimension fails SOFT. A boundary that cannot be resolved must
+            // refuse the search; an advisory one must not, because its only power is to remove
+            // content from an already-entitled set. Dropping it leaves a superseded corpus in the
+            // results, which is a relevance regression, not an access one.
+            const outcome = dim.advisory === true
+                ? await this.resolveAdvisory(dim, callerScopes, resolved, input, diagnostics)
+                : await this.resolveOne(dim, callerScopes, resolved, input, diagnostics);
+            if (outcome.Value !== undefined && outcome.Value !== null)
+                resolved[dim.name] = outcome.Value;
+            provenance.push({
+                Name: dim.name,
+                Value: outcome.Value ?? null,
+                Provenance: outcome.Provenance,
+                Restricts: dim.restricts === true,
+                // Effective mode, not the raw declaration: a boundary with no explicit mode is
+                // strict, and an auditor should see what was ENFORCED rather than what was written.
+                InheritanceMode: dim.inheritanceMode ?? (dim.restricts === true ? 'strict' : 'cascading'),
+                Note: outcome.Note,
+            });
+        }
+        return {
+            Context: {
+                PrimaryScopeEntityID: input.CallerContext?.PrimaryScopeEntityID,
+                PrimaryScopeRecordID: input.CallerContext?.PrimaryScopeRecordID,
+                SecondaryScopes: Object.keys(resolved).length ? resolved : undefined,
+            },
+            Diagnostics: diagnostics,
+            Provenance: provenance,
+        };
+    }
+    /** Parse the scope's declaration; a malformed config fails closed rather than being ignored. */
+    parseConfig(scope) {
+        const raw = scope.SearchContextConfig;
+        if (!raw || !raw.trim())
+            return null;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object')
+                throw new Error('not an object');
+            return parsed;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new ScopeDimensionError(`SearchScope "${scope.Name}" has a SearchContextConfig that is not valid JSON (${msg}). ` +
+                `Refusing to search: the scope declares dimensions but they cannot be read, so no bound can be enforced.`);
+        }
+    }
+    /**
+     * Validate the DECLARATION itself, before any dimension is dispatched.
+     *
+     * This has to run here rather than inside per-dimension resolution. `advisory` routes to a
+     * fail-soft path that deliberately swallows errors, so a contradiction checked *inside* that path
+     * would be swallowed too — and the failure mode was the worst available one: a dimension
+     * declaring `restricts: true` alongside `advisory: true` was silently given the advisory
+     * posture, i.e. a declared boundary quietly became droppable. Found by a test, not by review.
+     */
+    validateDeclaration(config, scope) {
+        for (const dim of config.dimensions) {
+            if (dim.restricts === true && dim.advisory === true) {
+                throw new ScopeDimensionError(`SearchScope "${scope.Name}" dimension "${dim.name}" declares BOTH restricts:true and ` +
+                    `advisory:true. A boundary must fail closed and may never be dropped; an advisory ` +
+                    `dimension fails soft and may only subtract. Pick one — if it carries an access ` +
+                    `decision it is not advisory.`);
+            }
+            // §5.9 — a boundary defaults to STRICT; choosing the permissive mode must be explicit.
+            // `inheritanceMode` was the exact failure this resolver exists to fix, reproduced: the
+            // field shipped in the declaration type and NOTHING read it, so `cascading` on a
+            // boundary looked configured while behaving as an unenforced comment.
+            if (dim.restricts === true && dim.inheritanceMode === 'cascading'
+                && dim.acknowledgeCascadingOnBoundary !== true) {
+                throw new ScopeDimensionError(`Dimension "${dim.name}" is restricting and declares inheritanceMode 'cascading', which is ` +
+                    `PERMISSIVE — content lacking the dimension would apply to everyone, widening the bound. ` +
+                    `If that is genuinely intended, set "acknowledgeCascadingOnBoundary": true on the dimension ` +
+                    `so the choice is deliberate and greppable. Otherwise use 'strict' (the default for a boundary).`);
+            }
+            if (dim.restricts === true && dim.valueType === 'freetext') {
+                throw new ScopeDimensionError(`Dimension "${dim.name}" is restricting but declares valueType 'freetext'. Free text cannot ` +
+                    `be made safe inside a filter — model it as a query input instead.`);
+            }
+            if (dim.supersededByRules?.length && dim.advisory !== true) {
+                throw new ScopeDimensionError(`SearchScope "${scope.Name}" dimension "${dim.name}" declares supersededByRules but is not ` +
+                    `advisory:true. Supersession rules may only ever REMOVE content; allowing them on a ` +
+                    `non-advisory dimension would let an ordered rule participate in the bound.`);
+            }
+            for (const rule of dim.supersededByRules ?? []) {
+                if (!rule.key || !Object.keys(rule.when ?? {}).length) {
+                    throw new ScopeDimensionError(`SearchScope "${scope.Name}" dimension "${dim.name}" has a supersession rule missing ` +
+                        `"key" or "when". A rule with no conditions would fire unconditionally.`);
+                }
+            }
+        }
+    }
+    /** `strictValidation` with teeth — previously this only warned and used the value anyway. */
+    rejectUndeclaredKeys(config, declared, callerScopes, scope) {
+        if (!config.strictValidation)
+            return;
+        const undeclared = Object.keys(callerScopes).filter((k) => !declared.has(k));
+        if (undeclared.length) {
+            throw new ScopeDimensionError(`SearchScope "${scope.Name}" has strictValidation enabled and the caller supplied undeclared ` +
+                `dimension(s): ${undeclared.join(', ')}. Refusing to search.`);
+        }
+    }
+    /** Resolve `narrowingOf` targets before their dependents; otherwise declaration order. */
+    orderByDependency(dimensions) {
+        const byName = new Map(dimensions.map((d) => [d.name, d]));
+        const out = [];
+        const seen = new Set();
+        const visit = (d, chain) => {
+            if (seen.has(d.name))
+                return;
+            if (chain.has(d.name)) {
+                throw new ScopeDimensionError(`Dimension "${d.name}" has a circular narrowingOf chain.`);
+            }
+            if (d.narrowingOf) {
+                const target = byName.get(d.narrowingOf);
+                if (!target) {
+                    throw new ScopeDimensionError(`Dimension "${d.name}" declares narrowingOf "${d.narrowingOf}", which is not a declared dimension.`);
+                }
+                visit(target, new Set([...chain, d.name]));
+            }
+            seen.add(d.name);
+            out.push(d);
+        };
+        for (const d of dimensions)
+            visit(d, new Set());
+        // Advisory dimensions resolve LAST: their ordered rules read the values other dimensions
+        // produced, so they cannot be evaluated until those exist.
+        return [...out.filter((d) => d.advisory !== true), ...out.filter((d) => d.advisory === true)];
+    }
+    /**
+     * Resolve an advisory (§5.12 supersession) dimension. Never throws.
+     *
+     * Every failure path here degrades to "no supersession" rather than to a refused search. That
+     * asymmetry with {@link resolveOne} is the entire point of the section: entitlement composes by
+     * intersection and fails closed; supersession only subtracts and fails soft.
+     */
+    async resolveAdvisory(dim, callerScopes, alreadyResolved, input, diagnostics) {
+        if (dim.supersededByRules?.length) {
+            const hit = this.firstMatchingRule(dim.supersededByRules, alreadyResolved);
+            if (!hit) {
+                diagnostics.push(`no supersession rule matched for advisory dimension "${dim.name}" — nothing superseded`);
+                return { Value: undefined, Provenance: 'Absent' };
+            }
+            diagnostics.push(`supersession rule matched for "${dim.name}" -> "${hit.key}"${hit.because ? ` (${hit.because})` : ''}`);
+            return {
+                Value: hit.key,
+                Provenance: 'RuleDerived',
+                Note: hit.because ?? `matched rule when=${JSON.stringify(hit.when)}`,
+            };
+        }
+        // No rules declared: fall back to the ordinary paths, but swallow any failure.
+        try {
+            return await this.resolveOne(dim, callerScopes, alreadyResolved, input, diagnostics);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            diagnostics.push(`advisory dimension "${dim.name}" could not be resolved and was DROPPED (fail-soft): ${msg}`);
+            LogStatus(`ScopeDimensionResolver: advisory dimension "${dim.name}" dropped — ${msg}`);
+            return { Value: undefined, Provenance: 'Absent', Note: `dropped fail-soft: ${msg}` };
+        }
+    }
+    /**
+     * First rule whose every `when` entry matches. Order in the array IS the precedence order.
+     *
+     * A set-valued resolved dimension matches by MEMBERSHIP, so an author writes
+     * `when: { ActiveSkillIDs: '<exam-writer>' }` without needing to know whether the dimension is
+     * scalar or a set. Comparison is case-insensitive: MJ UUID casing is inconsistent, and a rule
+     * that never fires because of letter case would be effectively undebuggable.
+     */
+    firstMatchingRule(rules, resolved) {
+        const same = (a, b) => typeof a === 'string' && typeof b === 'string'
+            ? a.toLowerCase() === b.toLowerCase()
+            : a === b;
+        return rules.find((rule) => Object.entries(rule.when).every(([name, expected]) => {
+            const actual = resolved[name];
+            if (actual === undefined)
+                return false;
+            if (Array.isArray(actual)) {
+                return Array.isArray(expected)
+                    ? expected.every((e) => actual.some((a) => same(a, e)))
+                    : actual.some((a) => same(a, expected));
+            }
+            return same(actual, expected);
+        }));
+    }
+    /** Resolve a single dimension, enforcing trust, grammar, narrowing and required-ness. */
+    async resolveOne(dim, callerScopes, alreadyResolved, input, diagnostics) {
+        const restricts = dim.restricts === true;
+        // `restricts` is a profile: it forces the safe posture rather than relying on an
+        // author remembering to set each field.
+        const trust = restricts ? 'ServerDerived' : (dim.trust ?? 'CallerSupplied');
+        let { Value: value, Provenance: provenance, Note: note } = await this.resolveByTrust(dim, trust, callerScopes, input, diagnostics);
+        ({ Value: value, Provenance: provenance } =
+            this.applyDefaultValue(dim, restricts, value, provenance, diagnostics));
+        if (value === undefined && dim.required) {
+            throw new ScopeDimensionError(`Required dimension "${dim.name}" could not be resolved for scope "${input.Scope.Name}".`);
+        }
+        if (value !== undefined && dim.narrowingOf) {
+            const bound = alreadyResolved[dim.narrowingOf];
+            value = this.meet(dim, value, bound);
+            if (bound !== undefined) {
+                provenance = 'Narrowed';
+                note = `narrowed within "${dim.narrowingOf}"${note ? `; ${note}` : ''}`;
+            }
+        }
+        // An unresolved dimension is 'Absent' — UNLESS a caller value was discarded getting
+        // here. The discard must survive: overwriting it would log a spoof attempt as a routine
+        // "dimension not supplied", which is precisely the record an investigator needs and the
+        // one an attacker would most like erased.
+        if (value === undefined && provenance !== 'DiscardedCaller')
+            provenance = 'Absent';
+        return { Value: value, Provenance: provenance, Note: note };
+    }
+    /**
+     * Produce a value according to the dimension's TRUST, which is the whole security hinge.
+     *
+     * `ServerDerived` never merges a caller value — it discards it and derives its own. The discard
+     * also wins the provenance label even when a server value replaced it, because an audit needs to
+     * see that someone tried; a successful override would otherwise look identical to a quiet run.
+     */
+    async resolveByTrust(dim, trust, callerScopes, input, diagnostics) {
+        if (trust !== 'ServerDerived') {
+            const raw = callerScopes[dim.name];
+            return {
+                Value: raw === undefined ? undefined : this.validateGrammar(dim, raw),
+                Provenance: raw === undefined ? 'Absent' : 'CallerSupplied',
+            };
+        }
+        let note;
+        if (dim.name in callerScopes) {
+            // THE ANTI-SPOOF RULE. Discarded, never merged.
+            const msg = `discarded caller-supplied value for ServerDerived dimension "${dim.name}"`;
+            diagnostics.push(msg);
+            LogStatus(`ScopeDimensionResolver: ${msg}`);
+            note = `a caller-supplied value was discarded (${JSON.stringify(callerScopes[dim.name]).substring(0, 80)})`;
+        }
+        return {
+            Value: await this.deriveServerValue(dim, input),
+            Provenance: note ? 'DiscardedCaller' : 'ServerDerived',
+            Note: note,
+        };
+    }
+    /**
+     * Apply a declared `defaultValue` when nothing resolved.
+     *
+     * A default may NOT stand in for a restricting dimension: for a bound, "absent" has to mean
+     * deny. Allowing a default there would let an author turn a failed derivation into a silent
+     * grant, which is the inverse of what the bound is for.
+     */
+    applyDefaultValue(dim, restricts, value, provenance, diagnostics) {
+        if (value !== undefined || dim.defaultValue === undefined || dim.defaultValue === null) {
+            return { Value: value, Provenance: provenance };
+        }
+        if (restricts) {
+            throw new ScopeDimensionError(`Dimension "${dim.name}" is restricting and could not be derived; a defaultValue must not ` +
+                `substitute for an access bound.`);
+        }
+        diagnostics.push(`applied defaultValue for "${dim.name}"`);
+        // A discard must not be relabelled. `DiscardedCaller` is the security-relevant event, and a
+        // machine reading SearchExecutionLog.ScopeDecisionJSON finds spoof attempts by filtering on
+        // that exact value — so overwriting it with 'Default' hides the attempt from the only query
+        // anyone would run to look for it. (The Note and Diagnostics did survive, but a label a tool
+        // can filter on is the point.) Same failure this resolver already had once, where an
+        // "unresolved => Absent" fallback erased the discard.
+        return {
+            Value: dim.defaultValue,
+            Provenance: provenance === 'DiscardedCaller' ? 'DiscardedCaller' : 'Default',
+        };
+    }
+    /** Derive a ServerDerived value: an approved `MJ: Queries` row, else nothing. */
+    async deriveServerValue(dim, input) {
+        if (!dim.expansionQueryID)
+            return undefined;
+        const result = await new RunQuery().RunQuery({
+            QueryID: dim.expansionQueryID,
+            Parameters: {
+                PrimaryScopeRecordID: input.CallerContext?.PrimaryScopeRecordID ?? null,
+                UserID: input.ContextUser?.ID ?? null,
+                AgentID: input.Principals?.AgentID ?? null,
+                // A skill is a principal in the same sense an agent is (Phase D), so a scope can
+                // derive a different bound depending on which skill is active — the mechanism
+                // behind "invoking this skill changes the content".
+                SkillID: input.Principals?.SkillID ?? null,
+            },
+        }, input.ContextUser);
+        if (!result?.Success) {
+            throw new ScopeDimensionError(`Expansion query for dimension "${dim.name}" failed: ${result?.ErrorMessage ?? 'unknown error'}. ` +
+                `Refusing to search rather than proceeding without the bound.`);
+        }
+        const rows = (result.Results ?? []);
+        // Single-column projection convention: first column of each row.
+        const values = rows
+            .map((r) => { const v = Object.values(r)[0]; return typeof v === 'string' ? v : String(v ?? ''); })
+            .filter((v) => v.length > 0);
+        return dim.valueType === 'uuid' ? values[0] : values;
+    }
+    /**
+     * Meet a caller value against a SET-valued server bound.
+     *
+     * A scalar caller value is a MEMBERSHIP test — "pick one of the allowed values" — not equality
+     * against the set. An earlier version compared the scalar to a stringified array and therefore
+     * rejected every legitimate pick, which is why the two shapes are handled apart here.
+     */
+    meetAgainstSet(dim, callerValue, serverSet, callerIsSet, widened) {
+        const lower = (v) => String(v).toLowerCase();
+        const allowed = new Set(serverSet.map(lower));
+        if (!callerIsSet) {
+            if (!allowed.has(lower(callerValue))) {
+                throw widened(`'${String(callerValue)}' is not one of the ${allowed.size} allowed value(s)`);
+            }
+            return callerValue;
+        }
+        const intersection = callerValue.filter((v) => allowed.has(lower(v)));
+        if (!intersection.length) {
+            // Bottom. Never fall back to the unrestricted bound: an empty value renders as a
+            // REMOVED clause under the `{% if %}` idiom, which inverts narrowing into widening.
+            throw new ScopeDimensionError(`Dimension "${dim.name}" narrowed to NOTHING — the caller's values lie entirely outside the ` +
+                `server-derived bound "${dim.narrowingOf}". Refusing to search (never widen on a degenerate scope).`);
+        }
+        return intersection;
+    }
+    /** Enforce the declared grammar. A failure REJECTS — never coerce, never drop-and-continue. */
+    validateGrammar(dim, raw) {
+        const fail = (why) => {
+            throw new ScopeDimensionError(`Dimension "${dim.name}" failed its declared valueType '${dim.valueType}': ${why}`);
+        };
+        switch (dim.valueType) {
+            case 'uuid':
+                if (typeof raw !== 'string' || !UUID_RE.test(raw))
+                    return fail(`not a uuid (${String(raw).substring(0, 40)})`);
+                return raw;
+            case 'uuid[]': {
+                const arr = Array.isArray(raw) ? raw : fail('not an array');
+                for (const v of arr)
+                    if (!UUID_RE.test(v))
+                        return fail(`array member is not a uuid (${String(v).substring(0, 40)})`);
+                return arr;
+            }
+            case 'enum':
+                if (typeof raw !== 'string')
+                    return fail('not a string');
+                if (!dim.enumValues?.length)
+                    return fail('no enumValues declared');
+                if (!dim.enumValues.includes(raw))
+                    return fail(`'${raw}' is not one of ${dim.enumValues.join('|')}`);
+                return raw;
+            case 'int':
+                if (typeof raw !== 'number' || !Number.isInteger(raw))
+                    return fail('not an integer');
+                return raw;
+            case 'iso-date': {
+                if (typeof raw !== 'string' || Number.isNaN(Date.parse(raw)))
+                    return fail('not an ISO date');
+                return raw;
+            }
+            case 'bool':
+                if (typeof raw !== 'boolean')
+                    return fail('not a boolean');
+                return raw;
+            case 'freetext':
+            case undefined:
+            default:
+                return raw;
+        }
+    }
+    /**
+     * Lattice meet — a caller may only NARROW. `set` intersects; `scalar` must match exactly;
+     * `opaque` forbids narrowing entirely.
+     */
+    meet(dim, callerValue, serverValue) {
+        if (serverValue === undefined)
+            return callerValue;
+        if (dim.valueDomain === 'opaque') {
+            throw new ScopeDimensionError(`Dimension "${dim.name}" has valueDomain 'opaque'; narrowingOf is not permitted.`);
+        }
+        // The lattice is chosen by the SHAPES of both sides, not by one declared domain. The
+        // important case — and the one an earlier version got wrong — is a SCALAR caller value
+        // narrowing a SET-valued server bound: that is a membership test ("pick one of the
+        // allowed values"), not an equality test. Comparing a scalar against a stringified
+        // array rejects every legitimate pick.
+        const serverIsSet = Array.isArray(serverValue);
+        const callerIsSet = Array.isArray(callerValue);
+        const lower = (v) => String(v).toLowerCase();
+        const widened = (detail) => new ScopeDimensionError(`Dimension "${dim.name}" would WIDEN rather than narrow the server-derived bound ` +
+            `"${dim.narrowingOf}": ${detail}. Refusing to search.`);
+        if (serverIsSet) {
+            return this.meetAgainstSet(dim, callerValue, serverValue, callerIsSet, widened);
+        }
+        // Server bound is a single value: the caller may only restate it.
+        if (callerIsSet) {
+            const distinct = new Set(callerValue.map(lower));
+            if (distinct.size !== 1 || !distinct.has(lower(serverValue))) {
+                throw widened(`a set that is not exactly ['${String(serverValue)}']`);
+            }
+            return serverValue;
+        }
+        if (lower(callerValue) !== lower(serverValue)) {
+            throw widened(`'${String(callerValue)}' != '${String(serverValue)}'`);
+        }
+        return serverValue;
+    }
+}
+//# sourceMappingURL=ScopeDimensionResolver.js.map

package/dist/generic/ScopeDimensionResolver.js.map

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

package/dist/generic/ScopeExplanation.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @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
+ */
+import type { DimensionExplanation, SearchContext } from './search.types.js';
+import type { SearchScopePermissionLevel, SearchScopePermissionSource } from '../permissions/SearchScopePermissionResolver.js';
+/** Which kind of retrieval lane a {@link LaneExplanation} describes. */
+export type LaneKind = 'ExternalIndex' | 'Entity' | 'StorageAccount';
+/**
+ * What happened to one retrieval lane.
+ *
+ * `Skipped` is the interesting state and the reason this type exists. A lane is skipped when
+ * its restriction could not be applied safely — an unparseable filter, a template that lost a
+ * clause, a required metadata key the rendered filter never mentions. Skipping is the correct
+ * outcome (the alternative is querying unfiltered), but it is also silent: the search still
+ * succeeds, just against fewer sources. Without this record, "the filter broke and we searched
+ * three lanes instead of four" is indistinguishable from a scope that only ever had three.
+ */
+export interface LaneExplanation {
+    Kind: LaneKind;
+    /** Index name, entity name, or storage account ID — whatever identifies the lane to a human. */
+    Target: string;
+    /** The row ID of the lane's child record, for pinpointing which configuration to fix. */
+    LaneID: string;
+    Status: 'Active' | 'Skipped';
+    /** The filter as rendered for this search, or null when the lane carries no filter. */
+    RenderedFilter: string | null;
+    /** Metadata keys this lane's `RequiredMetadataKeys` contract demands, if any. */
+    RequiredMetadataKeys?: string[];
+    /** Why the lane was skipped. Absent when `Status` is `Active`. */
+    Reason?: string;
+}
+/** The entitlement half of the decision: was this principal allowed to reach the scope at all. */
+export interface EntitlementExplanation {
+    Allowed: boolean;
+    Level: SearchScopePermissionLevel;
+    /** Which resolution path produced the answer (direct grant, role, agent fallback, skill…). */
+    Source: SearchScopePermissionSource;
+    Reason: string;
+    /** The principals in play, so a log row is self-describing without joining three tables. */
+    Principals: {
+        UserID: string | null;
+        AgentID: string | null;
+        SkillID: string | null;
+        /** Tenant the search ran for (`SearchContext.PrimaryScopeRecordID`), null if untenanted. */
+        PrimaryScopeRecordID: string | null;
+    };
+}
+/**
+ * The complete decision for one scope: whether it was reachable, how each dimension of its
+ * bound was decided, and what each lane ended up doing.
+ */
+export interface ScopeExplanation {
+    ScopeID: string;
+    ScopeName: string;
+    /**
+     * The entitlement decision, or `null` when this layer did not evaluate one.
+     *
+     * `null` is a real and common state, not a placeholder: `SearchEngine` does not gate scopes
+     * on `SearchScopePermission` itself — the caller that selects which scopes to search does
+     * (the agent RAG layer, an application action). So an explanation captured *during* a search
+     * legitimately has no entitlement to report, while one produced by `ExplainScope()` always
+     * does, because the dry run resolves it on purpose.
+     *
+     * It is nullable rather than defaulted because the two plausible defaults are both wrong:
+     * a fabricated "allowed" makes an unevaluated search look authorized in an audit log, and a
+     * fabricated "denied" makes a perfectly normal search look blocked. Neither is worth the
+     * convenience of a non-null field.
+     */
+    Entitlement: EntitlementExplanation | null;
+    /** Every declared dimension with its resolved value and provenance. Empty for an undeclared scope. */
+    Dimensions: DimensionExplanation[];
+    Lanes: LaneExplanation[];
+    /** Free-text notes from resolution (discards, applied defaults, expansion-query detail). */
+    Diagnostics: string[];
+    /**
+     * True when this scope would actually contribute results: entitlement did not deny it AND
+     * at least one lane is active. When `Entitlement` is null, this reflects the lanes alone.
+     *
+     * Entitled-but-zero-active-lanes is the case worth surfacing on its own. It looks like a
+     * permissions problem to whoever reports it ("I have access but get nothing"), while the
+     * actual cause is every lane failing its filter guard — a configuration bug that an
+     * entitlement check alone will never reveal.
+     */
+    Reachable: boolean;
+    /**
+     * True when this scope configures **no lanes at all**, which in MJ means UNSCOPED — every
+     * provider reads an empty child configuration as "all entities, all indexes, no filter".
+     *
+     * Surfaced as its own flag because it is the finding a reviewer is most likely to be
+     * hunting for and least likely to spot: such a scope has no filter to inspect, so it looks
+     * innocuous in every other field. It is also the exact opposite of what an empty `Lanes`
+     * array intuitively suggests.
+     */
+    Unbounded: boolean;
+    /** The effective context after resolution — what the lane templates were rendered against. */
+    ResolvedContext?: SearchContext;
+}
+/** Input to {@link ScopeExplanation}-producing dry runs. */
+export interface ExplainScopeInput {
+    /** Scopes to explain. */
+    ScopeIDs: string[];
+    /**
+     * The context a real caller would pass. Explaining with the SAME untrusted input a caller
+     * would send is the point — a preview that only accepts already-sanitized values cannot
+     * show you the discard, which is usually the thing you wanted to see.
+     */
+    SearchContext?: SearchContext;
+    /** Agent principal, if the search would run on an agent's behalf. */
+    AIAgentID?: string | null;
+    /** Skill principal, if a skill would be active. */
+    AISkillID?: string | null;
+}
+/**
+ * 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 declare function SummarizeExplanation(explanation: ScopeExplanation): string[];
+//# sourceMappingURL=ScopeExplanation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeExplanation.d.ts","sourceRoot":"","sources":["../../src/generic/ScopeExplanation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,KAAK,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,8CAA8C,CAAC;AAE5H,wEAAwE;AACxE,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG,QAAQ,GAAG,gBAAgB,CAAC;AAErE;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,gGAAgG;IAChG,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,uFAAuF;IACvF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,kGAAkG;AAClG,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,0BAA0B,CAAC;IAClC,8FAA8F;IAC9F,MAAM,EAAE,2BAA2B,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,UAAU,EAAE;QACR,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,4FAA4F;QAC5F,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;KACvC,CAAC;CACL;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC3C,sGAAsG;IACtG,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;;OAQG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,8FAA8F;IAC9F,eAAe,CAAC,EAAE,aAAa,CAAC;CACnC;AAED,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAC9B,yBAAyB;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,EAAE,CA0C5E"}