@memberjunction/codegen-lib 6.1.0-edge.1 → 6.1.0-edge.3

package/dist/Database/materializationDrift.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Phase 4: materialization drift detection (plan §13 + §17.2 "flag-and-hold").
+ *
+ * A materialization snapshots a specific source shape. When CodeGen re-syncs entity metadata to the
+ * live schema, a source entity/field a materialization depends on may have been dropped, renamed, or
+ * reshaped — leaving the materialized table out of sync with what its source now produces. Per §17.2
+ * the policy is FLAG-AND-HOLD: mark the row `DriftHold` and stop refreshing (surface for review),
+ * never silently auto-rebuild.
+ *
+ * This module is the pure decision core: given already-resolved existence facts (gathered against the
+ * freshly-synced metadata by the CodeGen orchestration), decide whether a materialization has drifted
+ * and why. No DB/IO — fully unit-testable.
+ */
+/** Resolved drift-relevant facts for one materialization (gathered against current metadata). */
+export interface MaterializationDriftFacts {
+    sourceType: 'Query' | 'EntityBaseView';
+    /** EntityBaseView case (1:1 copy of a source entity). */
+    baseView?: {
+        /** The source entity (SourceEntityID) still resolves in current metadata. */
+        sourceEntityExists: boolean;
+        /** Current field names on the source entity. */
+        currentEntityFields: string[];
+        /** The materialized table's current columns (what the snapshot was actually built with). */
+        materializedColumns: string[];
+    };
+    /** Query case (provenance via QueryEntity / QueryField / QueryDependency). */
+    query?: {
+        /** Names/IDs of QueryEntity source entities that no longer exist. */
+        missingSourceEntities: string[];
+        /** `Entity.Field` provenance refs (QueryField.SourceEntityID+SourceFieldName) that no longer resolve. */
+        missingSourceFields: string[];
+        /** Composed inner queries (QueryDependency.DependsOnQueryID) that no longer exist. */
+        missingComposedQueries: string[];
+        /** The query's CURRENT declared output column names (MJ: Query Fields). Empty when unknown / not yet
+         *  analyzed — the output-shape check is then skipped (can't judge → don't false-flag). */
+        currentOutputColumns: string[];
+        /** The materialized table's current DATA columns, with the synthetic surrogate PK and any `__mj_*`
+         *  system columns already excluded. Empty when the table can't be introspected — shape check skipped. */
+        materializedColumns: string[];
+    };
+}
+/** The drift verdict for one materialization. */
+export interface MaterializationDriftVerdict {
+    drift: boolean;
+    reason?: string;
+}
+/**
+ * Decides whether a materialization has drifted from its source. Pure.
+ *
+ * Base-view (1:1): drift if the source entity is gone, or its current field set no longer matches the
+ * columns the snapshot was built with (a field added/removed/renamed on the source).
+ * Query: drift if any provenance dependency is broken — a source entity removed, a mapped source field
+ * removed/renamed, or a composed inner query removed. Provenance refs with unknown source (no
+ * SourceEntityID/SourceFieldName) are NOT judged here (the orchestration excludes them) to avoid false
+ * positives from incomplete provenance — the §10 bias runs the other way for drift (only flag on a
+ * definite broken dependency).
+ */
+export declare function evaluateMaterializationDrift(facts: MaterializationDriftFacts): MaterializationDriftVerdict;
+//# sourceMappingURL=materializationDrift.d.ts.map

package/dist/Database/materializationDrift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializationDrift.d.ts","sourceRoot":"","sources":["../../src/Database/materializationDrift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,iGAAiG;AACjG,MAAM,WAAW,yBAAyB;IACtC,UAAU,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,yDAAyD;IACzD,QAAQ,CAAC,EAAE;QACP,6EAA6E;QAC7E,kBAAkB,EAAE,OAAO,CAAC;QAC5B,gDAAgD;QAChD,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAC9B,4FAA4F;QAC5F,mBAAmB,EAAE,MAAM,EAAE,CAAC;KACjC,CAAC;IACF,8EAA8E;IAC9E,KAAK,CAAC,EAAE;QACJ,qEAAqE;QACrE,qBAAqB,EAAE,MAAM,EAAE,CAAC;QAChC,yGAAyG;QACzG,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAC9B,sFAAsF;QACtF,sBAAsB,EAAE,MAAM,EAAE,CAAC;QACjC;kGAC0F;QAC1F,oBAAoB,EAAE,MAAM,EAAE,CAAC;QAC/B;iHACyG;QACzG,mBAAmB,EAAE,MAAM,EAAE,CAAC;KACjC,CAAC;CACL;AAED,iDAAiD;AACjD,MAAM,WAAW,2BAA2B;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,yBAAyB,GAAG,2BAA2B,CA4D1G"}

