@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/semantic/parameters/resolve.d.ts

@@ -0,0 +1,26 @@
+import type { QueryValue } from "../filters/types";
+import type { ParameterValues, SemanticParameter } from "./types";
+export interface ParameterResolutionOptions {
+    /** Utiliser la valeur par defaut du parametre. Vrai par defaut. */
+    useDefault?: boolean;
+    /** Valeurs retenues au tour precedent. */
+    lastUsed?: ParameterValues;
+}
+export type ResolvedParameters = Record<string, QueryValue | QueryValue[]>;
+/**
+ * Fusionne les parametres declares par le modele et ceux declares par la
+ * requete. La requete l'emporte sur le modele pour un meme nom : c'est
+ * elle qui sait ce qu'elle fournit, et une requete agent peut affiner la
+ * declaration d'un modele sans le modifier.
+ */
+export declare function mergeParameters(modelParameters?: SemanticParameter[], queryParameters?: SemanticParameter[]): SemanticParameter[];
+/**
+ * Resout les valeurs des parametres declares.
+ *
+ * Echec explicite dans trois cas : un parametre fourni n'est pas declare, un
+ * parametre obligatoire n'a pas de valeur, une valeur n'est pas du type
+ * attendu. Aucun de ces cas ne se degrade silencieusement : une requete
+ * qui s'execute avec des valeurs differentes de celles demandees est
+ * pire qu'une requete qui echoue.
+ */
+export declare function resolveParameterValues(parameters?: SemanticParameter[], values?: ParameterValues, options?: ParameterResolutionOptions): ResolvedParameters;

package/dist/semantic/parameters/types.d.ts

@@ -0,0 +1,23 @@
+import type { QueryValue } from "../filters/types";
+/**
+ * Types de parametre exposes par la couche semantique.
+ *
+ * Le vocabulaire est celui des types de champ deja supportes par les
+ * filtres (`FilterFieldType`), plus `category` qui decrit un parametre a
+ * choix multiple parmi une liste fermee.
+ */
+export declare const PARAMETER_TYPES: readonly ["string", "number", "boolean", "date", "category"];
+export type ParameterType = (typeof PARAMETER_TYPES)[number];
+export interface SemanticParameter {
+    /** Identifiant du parametre, utilise dans le SQL et les filtres. */
+    name: string;
+    type: ParameterType;
+    label?: string;
+    default?: QueryValue | QueryValue[];
+    required?: boolean;
+    /** Valeurs autorisees pour le type `category`. */
+    options?: QueryValue[];
+    /** Le parametre accepte une liste de valeurs. */
+    multiple?: boolean;
+}
+export type ParameterValues = Record<string, QueryValue | QueryValue[]>;

package/dist/semantic/parameters/values.d.ts

