@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/semantic/agent-schema.d.ts

@@ -0,0 +1,322 @@
+import { z } from "zod";
+/** Un filtre semantique, dans la forme persistee par le registre. */
+export declare const semanticFilterSchema: z.ZodObject<{
+    field: z.ZodString;
+    operator: z.ZodEnum<{
+        equals: "equals";
+        not_equals: "not_equals";
+        contains: "contains";
+        starts_with: "starts_with";
+        ends_with: "ends_with";
+        greater_than: "greater_than";
+        greater_than_or_equal: "greater_than_or_equal";
+        less_than: "less_than";
+        less_than_or_equal: "less_than_or_equal";
+        in: "in";
+        not_in: "not_in";
+        is_null: "is_null";
+        is_not_null: "is_not_null";
+        between: "between";
+        on: "on";
+        not_contains: "not_contains";
+        is_empty: "is_empty";
+        is_not_empty: "is_not_empty";
+        before: "before";
+        after: "after";
+    }>;
+    value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+    fieldType: z.ZodOptional<z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+    }>>;
+    period: z.ZodOptional<z.ZodObject<{
+        unit: z.ZodEnum<{
+            day: "day";
+            week: "week";
+            month: "month";
+            quarter: "quarter";
+            year: "year";
+        }>;
+        value: z.ZodNumber;
+        offsetUnit: z.ZodOptional<z.ZodEnum<{
+            day: "day";
+            week: "week";
+            month: "month";
+            quarter: "quarter";
+            year: "year";
+        }>>;
+        offsetValue: z.ZodOptional<z.ZodNumber>;
+        includeCurrent: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    parameter: z.ZodOptional<z.ZodString>;
+    parameterTo: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Un parametre declare par une requete semantique. */
+export declare const semanticParameterSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+        category: "category";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Les valeurs fournies pour les parametres declares. */
+export declare const semanticParameterValuesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+/** Expression d'une dimension ou d'une metrique, en JSON. */
+export declare const semanticExpressionSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        column: "column";
+        binary: "binary";
+        literal: "literal";
+        call: "call";
+        agg: "agg";
+        case: "case";
+        ifnull: "ifnull";
+    }>;
+}, z.core.$loose>;
+/**
+ * Entree de l'Agent API pour enregistrer un modele semantique.
+ *
+ * Le `baseSql` est facultatif : un modele peut viser une table nommee. Il
+ * reste soumis au garde-fou de lecture seule au moment de l'enregistrement
+ * (cote app), pas ici : ce schema decrit la forme, pas la politique.
+ */
+export declare const semanticModelInputSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    source: z.ZodObject<{
+        kind: z.ZodEnum<{
+            postgres: "postgres";
+            clickhouse: "clickhouse";
+            d1: "d1";
+            inline: "inline";
+        }>;
+        label: z.ZodString;
+        table: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    baseSql: z.ZodOptional<z.ZodString>;
+    dimensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        expression: z.ZodObject<{
+            kind: z.ZodEnum<{
+                column: "column";
+                binary: "binary";
+                literal: "literal";
+                call: "call";
+                agg: "agg";
+                case: "case";
+                ifnull: "ifnull";
+            }>;
+        }, z.core.$loose>;
+        type: z.ZodDefault<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    metrics: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        expression: z.ZodObject<{
+            kind: z.ZodEnum<{
+                column: "column";
+                binary: "binary";
+                literal: "literal";
+                call: "call";
+                agg: "agg";
+                case: "case";
+                ifnull: "ifnull";
+            }>;
+        }, z.core.$loose>;
+        type: z.ZodOptional<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+        }>>;
+        unit: z.ZodOptional<z.ZodEnum<{
+            count: "count";
+            ratio: "ratio";
+            currency: "currency";
+            duration: "duration";
+            percent: "percent";
+            position: "position";
+            score: "score";
+        }>>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            neutral: "neutral";
+            up: "up";
+            down: "down";
+        }>>;
+        format: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Croisement demande pour une requete : lignes, colonnes et mesures. */
+export declare const semanticPivotSchema: z.ZodObject<{
+    rowFields: z.ZodArray<z.ZodString>;
+    columnFields: z.ZodArray<z.ZodString>;
+    valueFields: z.ZodArray<z.ZodString>;
+    showRowTotals: z.ZodOptional<z.ZodBoolean>;
+    showColumnTotals: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Entree de l'Agent API pour executer une requete semantique.
+ *
+ * `limit` est plafonne a 1000 lignes : c'est la meme borne que celle du
+ * `sql-guard` de Pulse, pour que l'Agent API ne puisse pas devenir un canal
+ * d'extraction massive.
+ */
+export declare const semanticQueryInputSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    model: z.ZodString;
+    dimensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metrics: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    filters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodEnum<{
+            equals: "equals";
+            not_equals: "not_equals";
+            contains: "contains";
+            starts_with: "starts_with";
+            ends_with: "ends_with";
+            greater_than: "greater_than";
+            greater_than_or_equal: "greater_than_or_equal";
+            less_than: "less_than";
+            less_than_or_equal: "less_than_or_equal";
+            in: "in";
+            not_in: "not_in";
+            is_null: "is_null";
+            is_not_null: "is_not_null";
+            between: "between";
+            on: "on";
+            not_contains: "not_contains";
+            is_empty: "is_empty";
+            is_not_empty: "is_not_empty";
+            before: "before";
+            after: "after";
+        }>;
+        value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+        fieldType: z.ZodOptional<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+        }>>;
+        period: z.ZodOptional<z.ZodObject<{
+            unit: z.ZodEnum<{
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>;
+            value: z.ZodNumber;
+            offsetUnit: z.ZodOptional<z.ZodEnum<{
+                day: "day";
+                week: "week";
+                month: "month";
+                quarter: "quarter";
+                year: "year";
+            }>>;
+            offsetValue: z.ZodOptional<z.ZodNumber>;
+            includeCurrent: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        parameter: z.ZodOptional<z.ZodString>;
+        parameterTo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    sort: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        by: z.ZodString;
+        dir: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+            category: "category";
+        }>;
+        label: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    parameterValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>>;
+    pivot: z.ZodOptional<z.ZodObject<{
+        rowFields: z.ZodArray<z.ZodString>;
+        columnFields: z.ZodArray<z.ZodString>;
+        valueFields: z.ZodArray<z.ZodString>;
+        showRowTotals: z.ZodOptional<z.ZodBoolean>;
+        showColumnTotals: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Sortie : la description d'un modele expose par l'Agent API. */
+export declare const semanticModelOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    source: z.ZodObject<{
+        kind: z.ZodEnum<{
+            postgres: "postgres";
+            clickhouse: "clickhouse";
+            d1: "d1";
+            inline: "inline";
+        }>;
+        label: z.ZodString;
+        table: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    dimensionCount: z.ZodNumber;
+    metricCount: z.ZodNumber;
+    version: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+/** Sortie : la description d'une metrique expose par l'Agent API. */
+export declare const semanticMetricOutputSchema: z.ZodObject<{
+    model: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodString;
+    unit: z.ZodOptional<z.ZodString>;
+    direction: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Sortie : le resultat d'une requete semantique. */
+export declare const semanticQueryOutputSchema: z.ZodObject<{
+    model: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodObject<{}, z.core.$loose>>;
+    rowCount: z.ZodNumber;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    pivot: z.ZodOptional<z.ZodObject<{
+        columns: z.ZodArray<z.ZodString>;
+        rows: z.ZodArray<z.ZodObject<{}, z.core.$loose>>;
+        columnValues: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Entree d'une requete semantique, telle que l'Agent API la recoit. */
+export type SemanticQueryInput = z.infer<typeof semanticQueryInputSchema>;
+/** Entree de creation d'un modele semantique. */
+export type SemanticModelInput = z.infer<typeof semanticModelInputSchema>;

package/dist/semantic/cache.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Politique de cache d'un resultat materialise.
+ *
+ * Le modele est repris de Metabase (`src/metabase/cache/schema.clj`,
+ * `src/metabase/cache/settings.clj`) : une duree de vie, une fenetre de
+ * rafraichissement anticipe, un plafond absolu de conservation et une taille
+ * maximale.
+ *
+ * La fenetre de rafraichissement anticipe est ce qui distingue une cache qui
+ * "pere" d'une cache qui "respire" : le resultat est rafraichit avant
+ * d'expirer, pour que la requete ne patisse jamais de l'attente du
+ * recalcul.
+ */
+export interface CachePolicy {
+    /** Duree de vie du resultat, en secondes. 0 = pas de cache. */
+    ttlSeconds: number;
+    /**
+     * Fraction de la duree retranchee pour rafraichir en avance.
+     * 0.15 = rafraichir quand 85 % de la duree est ecoulee.
+     */
+    earlyRefreshRatio?: number;
+    /** Plafond absolu de conservation, en secondes. */
+    maxTtlSeconds?: number;
+    /** Taille maximale du resultat materialise, en kilo-octets. */
+    maxSizeKb?: number;
+}
+export type CacheEntryState = "absent" | "fresh" | "expired";
+export interface CacheEntry {
+    /** Instant de calcul du resultat (ISO 8601). */
+    computedAt: string;
+    /** Instant d'expiration (ISO 8601). */
+    expiresAt: string;
+    /** Taille du resultat en octets. */
+    sizeBytes?: number;
+    /** Nombre de lignes du resultat. */
+    rowCount?: number;
+}
+export interface CacheDecision {
+    state: CacheEntryState;
+    /** Faut-il recalculer le resultat ? */
+    shouldRefresh: boolean;
+    /** Instant d'expiration, `null` si le cache est desactive. */
+    expiresAt: string | null;
+    /** Instant de rafraichissement anticipe, `null` si le cache est desactive. */
+    refreshAt: string | null;
+    /** Raison de la decision, en clair. */
+    reason: string;
+}
+/** Ratio de rafraichissement anticipe retenu par defaut. */
+export declare const DEFAULT_EARLY_REFRESH_RATIO = 0.15;
+/**
+ * Duree de vie effective, en millisecondes.
+ *
+ * Le plafond `maxTtlSeconds` borne la duree : une politique qui demanderait
+ * de garder un resultat un an quand le plafond est d'une heure doit obeyir au
+ * plafond.
+ */
+export declare function effectiveTtlMs(policy: CachePolicy | undefined): number;
+/**
+ * Fenetre de validite d'un resultat calcule a `computedAt`.
+ *
+ * `expiresAt` est l'instant ou le resultat n'est plus valable ; `refreshAt`
+ * est l'instant ou il faut deja le recalculer, avant d'expirer.
+ */
+export declare function resolveCacheWindow(policy: CachePolicy | undefined, computedAt: Date): {
+    expiresAt: string | null;
+    refreshAt: string | null;
+};
+/**
+ * Decide de l'etat d'une entree de cache et du besoin de recalcul.
+ *
+ * - entree absente : on recalcule ;
+ * - entree fraiche et `now < refreshAt` : on sert le cache ;
+ * - entree fraiche et `now >= refreshAt` : on rafraichit en avance, mais le
+ *   resultat existant reste valable jusqu'a `expiresAt` ;
+ * - entree expiree : on recalcule.
+ */
+export declare function evaluateCacheEntry(entry: CacheEntry | null | undefined, policy: CachePolicy | undefined, now?: Date): CacheDecision;
+/**
+ * Taille approximative d'un payload serialise, en octets.
+ *
+ * La longueur JS compte des unites UTF-16 ; un caractere accentue en occupe
+ * deux unites mais trois octets en UTF-8. On mesure donc la longueur reelle
+ * de la version encodee.
+ */
+export declare function estimateResultSize(payload: unknown): number;
+/**
+ * Un resultat trop volumineux ne doit pas etre materialise : la base ne
+ * doit pas stocker un payload que personne ne relira.
+ */
+export declare function isResultTooLarge(sizeBytes: number, policy: CachePolicy | undefined): boolean;

package/dist/semantic/catalog/seo-models.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticModel } from "../types";
+export declare const SEO_SEMANTIC_MODELS: SemanticModel[];

package/dist/semantic/catalog/seo-models.fixtures.d.ts

@@ -0,0 +1,17 @@
+import type { EvalRow } from "../eval-memory";
+/**
+ * Colonnes reelles et lignes d'exemple des tables du catalogue SEO.
+ *
+ * Les colonnes sont verifiees dans `apps/lynx-seo/src/db/app.schema.ts` et
+ * `apps/lynx-seo/src/db/pulse.schema.ts` (le 2026-10-20). Elles servent a
+ * deux choses : verifier qu'aucune expression du catalogue ne reference une
+ * colonne imaginaire, et fournir les donnees de la verification croisee
+ * SQL / memoire.
+ */
+export type FixtureColumnType = "text" | "real";
+export interface FixtureColumn {
+    name: string;
+    type: FixtureColumnType;
+}
+export declare const SEO_MODEL_COLUMNS: Record<string, FixtureColumn[]>;
+export declare const SEO_MODEL_SAMPLE_ROWS: Record<string, EvalRow[]>;

package/dist/semantic/chart-suggestion.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Choix du graphique d'un aperçu.
+ *
+ * Le choix déterministe : une métrique temporelle → courbe, une métrique
+ * catégorielle → barres, une métrique seule → jauge. Le type de la dimension
+ * est lu dans le `Dataset` quand il est connu ; à défaut, le **nom** de la
+ * colonne décide, car c'est la seule information disponible pour une colonne
+ * dont le type n'a pas été inféré.
+ */
+import type { Dataset } from "../chart-plan/dataset";
+import type { ChartPlan } from "../chart-plan/types";
+export interface ChartSuggestionInput {
+    dataset: Dataset;
+    dimensions: string[];
+    metrics: string[];
+    measure?: string;
+}
+export declare function isTemporalDimension(name: string): boolean;
+/**
+ * Propose un graphique pour l'aperçu, ou `null` quand la demande ne porte
+ * aucune métrique — il n'y a alors rien à mesurer.
+ */
+export declare function suggestChartPlan(input: ChartSuggestionInput): ChartPlan | null;

package/dist/semantic/compiler.d.ts

@@ -0,0 +1,69 @@
+import type { SqlDialect } from "./dialects";
+import type { AggregateFunction } from "../seo-query-builder";
+import type { MetricExpr } from "./expr";
+import type { CompiledQuery, SemanticModel, SemanticQuery } from "./types";
+/**
+ * Compile une expression isolee en SQL.
+ *
+ * Utilise par le registre des metriques SEO, dont chaque definition porte
+ * une expression : la meme formule doit produire le meme resultat en memoire
+ * et en base.
+ */
+export declare function compileExpression(expression: MetricExpr, dialect: SqlDialect): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * Compile une requete semantique.
+ *
+ * @param context Parametres lies dans le `baseSql` du modele
+ *                (ex. `{ projectId: "..." }`).
+ */
+export declare function compileQuery(model: SemanticModel, query: SemanticQuery, dialect: SqlDialect, context?: Record<string, unknown>, options?: {
+    now?: Date;
+}): CompiledQuery;
+/**
+ * Compile une fonction fenêtrée (ROW_NUMBER, RANK, LAG, LEAD, SUM OVER,
+ * COUNT OVER, etc.) dans le dialecte cible.
+ */
+export declare function compileWindowFunction(dialect: SqlDialect, expr: string, over: {
+    partitionBy?: string[];
+    orderBy?: string;
+    frame?: string;
+}): string;
+/**
+ * Compile une fonction d'offset (LAG/LEAD) dans le dialecte cible.
+ */
+export declare function compileOffset(dialect: SqlDialect, expr: string, offset: number, defaultValue: string | null, over: {
+    partitionBy?: string[];
+    orderBy?: string;
+}): string;
+/**
+ * Compile une fonction de rang (ROW_NUMBER, RANK, DENSE_RANK, PERCENT_RANK,
+ * CUME_DIST) dans le dialecte cible.
+ */
+export declare function compileRank(dialect: SqlDialect, kind: "row_number" | "rank" | "dense_rank" | "percent_rank" | "cum_dist", over: {
+    partitionBy?: string[];
+    orderBy: string;
+}): string;
+/**
+ * Compile une agrégation fenêtrée (SUM/COUNT/AVG/MIN/MAX OVER) dans le
+ * dialecte cible.
+ */
+export declare function compileWindowAggregate(dialect: SqlDialect, fn: AggregateFunction, expr: string, over: {
+    partitionBy?: string[];
+    orderBy?: string;
+    frame?: string;
+}): string;
+/**
+ * Compile un CTE (WITH ... AS (...)) dans le dialecte cible.
+ */
+export declare function compileCte(dialect: SqlDialect, name: string, query: string, columns?: string[]): string;
+/**
+ * Retourne `true` si le dialecte supporte les CTE.
+ */
+export declare function supportsCte(dialect: SqlDialect): boolean;
+/**
+ * Rend une table dérivée (sous-requête dans FROM) dans le dialecte cible.
+ */
+export declare function derivedTable(dialect: SqlDialect, query: string, alias: string): string;

package/dist/semantic/diagnostics.d.ts

@@ -0,0 +1,62 @@
+import type { MetricExpr } from "./expr";
+/**
+ * Le diagnostic des dependances du catalogue : quelles references sont
+ * casseees, et lesquelles empechent l'execution.
+ *
+ * Le concept vient de Metabase (`enterprise/backend/src/metabase_enterprise/dependencies`,
+ * qui refuse d'executer une question dont une dependance est cassee) : aucun
+ * code de l'amont n'est repris.
+ */
+export type DependencyObjectType = "model" | "metric" | "segment" | "transform" | "question";
+export type DependencyIssueCode = "missing_model" | "missing_dimension" | "missing_metric" | "missing_dependency" | "missing_table";
+export interface DependencyIssue {
+    severity: "error" | "warning";
+    objectType: DependencyObjectType;
+    objectName: string;
+    code: DependencyIssueCode;
+    message: string;
+}
+export interface DiagnosticModelInput {
+    name: string;
+    dimensions: string[];
+    metrics: string[];
+    sourceTable?: string | null;
+    /** Les colonnes physiques de la table source, quand elles sont connues. */
+    sourceColumns?: string[];
+    metricExpressions?: Record<string, MetricExpr>;
+}
+export interface DiagnosticSegmentInput {
+    name: string;
+    model: string;
+    field: string;
+}
+export interface DiagnosticTransformInput {
+    name: string;
+    model?: string | null;
+    dependsOn: string[];
+}
+export interface DiagnosticQuestionInput {
+    name: string;
+    model: string;
+    dimensions: string[];
+    metrics: string[];
+}
+export interface DiagnosticCatalogInput {
+    models: DiagnosticModelInput[];
+    segments?: DiagnosticSegmentInput[];
+    transforms?: DiagnosticTransformInput[];
+    questions?: DiagnosticQuestionInput[];
+    knownTables?: string[];
+}
+/**
+ * Les colonnes citees par une expression. Une expression `{ kind: "agg" }`
+ * porte sa propre expression interne : elle est parcourue comme les autres.
+ */
+export declare function collectColumnReferences(expr: MetricExpr): string[];
+export declare function diagnoseSemanticDependencies(input: DiagnosticCatalogInput): DependencyIssue[];
+export declare function blockingIssue(issues: DependencyIssue[], objectType: DependencyObjectType, objectName: string): DependencyIssue | undefined;
+/**
+ * Le garde d'execution : un objet dont une dependance est cassee n'est pas
+ * execute, et le refus nomme l'objet casse.
+ */
+export declare function assertNoBlockingIssue(issues: DependencyIssue[], objectType: DependencyObjectType, objectName: string): void;

package/dist/semantic/dialects/bigquery.d.ts

@@ -0,0 +1,2 @@
+import type { SqlDialect } from "./types";
+export declare const BIGQUERY_DIALECT: SqlDialect;

package/dist/semantic/dialects/clickhouse.d.ts

@@ -0,0 +1,2 @@
+import type { SqlDialect } from "./types";
+export declare const CLICKHOUSE_DIALECT: SqlDialect;

package/dist/semantic/dialects/features.d.ts

@@ -0,0 +1,10 @@
+import type { SqlDialect } from "./types";
+export declare function supportsCte(dialect: SqlDialect): boolean;
+export declare function supportsWindowFunctions(dialect: SqlDialect): boolean;
+export declare function supportsNativePivot(dialect: SqlDialect): boolean;
+export declare function supportsGroupingSets(dialect: SqlDialect): boolean;
+export declare function supportsJsonFunctions(dialect: SqlDialect): boolean;
+export declare function supportsArrayFunctions(dialect: SqlDialect): boolean;
+export declare function supportsMaterializedViews(dialect: SqlDialect): boolean;
+export declare function supportsFullTextSearch(dialect: SqlDialect): boolean;
+export declare function supportsGeometricFunctions(dialect: SqlDialect): boolean;

package/dist/semantic/dialects/index.d.ts

@@ -0,0 +1,10 @@
+import { BIGQUERY_DIALECT } from "./bigquery";
+import { CLICKHOUSE_DIALECT } from "./clickhouse";
+import { POSTGRES_DIALECT } from "./postgres";
+import { REDSHIFT_DIALECT } from "./redshift";
+import { SNOWFLAKE_DIALECT } from "./snowflake";
+import { SQLITE_DIALECT } from "./sqlite";
+import type { SqlDialect, SqlDialectId } from "./types";
+export { BIGQUERY_DIALECT, CLICKHOUSE_DIALECT, POSTGRES_DIALECT, REDSHIFT_DIALECT, SNOWFLAKE_DIALECT, SQLITE_DIALECT, };
+export type { DateTruncUnit, DateUnit, SqlDialect, SqlDialectId, SqlParamType, SqlValueType, } from "./types";
+export declare function getDialect(id: SqlDialectId): SqlDialect;

package/dist/semantic/dialects/postgres.d.ts

@@ -0,0 +1,2 @@
+import type { SqlDialect } from "./types";
+export declare const POSTGRES_DIALECT: SqlDialect;

package/dist/semantic/dialects/redshift.d.ts

@@ -0,0 +1,2 @@
+import type { SqlDialect } from "./types";
+export declare const REDSHIFT_DIALECT: SqlDialect;

package/dist/semantic/dialects/registry.d.ts

@@ -0,0 +1,31 @@
+import type { SqlDialect, SqlDialectId } from "./types";
+export type DialectFeature = "cte" | "window-functions" | "native-pivot" | "grouping-sets" | "materialized-views" | "json-functions" | "full-text-search" | "array-functions" | "geometric-functions";
+export type DialectRegistration = {
+    id: SqlDialectId;
+    dialect: SqlDialect;
+    /** Optional: dialect family (e.g. "postgres" for redshift, "clickhouse" for ch-compatible) */
+    family?: string;
+    /** Optional: features this dialect supports (CTE, window functions, pivot natively, etc.) */
+    features?: DialectFeature[];
+    /** Optional: default port, driver name, connection hint */
+    connection?: {
+        driver: string;
+        defaultPort?: number;
+    };
+};
+export declare class DialectRegistry {
+    private dialects;
+    constructor();
+    private registerDefaults;
+    register(reg: DialectRegistration): void;
+    unregister(id: SqlDialectId): void;
+    get(id: SqlDialectId): DialectRegistration;
+    has(id: SqlDialectId): boolean;
+    list(): DialectRegistration[];
+    listIds(): SqlDialectId[];
+    /** Find dialects that support a given feature */
+    withFeature(feature: DialectFeature): DialectRegistration[];
+    /** Find the best dialect for a use case */
+    resolve(id: SqlDialectId): DialectRegistration;
+}
+export declare const dialectRegistry: DialectRegistry;

package/dist/semantic/dialects/snowflake.d.ts

@@ -0,0 +1,2 @@
+import type { SqlDialect } from "./types";
+export declare const SNOWFLAKE_DIALECT: SqlDialect;

package/dist/semantic/dialects/sqlite.d.ts

@@ -0,0 +1,2 @@
+import type { SqlDialect } from "./types";
+export declare const SQLITE_DIALECT: SqlDialect;