package/dist/Database/materializationDrift.js

@@ -0,0 +1,85 @@
+/**
+ * Phase 4: materialization drift detection (plan §13 + §17.2 "flag-and-hold").
+ *
+ * A materialization snapshots a specific source shape. When CodeGen re-syncs entity metadata to the
+ * live schema, a source entity/field a materialization depends on may have been dropped, renamed, or
+ * reshaped — leaving the materialized table out of sync with what its source now produces. Per §17.2
+ * the policy is FLAG-AND-HOLD: mark the row `DriftHold` and stop refreshing (surface for review),
+ * never silently auto-rebuild.
+ *
+ * This module is the pure decision core: given already-resolved existence facts (gathered against the
+ * freshly-synced metadata by the CodeGen orchestration), decide whether a materialization has drifted
+ * and why. No DB/IO — fully unit-testable.
+ */
+const lc = (s) => s.trim().toLowerCase();
+/**
+ * Decides whether a materialization has drifted from its source. Pure.
+ *
+ * Base-view (1:1): drift if the source entity is gone, or its current field set no longer matches the
+ * columns the snapshot was built with (a field added/removed/renamed on the source).
+ * Query: drift if any provenance dependency is broken — a source entity removed, a mapped source field
+ * removed/renamed, or a composed inner query removed. Provenance refs with unknown source (no
+ * SourceEntityID/SourceFieldName) are NOT judged here (the orchestration excludes them) to avoid false
+ * positives from incomplete provenance — the §10 bias runs the other way for drift (only flag on a
+ * definite broken dependency).
+ */
+export function evaluateMaterializationDrift(facts) {
+    if (facts.sourceType === 'EntityBaseView' && facts.baseView) {
+        const bv = facts.baseView;
+        if (!bv.sourceEntityExists) {
+            return { drift: true, reason: 'source entity no longer exists' };
+        }
+        // Skip the shape comparison when EITHER set is empty (mirrors the Query branch): an empty
+        // materializedColumns — the table couldn't be introspected under the CodeGen connection (transient
+        // failure, permission/visibility edge) — would otherwise make every source field look 'added' and
+        // false-flag DriftHold on a materialization that has not actually drifted (§10: only flag on a
+        // definite mismatch). currentEntityFields is never empty for a resolved entity, but guard it for symmetry.
+        if (bv.materializedColumns.length === 0 || bv.currentEntityFields.length === 0) {
+            return { drift: false };
+        }
+        const cur = new Set(bv.currentEntityFields.map(lc));
+        const mat = new Set(bv.materializedColumns.map(lc));
+        const added = [...cur].filter((c) => !mat.has(c));
+        const removed = [...mat].filter((c) => !cur.has(c));
+        if (added.length || removed.length) {
+            return {
+                drift: true,
+                reason: `base-view shape changed vs the snapshot (source added: [${added.join(', ')}]; snapshot has orphaned: [${removed.join(', ')}])`,
+            };
+        }
+        return { drift: false };
+    }
+    if (facts.sourceType === 'Query' && facts.query) {
+        const q = facts.query;
+        if (q.missingSourceEntities.length) {
+            return { drift: true, reason: `source entit${q.missingSourceEntities.length === 1 ? 'y' : 'ies'} removed: [${q.missingSourceEntities.join(', ')}]` };
+        }
+        if (q.missingSourceFields.length) {
+            return { drift: true, reason: `source field${q.missingSourceFields.length === 1 ? '' : 's'} removed/renamed: [${q.missingSourceFields.join(', ')}]` };
+        }
+        if (q.missingComposedQueries.length) {
+            return { drift: true, reason: `composed inner quer${q.missingComposedQueries.length === 1 ? 'y' : 'ies'} removed: [${q.missingComposedQueries.join(', ')}]` };
+        }
+        // Output-shape drift: the physical table is create-if-absent (no ALTER path), so an edit to the query's
+        // SELECT list (add/rename/remove an output column) while all source entities/fields still exist would
+        // otherwise go undetected and serve the OLD column set forever. Compare the query's current output
+        // columns against the snapshot's data columns — but ONLY when both are known (skip if either is empty:
+        // a query whose fields aren't analyzed yet, or a table we couldn't introspect, must not be false-flagged
+        // — the §10 "only flag on a definite mismatch" bias).
+        if (q.currentOutputColumns.length && q.materializedColumns.length) {
+            const cur = new Set(q.currentOutputColumns.map(lc));
+            const mat = new Set(q.materializedColumns.map(lc));
+            const added = [...cur].filter((c) => !mat.has(c));
+            const removed = [...mat].filter((c) => !cur.has(c));
+            if (added.length || removed.length) {
+                return {
+                    drift: true,
+                    reason: `query output shape changed vs the snapshot (query added: [${added.join(', ')}]; snapshot has orphaned: [${removed.join(', ')}]) — the create-if-absent table was not rebuilt`,
+                };
+            }
+        }
+        return { drift: false };
+    }
+    return { drift: false };
+}
+//# sourceMappingURL=materializationDrift.js.map