@@ -0,0 +1,60 @@
+import type { QueryValue } from "../filters/types";
+import type { ParameterType, ParameterValues, SemanticParameter } from "./types";
+/**
+ * Semantique des valeurs de parametre.
+ *
+ * Port cible de `metabase-lib/v1/parameters/utils/parameter-values.ts`, avec
+ * deux divergences assumees :
+ *
+ * 1. Metabase renvoie toujours un tableau pour les types `string` et `number`
+ *    parce que ses widgets sont multi-selection par defaut. LynxSEO rend
+ *    l'unicite explicite via `multiple`, donc un parametre simple reste un
+ *    scalaire.
+ * 2. Metabase compare l'egalite de deux jeux de valeurs via `_.isEqual`.
+ *    L'egalite est ici definie sans dependance : memes elements, ordre
+ *    indifferent.
+ */
+export declare function isParameterValueEmpty(value: unknown): boolean;
+/**
+ * Normalise une valeur brute vers le type du parametre.
+ *
+ * Retourne `null` quand la valeur ne peut pas etre convertie : la
+ * validation du type est une decision de l'appelant (un parametre
+ * obligatoire doit echouer, un parametre optionnel doit retomber sur sa
+ * valeur par defaut).
+ */
+export declare function normalizeParameterValue(type: ParameterType, value: unknown, multiple?: boolean): QueryValue | QueryValue[] | null;
+export interface ParameterValueLookup {
+    parameter: SemanticParameter;
+    values?: ParameterValues;
+    /** Utiliser la valeur par defaut du parametre. */
+    useDefault?: boolean;
+    /** Valeur retenue au tour precedent, prioritaire sur tout le reste. */
+    lastUsedParameterValue?: QueryValue | QueryValue[];
+}
+/**
+ * Valeur effective d'un parametre.
+ *
+ * Ordre de precedence : valeur retenue au tour precedent, valeur fournie,
+ * valeur par defaut, `null`.
+ */
+export declare function getParameterValue({ parameter, values, useDefault, lastUsedParameterValue, }: ParameterValueLookup): QueryValue | QueryValue[];
+/**
+ * Egalite de deux jeux de valeurs de parametre : memes elements, ordre
+ * indifferent. Deux listes de longueurs differentes ne sont jamais egales.
+ */
+export declare function areParameterValuesIdentical(a: QueryValue | QueryValue[] | undefined, b: QueryValue | QueryValue[] | undefined): boolean;
+export type ParameterValidation = {
+    ok: true;
+    value: QueryValue | QueryValue[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Valide une valeur contre la declaration d'un parametre.
+ *
+ * Le type `date` accepte une date ISO ou un instant epoch, normalisee en
+ * jour ISO `YYYY-MM-DD` — c'est la granularite des operateurs temporels.
+ */
+export declare function validateParameterValue(parameter: SemanticParameter, value: unknown): ParameterValidation;

package/dist/semantic/periods/period-filter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Le pont entre une période relative et un filtre.
+ *
+ * Un filtre persisté porte des bornes (« entre le 1er et le 31 »). Une
+ * période relative (« les 30 derniers jours ») se transforme en ces bornes au
+ * moment de la compilation : le SQL et l'évaluation en mémoire ne voient
+ * ainsi qu'un `between` ordinaire, et les deux backends ne peuvent pas
+ * diverger.
+ */
+import type { QueryFilter, RelativePeriod } from "../filters/types";
+/** Les options de résolution d'une période. */
+export interface PeriodResolutionOptions {
+    /** Le moment de référence de la période. */
+    now?: Date;
+    /** Le premier jour de la semaine : 1 = lundi, 0 = dimanche. */
+    firstDayOfWeek?: number;
+}
+/**
+ * Transforme une période relative en filtre `between` sur des jours ISO.
+ *
+ * Le filtre porte la période d'origine : l'interface peut donc afficher
+ * « les 30 derniers jours » alors que l'exécution porte des bornes.
+ */
+export declare function relativePeriodToFilter(field: string, period: RelativePeriod, options?: PeriodResolutionOptions): QueryFilter;
+/**
+ * Résout la période d'un filtre, si elle en porte une.
+ *
+ * Un filtre qui porte déjà une valeur n'est pas touché : ses bornes ont été
+ * résolues à la création, et les ré-resoudre à l'exécution ferait bouger une
+ * fenêtre qui ne doit pas bouger.
+ */
+export declare function resolvePeriodFilter(filter: QueryFilter, options?: PeriodResolutionOptions): QueryFilter;

package/dist/semantic/periods/relative.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Les périodes relatives.
+ *
+ * Comparer une période à la précédente est le premier besoin d'un tableau de
+ * bord SEO : « ce mois-ci contre le mois dernier », « les 30 derniers jours
+ * contre les 30 précédents ». Exprimer une fenêtre en dur (« 2026-09-01 » →
+ * « 2026-09-30 ») figeait la requête ; l'exprimer en période relative la rend
+ * reproductible et comparable d'une exécution à l'autre.
+ *
+ * La sémantique est celle de Metabase (`src/metabase/util/time/impl.clj`,
+ * fonction `to-range`) : une période est un point d'ancrage plus une
+ * quantité d'unités, et la fenêtre est **bornée inclusive**.
+ */
+import { RELATIVE_UNITS, type RelativePeriod, type RelativeUnit } from "../filters/types";
+export { RELATIVE_UNITS };
+export type { RelativePeriod, RelativeUnit };
+/** Une fenêtre résolue, bornes inclusives. */
+export interface PeriodRange {
+    /** Le premier instant de la fenêtre. */
+    start: Date;
+    /** Le dernier instant de la fenêtre, inclus. */
+    end: Date;
+}
+/** Les bornes calendaires d'une fenêtre, au format jour ISO. */
+export interface PeriodBounds {
+    /** Le premier jour de la fenêtre, `YYYY-MM-DD`. */
+    startDay: string;
+    /** Le dernier jour de la fenêtre, `YYYY-MM-DD`. */
+    endDay: string;
+}
+/** Le premier jour de la semaine : 1 = lundi (ISO), 0 = dimanche. */
+export declare const DEFAULT_FIRST_DAY_OF_WEEK = 1;
+/**
+ * Ajoute un nombre d'unités calendaires à une date.
+ *
+ * Les unités jour et semaine sont des durées fixes ; mois, trimestre et année
+ * sont des unités calendaires, bornées à la fin du mois.
+ */
+export declare function addRelativeUnits(date: Date, unit: RelativeUnit, count: number): Date;
+/**
+ * Tronque une date à son unité calendaire.
+ *
+ * La troncature est faite en UTC : la fenêtre d'un jour est la même partout,
+ * que le serveur soit à Paris ou à Tokyo.
+ */
+export declare function truncateToRelativeUnit(date: Date, unit: RelativeUnit, firstDayOfWeek?: number): Date;
+/**
+ * Résout une période relative en fenêtre de dates.
+ *
+ * Le point d'ancrage se déplace d'abord vers le passé (`value` négatif) ou
+ * vers l'unité suivante (`value` positif sans période courante incluse), puis
+ * d'un éventuel décalage. La fenêtre couvre ensuite `value` unités
+ * calendaires entières, la période courante étant comptée en plus si elle est
+ * incluse.
+ */
+export declare function resolveRelativePeriod(period: RelativePeriod, now?: Date, firstDayOfWeek?: number): PeriodRange;
+/** Les bornes calendaires d'une période, au format jour ISO. */
+export declare function relativePeriodBounds(period: RelativePeriod, now?: Date, firstDayOfWeek?: number): PeriodBounds;
+/** Un raccourci de période proposé par l'interface. */
+export interface RelativePeriodPreset {
+    /** L'identifiant stable du raccourci. */
+    id: string;
+    /** Le libellé affiché. */
+    label: string;
+    /** La période que le raccourci exprime. */
+    period: RelativePeriod;
+}
+/**
+ * Les raccourcis de période.
+ *
+ * Ils reprennent les raccourcis de Metabase
+ * (`frontend/src/metabase/querying/common/components/DatePicker/DateShortcutPicker/constants.ts`)
+ * et couvrent les besoins d'un tableau de bord SEO : la période en cours, la
+ * période précédente, et les fenêtres glissantes de 7, 30 jours, 3 et 12
+ * mois.
+ */
+export declare const RELATIVE_PERIOD_PRESETS: readonly RelativePeriodPreset[];
+/** Le raccourci de période d'un identifiant donné. */
+export declare function relativePeriodPreset(id: string): RelativePeriodPreset;
+/**
+ * Décrit une période relative en français, à partir de ses bornes résolues.
+ *
+ * La description nomme la fenêtre réellement couverte, pas l'expression :
+ * « 1 – 7 octobre 2026 » est plus utile qu'« il y a 7 jours ».
+ */
+export declare function describeRelativePeriod(period: RelativePeriod, now?: Date, firstDayOfWeek?: number): string;

package/dist/semantic/pipeline.d.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import { type SemanticQueryInput } from "./agent-schema";
+import type { SqlDialect } from "./dialects";
+import type { CompiledQuery, SemanticModel } from "./types";
+/**
+ * Pipelines semantiques : un "notebook" de requete.
+ *
+ * Un pipeline est une suite ORDONNEE d'etapes (filtre, agregation,
+ * expression, tri, limite). La source est **implicite** : c'est le modele
+ * semantique que le pipeline cible (`doc.model`). Le pipeline se serialise en
+ * JSON (`pipeline_documents`), se valide a la lecture, puis se compile en SQL
+ * parametre via `compileQuery`.
+ *
+ * Le document ne porte volontairement **pas** l'identifiant de projet : le
+ * tenant est injecte par le contexte de compilation, jamais par le document
+ * persiste. Un document qui pourrait fixer son propre projet serait une voie
+ * de fuite inter-tenant.
+ */
+/** Les types d'etapes reconnus. */
+export type PipelineStageKind = "filter" | "aggregate" | "expression" | "sort" | "limit";
+/**
+ * Une etape de pipeline.
+ *
+ * `config` est un objet libre au niveau du type : sa forme exacte depend du
+ * `kind` et est verifiee a l'execution par `pipelineDocumentSchema`. Les cles
+ * attendues sont :
+ * - `filter`     : `{ filters: QueryFilter[] }` ;
+ * - `aggregate`  : `{ dimensions: string[]; metrics: string[] }` ;
+ * - `expression` : `{ name: string; role?: "dimension" | "metric"; expression?: MetricExpr }` ;
+ * - `sort`       : `{ sort: { by: string; dir: "asc" | "desc" }[] }` ;
+ * - `limit`      : `{ limit: number; offset?: number }`.
+ */
+export interface PipelineStage {
+    id: string;
+    kind: PipelineStageKind;
+    label?: string;
+    config: Record<string, unknown>;
+}
+/** Un pipeline persiste : sa version, son modele et ses etapes ordonnees. */
+export interface PipelineDocument {
+    version: 1;
+    model: string;
+    stages: PipelineStage[];
+}
+/**
+ * Le schema d'un pipeline persiste.
+ *
+ * Il reutilise `semanticFilterSchema` et `semanticExpressionSchema` du
+ * contrat de l'Agent API : la forme d'un filtre ou d'une expression est
+ * decrite a UN seul endroit, donc elle ne peut pas diverger entre les deux
+ * surfaces.
+ */
+export declare const pipelineDocumentSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    model: z.ZodString;
+    stages: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"filter">;
+        label: z.ZodOptional<z.ZodString>;
+        config: z.ZodObject<{
+            filters: 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>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"aggregate">;
+        label: z.ZodOptional<z.ZodString>;
+        config: z.ZodObject<{
+            dimensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            metrics: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"expression">;
+        label: z.ZodOptional<z.ZodString>;
+        config: z.ZodObject<{
+            name: z.ZodString;
+            role: z.ZodDefault<z.ZodEnum<{
+                metric: "metric";
+                dimension: "dimension";
+            }>>;
+            expression: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    column: "column";
+                    binary: "binary";
+                    literal: "literal";
+                    call: "call";
+                    agg: "agg";
+                    case: "case";
+                    ifnull: "ifnull";
+                }>;
+            }, z.core.$loose>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"sort">;
+        label: z.ZodOptional<z.ZodString>;
+        config: z.ZodObject<{
+            sort: z.ZodArray<z.ZodObject<{
+                by: z.ZodString;
+                dir: z.ZodEnum<{
+                    asc: "asc";
+                    desc: "desc";
+                }>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"limit">;
+        label: z.ZodOptional<z.ZodString>;
+        config: z.ZodObject<{
+            limit: z.ZodNumber;
+            offset: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+/**
+ * Lit et valide un pipeline depuis son JSON persiste.
+ *
+ * Le `JSON.parse` est isole dans un `try/catch` : un document corrompu leve
+ * une erreur explicite, jamais un `undefined` silencieux. Aucun `as` n'est
+ * utilise : la validation zod produit seule le type de sortie.
+ */
+export declare function parsePipelineDocument(json: string): PipelineDocument;
+/**
+ * Convertit un document de pipeline en entree de requete.
+ *
+ * Les etapes sont parcourues DANS L'ORDRE : les filtres s'accumulent, les
+ * dimensions et les metriques s'ajoutent dans l'ordre de declaration, le tri
+ * s'empile, et la derniere etape de limite l'emporte. Le `projectId` n'est pas
+ * porte par le document : il est fourni par l'appelant (contexte de tenant).
+ */
+export declare function pipelineDocumentToQueryInput(doc: PipelineDocument, projectId?: string): SemanticQueryInput;
+/**
+ * Compile un pipeline en SQL parametre.
+ *
+ * Le deuxieme argument est le JSON BRUT du pipeline (tel que persiste dans
+ * `semantic_pipelines.pipeline_json`) : le parsing et la validation restent
+ * dans le moteur, l'appelant ne manipule jamais d'objet non verifie.
+ *
+ * Le `context` porte l'isolation du tenant (`{ projectId }`) : il est
+ * transmis tel quel a `compileQuery`.
+ */
+export declare function compilePipelineToQuery(model: SemanticModel, pipelineJson: string, dialect: SqlDialect, context?: Record<string, unknown>, options?: {
+    now?: Date;
+}): CompiledQuery;

package/dist/semantic/pivot-powerset.d.ts

@@ -0,0 +1,31 @@
+import type { SemanticQuery, SemanticModel, CompiledQuery } from "./types";
+import type { PivotResult } from "./pivot";
+import type { SqlDialect } from "./dialects/types";
+export interface PivotOptions {
+    rows: string[];
+    cols: string[];
+    metrics: string[];
+    showRowTotals: boolean;
+    showColumnTotals: boolean;
+    showGrandTotal: boolean;
+    includeSubtotals: boolean;
+}
+export interface PivotSubQuery {
+    label: string;
+    groupBy: string[];
+    isTotal: boolean;
+    query: SemanticQuery;
+}
+export declare function breakoutCombinations(numBreakouts: number, pivotRows: number[] | null, pivotCols: number[] | null): number[][];
+export declare function generatePivotSubQueries(query: SemanticQuery, options: PivotOptions): PivotSubQuery[];
+export declare function compileGroupingSets(groupBy: string[], combinations: number[][], dialect: SqlDialect): {
+    sql: string;
+    groupingMarker: string;
+};
+export declare function executePivot(query: SemanticQuery, options: PivotOptions, dialect: SqlDialect, executor: (compiled: CompiledQuery) => Promise<{
+    columns: {
+        name: string;
+        type?: string;
+    }[];
+    rows: Record<string, unknown>[];
+}>, model?: SemanticModel, compile?: (model: SemanticModel, q: SemanticQuery, d: SqlDialect) => CompiledQuery): Promise<PivotResult>;

package/dist/semantic/pivot.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Le pivot LynxSEO : un jeu plat devient un tableau large (lignes × colonnes).
+ *
+ * Réécriture du concept de Metabase (`src/metabase/pivot/core.cljc` et
+ * `frontend/src/metabase-lib/v1/queries/utils/pivot.ts`). Aucun code de
+ * l'amont n'est repris : là-haut le pivot passe par une requête LQL, un
+ * composant React et des sous-totaux annotés par un `pivot-grouping` ; ici
+ * le pivot est une transformation **pure** du jeu déjà reçu.
+ */
+import type { Dataset, DatasetValue } from "../chart-plan/dataset";
+export interface PivotSpec {
+    /** Dimensions qui constituent la clé de ligne. */
+    rowFields: string[];
+    /**
+     * Dimensions dont les valeurs deviennent les colonnes.
+     *
+     * Metabase répartit le pivot en `pivot_table.column_split = { rows,
+     * columns, values }` : `columns` est une **liste**. Croiser deux
+     * dimensions (par exemple l'appareil et le pays) donne une colonne par
+     * combinaison de leurs valeurs.
+     */
+    columnFields: string[];
+    /** Mesures croisées avec les valeurs des dimensions de colonne. */
+    valueFields: string[];
+    /** Ajoute une colonne « Total » qui somme les cellules de chaque ligne. */
+    showRowTotals?: boolean;
+    /** Ajoute une ligne « Total » qui somme les cellules de chaque colonne. */
+    showColumnTotals?: boolean;
+}
+export interface PivotResult {
+    /** Noms des colonnes du tableau large, dans l'ordre d'affichage. */
+    columns: string[];
+    /** Une ligne par combinaison des dimensions de ligne. */
+    rows: Record<string, DatasetValue>[];
+    /**
+     * Combinaisons de valeurs des dimensions de colonne, triées. Avec une
+     * seule dimension de colonne, c'est la liste de ses valeurs ; avec
+     * plusieurs, chaque entrée est la jointure des valeurs par ` — `.
+     */
+    columnValues: string[];
+}
+export declare function pivotDataset(dataset: Dataset, spec: PivotSpec): PivotResult;
+/** Colonnes et lignes d'un resultat de requete, telles que servies par l'API. */
+export interface QueryResultLike {
+    columns: {
+        name: string;
+        type?: string;
+    }[];
+    rows: Record<string, DatasetValue>[];
+}
+/**
+ * Pivote un resultat de requete.
+ *
+ * Le pivot est applique **cote serveur** : la question enregistree porte
+ * son pivot, donc c'est la reponse servie — et non l'affichage — qui est
+ * croisee. Le client recoit alors le meme tableau large que l'API.
+ */
+export declare function pivotQueryResult(result: QueryResultLike, spec: PivotSpec): PivotResult;

package/dist/semantic/primitives.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Primitives arithmétiques partagées par la couche sémantique.
+ *
+ * Ces trois fonctions sont l'**unique** définition de la division sûre, du
+ * pourcentage sûr et de la normalisation d'un CTR. Le registre SEO
+ * (`seo-metric-registry.ts`) les ré-exporte, et l'évaluateur en mémoire
+ * (`eval-memory.ts`) les utilise : les déplacer ici permet au registre de
+ * s'appuyer sur l'évaluateur sans créer un cycle d'import entre les deux
+ * modules. L'API publique du registre est inchangée.
+ */
+/**
+ * Division that never returns NaN/Infinity: a zero denominator yields 0, which
+ * is what every reporting screen has to show before any data exists.
+ */
+export declare function safeRatio(numerator: number, denominator: number): number;
+/** `safeRatio` expressed as a percentage. */
+export declare function safePercent(numerator: number, denominator: number, precision?: number): number;
+/**
+ * Accepts both shapes a CTR arrives in: a ratio (0.42) or a percentage string
+ * already parsed (42). Replaces the `if (ctr > 1) ctr /= 100` heuristic that
+ * silently mangled a genuine ratio of exactly 1.
+ */
+export declare function normalizeCtrInput(value: number): number;

package/dist/semantic/question.d.ts

@@ -0,0 +1,71 @@
+import type { ParameterValues } from "./parameters/types";
+import type { SemanticQuery } from "./types";
+/**
+ * Une question enregistree.
+ *
+ * Un **modele** semantique decrit une source et ses dimensions/metriques ; une
+ * **question** est une instance executable de ce modele : un nom, une requete,
+ * des valeurs de parametres et un mode d'affichage.
+ *
+ * Le concept est repris de la carte de Metabase (`metabase-lib/v1/Question.ts`) :
+ * une requete nommee, reutilisable, executable a la demande. Aucun code de
+ * l'amont n'est repris.
+ *
+ * La question ne declare **pas** ses parametres : ils sont declares par le
+ * modele. Elle ne porte que les **valeurs**. C'est ce qui permet de changer
+ * la declaration d'un parametre sans reecrire toutes les questions qui
+ * l'utilisent.
+ */
+export type QuestionDisplay = "table" | "chart";
+export interface SemanticQuestion {
+    id?: string;
+    name: string;
+    description?: string;
+    /** Nom du modele semantique execute. */
+    model: string;
+    /** Requete posee sur ce modele. */
+    query: SemanticQuery;
+    /** Mode d'affichage du resultat. */
+    display: QuestionDisplay;
+    /** Valeurs des parametres declares par le modele. */
+    parameterValues?: ParameterValues;
+}
+/**
+ * Serialisation canonique : les cles d'objet sont triees, l'ordre des tableaux
+ * est conserve.
+ *
+ * Deux objets semantiquement egaux doivent produire la meme chaine, quelle que
+ * soit l'ordre dans lequel leurs cles ont ete ecrites. C'est la base de la
+ * cle de cache : une question reecrite avec les memes valeurs dans un autre
+ * ordre ne doit pas invalider le cache.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Hash FNV-1a sur 64 bits (deux mots de 32 bits).
+ *
+ * Le moteur ne peut pas utiliser `crypto.subtle` : l'API est asynchrone et
+ * n'existe pas partout. Un hash de cabinet synchrone et sans dependance suffit
+ * ici — son role est de distinguer deux questions, pas de resister a une
+ * attaque par collision.
+ */
+export declare function hashCanonical(value: string): string;
+/**
+ * Cle de cache d'une question.
+ *
+ * Elle depend du modele, de la requete et des valeurs de parametres — pas du
+ * nom de la question, ni de son identifiant : renommer une question ne doit
+ * pas invalider son cache, mais changer une valeur de filtre doit.
+ */
+export declare function questionCacheKey(question: SemanticQuestion): string;
+/**
+ * Complete une question par ses valeurs par defaut.
+ *
+ * Une question enregistree sans nom porte le nom de son modele ; sans mode
+ * d'affichage, elle s'affiche en tableau.
+ */
+export declare function normalizeQuestion(question: SemanticQuestion): SemanticQuestion;
+/**
+ * Une question est exécutable si elle vise un modele et demande au moins une
+ * dimension ou une metrique : sans elle, la requete ne selectionnerait rien.
+ */
+export declare function isQuestionRunnable(question: SemanticQuestion): boolean;

package/dist/semantic/registry.d.ts

@@ -0,0 +1,31 @@
+import type { SemanticModel, SemanticSegment } from "./types";
+/**
+ * L'interface unique d'acces aux modeles semantiques.
+ *
+ * Deux implementations : le **catalogue** livre en dur dans le moteur, et le
+ * **registre base** qui porte les modeles ecrits par l'utilisateur. Les deux
+ * se fusionnent a la lecture : un modele utilisateur portant le meme nom
+ * **ecrase** le modele livre (surcharge controlee).
+ */
+export interface SemanticRegistry {
+    listModels(): Promise<SemanticModel[]>;
+    getModel(name: string): Promise<SemanticModel | null>;
+    /**
+     * Modele par identifiant persiste.
+     *
+     * Les surfaces qui recoivent un identifiant (pipeline enregistre, question
+     * mathematisee) ne connaissent pas le nom : resoudre par nom les forcerait a
+     * un aller-retour supplementaire, et un renommage casserait le lien.
+     */
+    getModelById(id: string): Promise<SemanticModel | null>;
+    saveModel(model: SemanticModel): Promise<void>;
+    deleteModel(id: string): Promise<void>;
+    listSegments(model?: string): Promise<SemanticSegment[]>;
+    saveSegment(segment: SemanticSegment): Promise<void>;
+}
+export declare function createCatalogRegistry(models: SemanticModel[]): SemanticRegistry;
+/**
+ * Fusionne un registre de base et un registre utilisateur. Le registre
+ * utilisateur ecrase le catalogue pour un modele de meme nom.
+ */
+export declare function createOverlayRegistry(base: SemanticRegistry, overlay: SemanticRegistry): SemanticRegistry;