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

package/dist/Database/materializationAnalysis.d.ts

@@ -0,0 +1,241 @@
+import { MaterializedColumnSpec } from './codeGenDatabaseProvider.js';
+import type { SQLParserDialect } from '@memberjunction/sql-dialect';
+/**
+ * Result-shape + key analysis for query materialization (CodeGen materialization phase,
+ * sub-step C — plan/query-entity-materialization.md §4.2 / §5 / §9).
+ *
+ * This is the deterministic, engine-agnostic core: given a query's declared output shape
+ * (its `MJ: Query Fields`) and whether it is parameterized, decide whether it qualifies for
+ * materialization in v1 and produce the physical column spec for its materialized table.
+ *
+ * **v1 scope (Phase 1):** only **unparameterized** queries materialize; parameterized ones
+ * are deferred to Phase 2 (row-filter) / later. The single-column key is a **synthetic
+ * surrogate** (full-rebuild compatible) — the deterministic combined-key-set hashing in §5
+ * is Phase 3 and will replace the surrogate when incremental refresh lands.
+ */
+/** A query's declared output column (subset of `MJ: Query Fields` relevant to the shape). */
+export interface QueryFieldShape {
+    /** Output column name. */
+    Name: string;
+    /** Engine-native SQL type for the column (from `QueryField.SQLFullType`). */
+    SQLFullType: string;
+    /** Whether the column is a computed expression (informational; still materializable as a snapshot column). */
+    IsComputed?: boolean;
+}
+/** The outcome of analyzing a query for materialization. */
+export interface MaterializationAnalysis {
+    /** True only if the query can be materialized in v1. */
+    qualifies: boolean;
+    /** When `qualifies` is false, a human-readable reason (logged, never guessed-past). */
+    reason?: string;
+    /** Physical column spec for the materialized table (surrogate PK first, then the query's output columns). */
+    columns: MaterializedColumnSpec[];
+    /** Name of the synthetic surrogate primary-key column. */
+    surrogateColumnName: string;
+}
+/**
+ * Name of the synthetic surrogate key column added to every query-materialized table in v1.
+ * Namespaced to avoid colliding with a query's own output columns.
+ */
+export declare const MATERIALIZATION_SURROGATE_COLUMN = "__mj_MaterializedRowID";
+/** Default surrogate column SQL type (SQL Server). Callers on other engines pass their own. */
+export declare const DEFAULT_SURROGATE_SQL_TYPE = "int IDENTITY(1,1)";
+/**
+ * Analyzes a query for v1 materialization. Pure function — no DB/IO — so it is fully unit-testable.
+ *
+ * Qualifying rule (§9 / §10, asymmetric-risk: default to NOT materializable when unsure):
+ *   - parameterized queries do not qualify in v1 (deferred);
+ *   - a query with no declared output fields does not qualify (run query analysis first);
+ *   - a query whose output already contains a column named like the surrogate does not qualify
+ *     (we won't silently shadow it).
+ *
+ * On success, returns the column spec with a synthetic surrogate PK prepended; the query's
+ * own output columns are emitted as nullable snapshot columns (a snapshot may contain NULLs).
+ */
+export declare function analyzeQueryForMaterialization(opts: {
+    queryName: string;
+    isParameterized: boolean;
+    fields: QueryFieldShape[];
+    /** Engine-specific surrogate column type; defaults to SQL Server's identity. */
+    surrogateSQLType?: string;
+}): MaterializationAnalysis;
+/**
+ * Verified role of a single query parameter, produced by the render-and-diff verifier (Phase 2b)
+ * with an LLM proposer (Phase 2c). The verifier is the oracle; this module only consumes its
+ * verdict — so `RowFilter` here means *proven* row-filter (the render-and-diff confirmed the only
+ * difference across param values is a substituted literal at a WHERE predicate on `filterColumn`).
+ */
+export type ParamRole = 'RowFilter' | 'Structural' | 'Unbounded';
+/** Persisted parameterization mode (mirrors the `MaterializedResult.ParamMode` CHECK values). */
+export type ParamMode = 'None' | 'RowFilterBroad' | 'PerValueCache' | 'BoundFixed';
+/**
+ * Phase 2 read-time-injectable operators — the SAFE whitelist. A `column <op> value` predicate in this
+ * set can be faithfully re-applied against the broad materialized table with a bound parameter (§3 of the
+ * Phase-2 plan). `LIKE`/`IS`/`BETWEEN` and their negations are intentionally EXCLUDED in v1 (subtler
+ * pattern/null/two-operand semantics) — a query using them stays live-only, which is harmless (§10).
+ */
+export declare const SAFE_READ_FILTER_OPERATORS: ReadonlySet<string>;
+/**
+ * One read-time filter predicate persisted as the contract between CodeGen (classify-time) and the runtime
+ * provider (read-time): `column <operator> value(s)` against the broad materialized table. Self-sufficient —
+ * the provider consumes this JSON directly and never re-parses the query. Values are ALWAYS bound as SQL
+ * parameters at read time (never interpolated), so `column`/`operator` are the only trusted-from-here fields.
+ */
+export interface ReadFilterSpecEntry {
+    /** The materialized output column to filter (proven present in the output at qualify time). */
+    column: string;
+    /** The normalized `column <op> value` operator — always one of {@link SAFE_READ_FILTER_OPERATORS}. */
+    operator: string;
+    /** The `MJ: Query Parameter` name whose incoming value binds into this predicate. */
+    paramName: string;
+    /** `scalar` → single bound value; `list` → `IN (@p0,@p1,…)` bound element-wise. */
+    kind: 'scalar' | 'list';
+}
+/** One parameter's verified classification (input to {@link qualifyParameterizedQuery}). */
+export interface ParamClassification {
+    /** Parameter name (the Nunjucks variable). */
+    name: string;
+    /** Verified role. `RowFilter` requires `filterColumn`; `Structural` may carry a bounded domain. */
+    role: ParamRole;
+    /** Bucket 1: the output column the param filters on (must be present in the materialized output). */
+    filterColumn?: string;
+    /** Bucket 1: the normalized `column <op> value` operator (Phase 2 — required to reconstruct the predicate). */
+    filterOperator?: string;
+    /** Bucket 1: scalar vs. list (`IN`/`NOT IN`) value shape. */
+    filterKind?: 'scalar' | 'list';
+    /** Bucket 2: the verifier-bounded value domain (advisory — the runtime guard still recomputes on a miss). */
+    boundedDomain?: string[];
+}
+/** The parameterization-qualification decision for a query. */
+export interface ParamQualification {
+    /** True only if the query's params are all safely materializable. */
+    qualifies: boolean;
+    /** When `qualifies` is false, a human-readable reason (logged, never guessed past). */
+    reason?: string;
+    /** Resolved mode. `None` for an unparameterized query. */
+    paramMode: ParamMode;
+    /** RowFilterBroad: the columns to apply as read-time predicates against the broad materialized table (§6.4). */
+    rowFilterColumns: string[];
+    /**
+     * RowFilterBroad: the structured, self-sufficient predicate spec the runtime provider injects at read time
+     * (Phase 2). Empty for every other mode. Persisted as JSON on `MJ: Materialized Results . ReadFilterSpec`.
+     */
+    readFilterSpec: ReadFilterSpecEntry[];
+}
+/**
+ * Decides the {@link ParamMode} for a (possibly parameterized) query from its per-param
+ * classifications — the §9 qualifying rule under the §10 asymmetric-risk posture
+ * (**default to NOT materializable unless every param is provably safe**). Pure — no DB/IO/LLM.
+ *
+ * Rules:
+ *  - no params → `None` (qualifies; caller materializes the static query).
+ *  - any `Unbounded` param (Bucket 3) → refuse (author can bind it to a fixed value → BoundFixed,
+ *    which arrives here as effectively unparameterized).
+ *  - `RowFilter` (Bucket 1) → the `filterColumn` MUST be present in the materialized output, else
+ *    refuse (filtering on a projected-away column would be unsound).
+ *  - `Structural` (Bucket 2) → only when `allowPerValueCache` is enabled AND the verifier bounded
+ *    the domain; otherwise refuse (recompute live). Open decision §17 — defaults OFF.
+ *  - a mix of row-filter and structural params is not modeled in v1 → refuse.
+ */
+export declare function qualifyParameterizedQuery(opts: {
+    queryName: string;
+    params: ParamClassification[];
+    /** The query's materialized output column names (for the Bucket-1 column-presence check). */
+    outputColumns: string[];
+    /** Whether Bucket-2 per-value cache is supported in this build (default false → structural recomputes). */
+    allowPerValueCache?: boolean;
+    /**
+     * Whether Bucket-1 row-filter broad materialization is enabled in this build (default false).
+     * Phase 2 is not shipped: the read-time row-filter predicate is NOT auto-injected by the provider,
+     * so a caller reading a RowFilterBroad materialization must supply the filter themselves (via
+     * ExtraFilter) or they get the broad/unfiltered set. To avoid that footgun, parameterized row-filter
+     * queries are refused (stay live-only) unless a build explicitly opts in. Flipping this to true is the
+     * Phase-2 enablement switch (finalize the read-time predicate injection first).
+     */
+    allowRowFilterBroad?: boolean;
+    /**
+     * The query's **rendered** SQL (a concrete instance — parameters already substituted). REQUIRED to
+     * qualify a `RowFilter` param: the verifier reports `filterColumn` as a BARE column name, and matching
+     * that name against the output-column list alone cannot tell `o.Status` (the predicate) apart from
+     * `c.Status` (the projected output) in a join, nor `BillRegion` (an alias over `ShipRegion`) apart from
+     * a real `BillRegion` column. Both mis-matches produce a materialized read that filters on a DIFFERENT
+     * column than the live query, with no error and no count-guard signal. See
+     * {@link proveFilterColumnBinding}. When omitted, RowFilter params are REFUSED (fail closed, §10) —
+     * the query stays live-only, which is always correct.
+     */
+    sql?: string;
+    /** Dialect used to parse {@link sql}. Required alongside it; RowFilter params refuse without both. */
+    dialect?: SQLParserDialect;
+}): ParamQualification;
+/** Verdict of {@link proveFilterColumnBinding}: provable, or refused with the precise reason. */
+export interface FilterColumnBindingProof {
+    /** True ONLY when the predicate column is proven to be the same source column the output column carries. */
+    provable: boolean;
+    /** When not provable, the precise reason (logged; never guessed past). */
+    reason?: string;
+}
+/**
+ * Proves that a verified row-filter predicate on `filterColumn` refers to **exactly** the materialized
+ * output column of that same name — the gap a bare-name `outputColumns.includes(filterColumn)` check leaves
+ * open, and which nothing downstream can close.
+ *
+ * Two silently-wrong-data cases motivate it, both of which pass every existing guard (in particular the
+ * broad-render count guard, since exactly ONE predicate is stripped in each):
+ *
+ *  - **Join collision** — `SELECT o.ID, c.Status FROM Orders o JOIN Customers c … WHERE o.Status = {{s}}`.
+ *    The output `Status` is the CUSTOMER's; the predicate is the ORDER's. The materialized read emits
+ *    `WHERE [Status] = @p0` against the customer's value.
+ *  - **Alias rebinding** — `SELECT ID, ShipRegion AS BillRegion FROM Orders WHERE BillRegion = {{r}}` on a
+ *    table that has BOTH columns. The materialized `BillRegion` column holds `ShipRegion` values, so the
+ *    read filters `ShipRegion = 'East'` while live filters `BillRegion = 'East'`.
+ *
+ * Refuses (never guesses) unless ALL of the following hold — falling back to the live query, always correct:
+ *  1. `sql` parses to a single plain SELECT (not multi-statement, not a set operation — a `UNION` root
+ *     exposes only its first branch, so nothing about the whole result can be proven from it);
+ *  2. the SELECT list is readable and not a wildcard (`SELECT *` hides the real output↔source mapping);
+ *  3. exactly ONE output column is named `filterColumn` (two would make the read-time predicate ambiguous);
+ *  4. that output column is a plain column reference, not a computed expression;
+ *  5. it projects the SAME source column name (no alias rebinding);
+ *  6. the WHERE clause references `filterColumn` under a single, consistent qualifier; and
+ *  7. that qualifier provably denotes the same relation as the output column's — trivially true for a
+ *     single-relation FROM, otherwise both must carry the same explicit qualifier ({@link sourceRefsMatch}).
+ *
+ * Pure — no DB/IO.
+ */
+export declare function proveFilterColumnBinding(opts: {
+    /** The query's RENDERED SQL (parameters substituted), still carrying the row-filter predicate. */
+    sql: string;
+    /** Dialect to parse with. */
+    dialect: SQLParserDialect;
+    /** The verifier-reported bare filter column name. */
+    filterColumn: string;
+}): FilterColumnBindingProof;
+/**
+ * Phase 3: detect the combined KEY of an aggregation query (for the surrogate hash). Conservative and
+ * safe-by-default — returns the grouping columns as the key ONLY when it can confidently identify an
+ * aggregation whose key is expressible in the materialized output; ANY ambiguity → null, and the caller
+ * then uses the synthetic surrogate + full rebuild (always correct, just not incrementally optimizable —
+ * the §10 "refuse under uncertainty" bias applied to keying). See the inline comment for the exact rules;
+ * the key is built from the AST GROUP BY terms (not a SELECT-list split), so grouping expressions and
+ * grouped-but-unprojected columns both refuse rather than silently producing a too-narrow key.
+ */
+export declare function detectAggregationKeyColumns(opts: {
+    sql: string;
+    dialect: SQLParserDialect;
+    fields: QueryFieldShape[];
+}): {
+    name: string;
+    type: string;
+}[] | null;
+/**
+ * Phase 4: is an aggregation's measure set PURELY ADDITIVE (only SUM / plain COUNT)? Drives the
+ * refresh-strategy choice: additive keyed aggregations use the MERGE-upsert `Incremental` path
+ * (in-place measure update, no row churn), non-additive ones use `DirtyGroupRecompute` (whole-group
+ * delete+reinsert). Conservative and safe-by-default: returns false on ANY sign of a non-additive
+ * aggregate (`AVG`/`MIN`/`MAX`/`STDEV*`/`VAR*`/`MEDIAN`/`PERCENTILE`/`*_AGG`, or `COUNT(DISTINCT …)`),
+ * and requires at least one additive aggregate to be present — anything ambiguous → false (the caller
+ * then uses DirtyGroupRecompute, which is correct for all measure types). Regex-based because the SQL
+ * parser doesn't expose per-measure expression text; the bias is toward the safe (non-additive) answer.
+ */
+export declare function detectAdditiveMeasures(sql: string): boolean;
+//# sourceMappingURL=materializationAnalysis.d.ts.map

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

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