package/dist/Database/materializationDrift.js.map

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

package/dist/Database/materializationParamClassifier.d.ts

@@ -0,0 +1,92 @@
+import type { SQLParserDialect } from '@memberjunction/sql-dialect';
+import { type VerifiedParamRole } from './materializationParamVerifier.js';
+import { type ParamQualification } from './materializationAnalysis.js';
+/**
+ * Phase 2c — deterministic parameter classification for query materialization
+ * (plan /plans/query-entity-materialization.md §9 / §10).
+ *
+ * Orchestrates the render-and-diff oracle ({@link verifyParamRole}) across every parameter of a
+ * query and folds the per-parameter verdicts into the overall {@link qualifyParameterizedQuery}
+ * decision. For each parameter it renders the query template ≥2 times — that parameter varied
+ * across distinct probe values while **all others are held fixed** — and asks the verifier whether
+ * the variation is a clean row filter, a structural change, or unverifiable.
+ *
+ * **Deterministic-only (v1):** probe values are generated from each parameter's declared type; no
+ * LLM is involved (the LLM proposer is deferred to the Bucket-2 / bounded-domain phase). The
+ * verifier is the oracle — this module never trusts author intent.
+ *
+ * The renderer is **injected** ({@link VariantRenderer}) so this module stays free of the Nunjucks
+ * engine and the per-request platform singleton: the soundness-critical orchestration is pure and
+ * fully unit-testable, and the manage-metadata caller supplies the production renderer.
+ */
+/** A query parameter's declared type (mirrors `MJ: Query Parameter`.Type). */
+export type QueryParamType = 'string' | 'number' | 'date' | 'boolean' | 'array';
+/** Subset of a `MJ: Query Parameter` row needed to probe and classify the parameter. */
+export interface QueryParamDef {
+    /** Parameter name (the Nunjucks variable). */
+    Name: string;
+    /** Declared type — drives probe-value generation and the held value. */
+    Type: QueryParamType;
+    /** Author-provided example value (used as the held value for *other* params when valid). */
+    SampleValue?: string | null;
+}
+/**
+ * Renders the query template to final SQL for a complete parameter-value map. Deterministic and
+ * side-effect free from this module's perspective. Supplied by the caller (production: the
+ * Nunjucks render pipeline with SQL-safe filters). May throw if a value breaks the template.
+ */
+export type VariantRenderer = (paramValues: Record<string, unknown>) => string;
+/** A single parameter's classification outcome (for logging / diagnostics). */
+export interface ParamVerdict {
+    name: string;
+    verdict: VerifiedParamRole;
+}
+/** Result of classifying all of a query's parameters. */
+export interface QueryParamClassification {
+    /** The overall qualification (drives whether/how the query materializes). */
+    qualification: ParamQualification;
+    /** Per-parameter verdicts, in declaration order (for precise logs). */
+    perParam: ParamVerdict[];
+}
+/**
+ * Generates ≥2 distinct probe values for a parameter type. Booleans have `[true, false]`. String/number/date
+ * get truthy variants PLUS a falsy one (`''`, `0`, `''`) so a CONDITIONAL predicate (`{% if param %}WHERE …
+ * {% endif %}`) reveals itself: the falsy value renders the FALSE branch (no WHERE), which the AST oracle diffs
+ * as a structural change vs. the truthy renders → the parameter is refused as `Structural` instead of being
+ * mis-classified as an unconditional row filter (which would materialize broad and then WRONGLY apply the
+ * predicate at read time when the param is empty/omitted, diverging from the live query). For these types an
+ * unconditional row filter (`WHERE col = {{param}}`) renders the falsy value as a plain LITERAL (`= ''`/`= 0`),
+ * same SQL shape → stays `RowFilter`, so it isn't over-refused.
+ *
+ * Arrays deliberately get NO empty probe: an empty array renders `IN ()`, which changes the SQL SHAPE even for
+ * an UNCONDITIONAL `WHERE x IN {{arr}}` row filter — the oracle can't distinguish that from a conditional, so
+ * an empty probe would over-refuse the legitimate (and supported) varying-length IN-list row filter. The rare
+ * conditional-array param (`{% if arr %}… IN {{arr}} …{% endif %}`) is therefore a documented residual, not
+ * covered by this structural probe. A falsy value that breaks the template render fails safe (→ Unbounded →
+ * refused). Truthy values are kept FIRST so the held baseline is unaffected (holdValue is independent).
+ */
+export declare function probeValues(type: QueryParamType): unknown[];
+/** Builds the base value map with every parameter held at its stable value. */
+export declare function buildHeldValues(params: QueryParamDef[]): Record<string, unknown>;
+/**
+ * Classifies every parameter of a query and folds the verdicts into the overall qualification.
+ *
+ * Pure orchestration: pass the rendered-SQL producer via `render`. Returns both the qualification
+ * (feeds the materialization gate) and the per-parameter verdicts (for precise logging).
+ *
+ * Note: bounded-domain (`Structural` Bucket-2) classification is **not** populated in v1 — verdicts
+ * carry no `boundedDomain`, so a structural parameter qualifies only if `allowPerValueCache` is on
+ * (off by default) *and* a domain is supplied, which it never is here → structural ⇒ refuse. This is
+ * intentional: per-value caching is a later phase.
+ */
+export declare function classifyQueryParameters(opts: {
+    queryName: string;
+    params: QueryParamDef[];
+    outputColumns: string[];
+    dialect: SQLParserDialect;
+    render: VariantRenderer;
+    allowPerValueCache?: boolean;
+    /** Phase-2 enablement for Bucket-1 row-filter broad materialization (default false → refuse, stay live-only). */
+    allowRowFilterBroad?: boolean;
+}): QueryParamClassification;
+//# sourceMappingURL=materializationParamClassifier.d.ts.map

package/dist/Database/materializationParamClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializationParamClassifier.d.ts","sourceRoot":"","sources":["../../src/Database/materializationParamClassifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACzF,OAAO,EAAuD,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEzH;;;;;;;;;;;;;;;;;GAiBG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEhF,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC1B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,IAAI,EAAE,cAAc,CAAC;IACrB,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;AAE/E,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,CAAC;CAC9B;AAED,yDAAyD;AACzD,MAAM,WAAW,wBAAwB;IACrC,6EAA6E;IAC7E,aAAa,EAAE,kBAAkB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,EAAE,CAa3D;AA8CD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMhF;AAoGD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iHAAiH;IACjH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC,GAAG,wBAAwB,CAyC3B"}

package/dist/Database/materializationParamClassifier.js

@@ -0,0 +1,224 @@
+import { verifyParamRole } from './materializationParamVerifier.js';
+import { qualifyParameterizedQuery } from './materializationAnalysis.js';
+/**
+ * Generates ≥2 distinct probe values for a parameter type. Booleans have `[true, false]`. String/number/date
+ * get truthy variants PLUS a falsy one (`''`, `0`, `''`) so a CONDITIONAL predicate (`{% if param %}WHERE …
+ * {% endif %}`) reveals itself: the falsy value renders the FALSE branch (no WHERE), which the AST oracle diffs
+ * as a structural change vs. the truthy renders → the parameter is refused as `Structural` instead of being
+ * mis-classified as an unconditional row filter (which would materialize broad and then WRONGLY apply the
+ * predicate at read time when the param is empty/omitted, diverging from the live query). For these types an
+ * unconditional row filter (`WHERE col = {{param}}`) renders the falsy value as a plain LITERAL (`= ''`/`= 0`),
+ * same SQL shape → stays `RowFilter`, so it isn't over-refused.
+ *
+ * Arrays deliberately get NO empty probe: an empty array renders `IN ()`, which changes the SQL SHAPE even for
+ * an UNCONDITIONAL `WHERE x IN {{arr}}` row filter — the oracle can't distinguish that from a conditional, so
+ * an empty probe would over-refuse the legitimate (and supported) varying-length IN-list row filter. The rare
+ * conditional-array param (`{% if arr %}… IN {{arr}} …{% endif %}`) is therefore a documented residual, not
+ * covered by this structural probe. A falsy value that breaks the template render fails safe (→ Unbounded →
+ * refused). Truthy values are kept FIRST so the held baseline is unaffected (holdValue is independent).
+ */
+export function probeValues(type) {
+    switch (type) {
+        case 'string':
+            return ['__mj_probe_alpha', '__mj_probe_beta', '__mj_probe_gamma', ''];
+        case 'number':
+            return [101, 202, 303, 0];
+        case 'date':
+            return ['2020-01-15', '2021-06-15', '2022-12-31', ''];
+        case 'boolean':
+            return [true, false];
+        case 'array':
+            return [['__mj_a', '__mj_b'], ['__mj_c'], ['__mj_d', '__mj_e', '__mj_f']];
+    }
+}
+/** Parses a parameter's SampleValue into the runtime shape its type expects (best-effort). */
+function parseSampleValue(type, sample) {
+    switch (type) {
+        case 'number': {
+            const n = Number(sample);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        case 'boolean':
+            return sample.trim().toLowerCase() === 'true';
+        case 'array':
+            return sample.includes(',') ? sample.split(',').map((s) => s.trim()) : [sample];
+        case 'string':
+        case 'date':
+            return sample;
+    }
+}
+/** A stable value to hold a parameter at while a *different* parameter is varied. */
+function holdValue(param) {
+    if (param.SampleValue != null && param.SampleValue.trim().length > 0) {
+        const parsed = parseSampleValue(param.Type, param.SampleValue);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    return defaultHoldValue(param.Type);
+}
+/** Type-based fallback held value when a parameter has no usable SampleValue. */
+function defaultHoldValue(type) {
+    switch (type) {
+        case 'string':
+            return '__mj_hold';
+        case 'number':
+            return 1;
+        case 'date':
+            return '2020-01-01';
+        case 'boolean':
+            return true;
+        case 'array':
+            return ['__mj_hold'];
+    }
+}
+/** Builds the base value map with every parameter held at its stable value. */
+export function buildHeldValues(params) {
+    const held = {};
+    for (const p of params) {
+        held[p.Name] = holdValue(p);
+    }
+    return held;
+}
+/**
+ * Renders the variant SQL strings for one parameter varied across its probe values, all other
+ * parameters held fixed. Returns null if any render throws (the parameter is then unverifiable).
+ */
+function renderVariantsForParam(param, held, render) {
+    const variants = [];
+    for (const v of probeValues(param.Type)) {
+        try {
+            variants.push(render({ ...held, [param.Name]: v }));
+        }
+        catch {
+            return null; // a probe value broke the template → cannot verify this parameter
+        }
+    }
+    return variants;
+}
+/**
+ * A distinctive sentinel value per parameter type for the value-passthrough guard, chosen so its verbatim
+ * appearance in a rendered query is proof the value survived template rendering unchanged (extremely
+ * unlikely to occur coincidentally). Booleans/dates use a plain value that a SQL-formatting filter will
+ * typically coerce (`true`→`1`, a reformatted date) — which the guard then treats as non-passthrough.
+ */
+function passthroughSentinel(type) {
+    // Each sentinel deliberately combines features the common value-transforming filters would alter, so the
+    // verbatim-contains check catches them:
+    //  - STRING/ARRAY: leading/trailing + interior WHITESPACE (trim/ltrim/rtrim/collapse), MIXED CASE (upper/
+    //    lower/capitalize/title), and DIGITS + SEPARATORS — a dash and a dot — so a normalizing `replace('-','')`
+    //    / `replace('.','')` / digit-strip alters it. No single-quote (which sqlString escapes → would
+    //    false-refuse an identity render).
+    //  - NUMBER: a NEGATIVE, NON-INTEGER value. An integer-preserving numeric filter (round/int/floor/ceil)
+    //    drops the fractional part and abs drops the sign, so any of them changes it → refuse — while sqlNumber
+    //    renders it verbatim, so a genuine identity render still passes. (A plain integer sentinel would be
+    //    identity under round/int and slip through.)
+    //  - DATE: a time + non-UTC offset that rolls to the NEXT calendar day in UTC, so sqlDate's
+    //    `new Date(x).toISOString()` normalization changes the date portion → refuse. In practice every SQL-safe
+    //    date filter reformats, so date row-filters are conservatively refused (a never-wrong missed optimization).
+    // The guard is conservative best-effort, NOT a proof: a pathological custom filter that is identity on this
+    // exact sentinel could still slip through (plan §9) — most realistically a `replace()` of a character the
+    // sentinel happens not to contain.
+    switch (type) {
+        case 'string': return '  Mj0_Pt9-zQx.Kw  ';
+        case 'number': return -305419896.5073; // negative + fractional → catches round/int/floor/ceil/abs; sqlNumber renders verbatim
+        case 'date': return '2019-03-14T20:00:00-05:00'; // → 2019-03-15T01:00:00.000Z in UTC: sqlDate changes the date portion
+        case 'boolean': return true;
+        case 'array': return ['  Mj0_PtA9-zx.  ', '  Mj0_PtB9-zx.  '];
+    }
+}
+/**
+ * Phase-2 value-passthrough guard (plan §9). A proven `RowFilter` is only safe to inject at read time if
+ * the template renders the parameter's value UNCHANGED into the predicate literal — because the read path
+ * binds the caller's **raw** value. If the template transforms it (`{{ x | upper | sqlString }}`, a custom
+ * filter) the materialized read would filter on a different value than the live query → silently wrong rows.
+ *
+ * We render the query with a distinctive sentinel and require it to appear VERBATIM in the rendered SQL.
+ * If it doesn't (a value transform, or a type coercion we can't verify), the parameter is refused. This is
+ * **conservative by design** (§10 refuse-under-uncertainty): a coerced-but-faithful value (e.g. a boolean
+ * rendered as `1`) refuses too, leaving the query live-only — a missed optimization, never wrong.
+ */
+function isValuePassthrough(param, held, render) {
+    const sentinel = passthroughSentinel(param.Type);
+    let rendered;
+    try {
+        rendered = render({ ...held, [param.Name]: sentinel });
+    }
+    catch {
+        return false; // cannot render the sentinel → cannot prove passthrough → refuse
+    }
+    const parts = Array.isArray(sentinel) ? sentinel : [sentinel];
+    return parts.every((part) => rendered.includes(String(part)));
+}
+/**
+ * Verifies a single parameter's role by rendering its variants and running the AST oracle. `held` is the
+ * shared base value map (all params at their stable values) — computed ONCE by the caller and reused, since
+ * the baseline is identical for every parameter being probed (renderVariantsForParam overrides just the one
+ * varied param). Rebuilding it per-call would make classification O(N^2) in parameter count.
+ */
+function verifyOneParam(param, held, dialect, render) {
+    const variants = renderVariantsForParam(param, held, render);
+    if (variants == null) {
+        return { role: 'Unbounded', reason: `parameter "${param.Name}" produced a template error while probing — cannot verify; refusing under uncertainty` };
+    }
+    const verdict = verifyParamRole(variants, dialect);
+    // Value-passthrough guard: a proven row filter is only injectable if the raw value survives rendering
+    // into the predicate literal. A transforming template would make the materialized read diverge from live.
+    if (verdict.role === 'RowFilter' && !isValuePassthrough(param, held, render)) {
+        return {
+            role: 'Unbounded',
+            reason: `parameter "${param.Name}" filters on "${verdict.filterColumn ?? '?'}" but the template transforms its value before the predicate literal (the raw value does not survive rendering) — a materialized read would filter on a different value than the live query; refusing (query stays live-only)`,
+        };
+    }
+    return verdict;
+}
+/**
+ * Classifies every parameter of a query and folds the verdicts into the overall qualification.
+ *
+ * Pure orchestration: pass the rendered-SQL producer via `render`. Returns both the qualification
+ * (feeds the materialization gate) and the per-parameter verdicts (for precise logging).
+ *
+ * Note: bounded-domain (`Structural` Bucket-2) classification is **not** populated in v1 — verdicts
+ * carry no `boundedDomain`, so a structural parameter qualifies only if `allowPerValueCache` is on
+ * (off by default) *and* a domain is supplied, which it never is here → structural ⇒ refuse. This is
+ * intentional: per-value caching is a later phase.
+ */
+export function classifyQueryParameters(opts) {
+    const { queryName, params, outputColumns, dialect, render } = opts;
+    // Compute the held baseline ONCE (not per-parameter) — see verifyOneParam.
+    const held = buildHeldValues(params);
+    const perParam = params.map((p) => ({
+        name: p.Name,
+        verdict: verifyOneParam(p, held, dialect, render),
+    }));
+    const classifications = perParam.map((pv) => ({
+        name: pv.name,
+        role: pv.verdict.role,
+        filterColumn: pv.verdict.filterColumn,
+        filterOperator: pv.verdict.filterOperator,
+        filterKind: pv.verdict.filterKind,
+    }));
+    // The qualifier needs the CONCRETE SQL to prove each RowFilter predicate binds to the materialized
+    // output column of the same name (a bare column-name match cannot see a join collision or an alias
+    // rebinding — see proveFilterColumnBinding). The held baseline render is the right instance: it is the
+    // same shape the broad-render step strips, and it still carries the row-filter predicate. If the render
+    // throws, we pass nothing and RowFilter params refuse (fail closed → the query stays live-only).
+    let heldSQL;
+    try {
+        heldSQL = render(held);
+    }
+    catch {
+        heldSQL = undefined;
+    }
+    const qualification = qualifyParameterizedQuery({
+        queryName,
+        params: classifications,
+        outputColumns,
+        allowPerValueCache: opts.allowPerValueCache ?? false,
+        allowRowFilterBroad: opts.allowRowFilterBroad ?? false,
+        sql: heldSQL,
+        dialect,
+    });
+    return { qualification, perParam };
+}
+//# sourceMappingURL=materializationParamClassifier.js.map

package/dist/Database/materializationParamClassifier.js.map

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

package/dist/Database/materializationParamVerifier.d.ts

@@ -0,0 +1,71 @@
+import type { SQLParserDialect } from '@memberjunction/sql-dialect';
+import type { ParamRole } from './materializationAnalysis.js';
+/**
+ * Phase 2b — the render-and-diff verifier (the AST oracle for query parameterization).
+ *
+ * This is the **soundness-critical** core of parameterized materialization (plan
+ * /plans/query-entity-materialization.md §9 Bucket 1, §10 asymmetric-risk). Given a stored
+ * query's templated SQL rendered with the **same** parameter set except for **one** parameter
+ * varied across ≥2 distinct values, it decides that parameter's {@link ParamRole}:
+ *
+ *   - `RowFilter`  — varying the value changes only a literal at a *clean* top-level `WHERE`
+ *                    predicate on a single column (so the query can be materialized broad and
+ *                    that column filtered at read time — Phase 2d).
+ *   - `Structural` — varying the value changes the SQL *shape* (different branch / columns /
+ *                    joins). Not a row filter; may be per-value-cacheable later (Bucket 2).
+ *   - `Unbounded`  — anything we cannot prove safe: a parse failure, no observable effect, a
+ *                    literal that varies outside a clean top-level conjunctive `WHERE` equality
+ *                    (projection, `OR`/`NOT`, subquery, function, `JOIN ... ON`), or a value that
+ *                    touches more than one column. **Default to this when unsure.**
+ *
+ * The verifier observes *actual rendered behavior* — it never trusts the template author's intent.
+ * Its output ({@link VerifiedParamRole}) feeds `qualifyParameterizedQuery` in materializationAnalysis.
+ *
+ * **Why "clean top-level conjunctive WHERE" is mandatory:** read-time row filtering re-applies the
+ * predicate against the *broad* materialization. That is only equivalent to the live parameterized
+ * query when the predicate is ANDed into the outer WHERE on a materialized column. Under an `OR`
+ * (`WHERE Status = {{s}} OR IsAdmin = 1`), re-filtering by `Status` would wrongly drop the `IsAdmin`
+ * rows; inside a subquery / function / JOIN it may not correspond to an output column at all. Those
+ * all *taint* the site → refuse.
+ *
+ * Pure — no DB / IO / LLM. The render step (turning a template + values into these SQL strings)
+ * lives in the Phase 2c adapter; this module only consumes already-rendered SQL, so it is fully
+ * unit-testable with hand-written SQL pairs.
+ */
+/** Comparison operator of a proven row filter, normalized so it always reads `column <op> value`. */
+export type FilterOperator = '=' | '!=' | '<>' | '<' | '>' | '<=' | '>=' | 'IN' | 'NOT IN' | 'LIKE' | 'NOT LIKE' | 'IS' | 'IS NOT' | 'BETWEEN' | 'NOT BETWEEN';
+/** Shape of a proven row-filter value: a single scalar vs. an all-literal list bag (`IN`/`NOT IN`). */
+export type FilterKind = 'scalar' | 'list';
+/** The verifier's verdict for a single parameter. */
+export interface VerifiedParamRole {
+    /** Proven role under the §10 asymmetric-risk posture. */
+    role: ParamRole;
+    /** For `RowFilter`: the single column the value filters on (as written in the predicate). */
+    filterColumn?: string;
+    /**
+     * For `RowFilter`: the comparison operator, **normalized to the `column <op> value` reading** — if the
+     * predicate was written `value < column`, the operator is flipped (`>`) so read-time injection can emit
+     * `column > value` faithfully. This is the Phase-2 metadata that `filterColumn` alone cannot supply
+     * (`Score >= x` vs `Score = x` are otherwise indistinguishable). Absent for non-RowFilter verdicts.
+     */
+    filterOperator?: FilterOperator;
+    /** For `RowFilter`: whether the value is a single scalar or an `IN`/`NOT IN` list bag. */
+    filterKind?: FilterKind;
+    /** Human-readable justification (logged; never guessed past). */
+    reason: string;
+}
+/**
+ * Verifies a single parameter's {@link ParamRole} from ≥2 full-query SQL variants — the same query
+ * template rendered with the same values for every parameter *except* this one, which is varied
+ * across distinct values. Pure; the Phase 2c adapter supplies the rendered strings.
+ *
+ * Decision (refuse-under-uncertainty, §10):
+ *  - <2 variants, or any variant fails to parse → `Unbounded`.
+ *  - any pair differs structurally → `Structural` (shape depends on the value; possibly Bucket 2).
+ *  - all pairs structurally equal but no literal varied → `Unbounded` (no observable effect to prove).
+ *  - a varying literal is tainted (projection / `OR` / subquery / function / non-top-WHERE) → `Unbounded`.
+ *  - varying literals touch >1 column → `Unbounded` (multi-column not modeled in v1).
+ *  - else → `RowFilter` on the single bound column.
+ */
+export declare function verifyParamRole(variants: string[], dialect: SQLParserDialect): VerifiedParamRole;
+//# sourceMappingURL=materializationParamVerifier.d.ts.map

package/dist/Database/materializationParamVerifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializationParamVerifier.d.ts","sourceRoot":"","sources":["../../src/Database/materializationParamVerifier.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAM3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,qGAAqG;AACrG,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAE/J,uGAAuG;AACvG,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3C,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAC9B,yDAAyD;IACzD,IAAI,EAAE,SAAS,CAAC;IAChB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,0FAA0F;IAC1F,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAClB;AAySD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,gBAAgB,GAAG,iBAAiB,CAmDhG"}