drizzle-cube 0.7.0 → 0.8.0

package/dist/server/adapters/base-adapter.d.ts

@@ -111,6 +111,17 @@ export interface DatabaseAdapter {
      * @returns SQL expression with type casting
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Cast expression to specific database type, tolerantly: unparseable input yields NULL
+     * instead of raising an error (PostgreSQL's `::`/`CAST` on bad input) or silently producing
+     * 0 (MySQL/SQLite `CAST` on non-numeric text). Intended for EAV-style schemas where a text
+     * column holds numbers/timestamps for some attributes and free text for others, so one dirty
+     * value doesn't fail the whole query or masquerade as a real 0.
+     * @param fieldExpr - The field expression to cast
+     * @param targetType - Target database type
+     * @returns SQL expression with tolerant type casting; unparseable/NULL input yields NULL
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Build AVG aggregation expression with database-specific null handling
      * @param fieldExpr - The field expression to average
@@ -216,6 +227,7 @@ export declare abstract class BaseDatabaseAdapter implements DatabaseAdapter {
     abstract buildPeriodSeriesSubquery(maxPeriod: number): SQL;
     abstract buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
     abstract castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    abstract tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     abstract getCapabilities(): DatabaseCapabilities;
     abstract buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL | null;
     /**
@@ -303,6 +315,40 @@ export declare abstract class BaseDatabaseAdapter implements DatabaseAdapter {
         field: AnyColumn | SQL;
         direction: 'asc' | 'desc';
     }>, config?: WindowFunctionConfig): SQL | null;
+    /**
+     * Regex pattern for tryCastToType's decimal guard: optional leading sign, digits with an
+     * optional fractional part (or a bare fractional part like `.5`), surrounded by optional
+     * spaces; rejects everything else. Shared by PostgreSQL (`~`) and MySQL/SingleStore
+     * (`REGEXP`).
+     *
+     * Deliberately written using only POSIX ERE syntax (`[0-9]` instead of `\d`, a literal
+     * space instead of `\s`) rather than Perl/ICU shorthands. PostgreSQL's `~` always
+     * understands `\d`/`\s`, and MySQL 8.0.4+'s default ICU regex engine does too — but
+     * SingleStore's `REGEXP` is dialect-switchable via the `regexp_format` session variable
+     * ('extended' = POSIX ERE, 'advanced' = ICU/PCRE-style), and SingleStore's own docs
+     * recommend explicitly opting into 'advanced' for new regex logic, implying 'extended'
+     * (POSIX, no `\d`/`\s`) is the default. Since SingleStoreAdapter inherits this pattern
+     * unchanged from MySQLAdapter and this repo doesn't control session variables for
+     * consumers, the pattern is written as the POSIX-ERE/ICU/ARE intersection so it matches
+     * correctly regardless of which dialect is active.
+     */
+    protected decimalTryCastPattern(): string;
+    /**
+     * Regex pattern for tryCastToType's integer guard: optional leading sign, digits only,
+     * surrounded by optional spaces. Same POSIX-ERE/ICU/ARE-portable rationale as
+     * decimalTryCastPattern().
+     */
+    protected integerTryCastPattern(): string;
+    /**
+     * Regex pattern for tryCastToType's timestamp guard: an ISO 8601-shaped date, optionally
+     * followed by a time component (with optional seconds, fractional seconds and a UTC/offset
+     * suffix), surrounded by optional spaces. This only validates the *shape* of the input —
+     * it does not catch calendar-invalid dates (e.g. 2024-02-30) or reject strings that "look"
+     * like a timestamp but aren't (that would need engine-side parsing, which is exactly what
+     * tryCastToType is avoiding relying on for error-safety). Same POSIX-ERE/ICU/ARE-portable
+     * rationale as decimalTryCastPattern().
+     */
+    protected timestampTryCastPattern(): string;
     /**
      * Helper method to build pattern for string matching
      * Can be overridden by specific adapters if needed

package/dist/server/adapters/databend-adapter.d.ts

@@ -45,6 +45,11 @@ export declare class DatabendAdapter extends BaseDatabaseAdapter {
      * Databend supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build Databend tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Databend capabilities - start conservative
      */

package/dist/server/adapters/duckdb-adapter.d.ts

@@ -52,6 +52,11 @@ export declare class DuckDBAdapter extends BaseDatabaseAdapter {
      * DuckDB supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build DuckDB tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * DuckDB has full support for statistical and window functions
      * Note: supportsPercentileSubqueries is false because DuckDB's QUANTILE_CONT

package/dist/server/adapters/mysql-adapter.d.ts

@@ -47,6 +47,20 @@ export declare class MySQLAdapter extends BaseDatabaseAdapter {
      * MySQL equivalent to PostgreSQL's :: casting syntax
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build MySQL tolerant type casting: NULL on unparseable input instead of MySQL's usual
+     * lenient-but-wrong behaviour. `CAST(x AS DECIMAL/SIGNED)` parses a leading numeric prefix
+     * (or returns 0 with a warning if there's no numeric prefix at all) rather than erroring —
+     * so a dirty value like 'n/a' silently becomes 0. `CAST(x AS DATETIME)` on a string that
+     * merely looks date-shaped but is calendar-invalid can, depending on sql_mode, raise an
+     * error (strict mode, the MySQL 8 default) rather than returning NULL. Guard all three with
+     * REGEXP so we only ever attempt the cast on input that already looks like the target type;
+     * anything else short-circuits to NULL first.
+     *
+     * The timestamp guard only validates ISO 8601 *shape* — it will not catch calendar-invalid
+     * dates like 2024-02-30, which could still error under strict SQL mode.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * MySQL AVG/STDDEV/VARIANCE use IFNULL (no COALESCE-for-zero idiom mismatch,
      * but IFNULL is the MySQL-idiomatic null guard).

package/dist/server/adapters/postgres-adapter.d.ts

@@ -43,6 +43,21 @@ export declare class PostgresAdapter extends BaseDatabaseAdapter {
      * Extracted from various locations where ::timestamp was used
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build PostgreSQL tolerant type casting: NULL on unparseable input instead of an error.
+     * PostgreSQL has no TRY_CAST, and `CAST(x AS type DEFAULT NULL ON ERROR)` (added in a
+     * recent PostgreSQL release) requires a minimum server version. This repo pins no minimum
+     * PostgreSQL version anywhere (CI/dev docker-compose both run `postgres:18`, but nothing
+     * documents that as a floor for consumers), so we don't assume newer syntax is available.
+     * Instead, guard the cast with a POSIX regex (`~`) so we only ever attempt to cast values
+     * that already look like the target type; anything else short-circuits to NULL before the
+     * cast runs, so PostgreSQL never gets a chance to raise.
+     *
+     * The timestamp guard only validates ISO 8601 *shape* (see timestampTryCastPattern) — it
+     * will not catch calendar-invalid dates like 2024-02-30, which would still error. A full
+     * guarantee would need a helper SQL function (out of scope here).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * PostgreSQL has full support for statistical and window functions
      */

package/dist/server/adapters/snowflake-adapter.d.ts

@@ -41,6 +41,12 @@ export declare class SnowflakeAdapter extends BaseDatabaseAdapter {
      * Snowflake supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build Snowflake tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST). Snowflake's
+     * TRY_CAST supports VARCHAR, NUMBER-family types (including DECIMAL) and TIMESTAMP.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Snowflake capabilities - full SQL support
      */

package/dist/server/adapters/sqlite-adapter.d.ts

@@ -51,6 +51,27 @@ export declare class SQLiteAdapter extends BaseDatabaseAdapter {
      * SQLite has dynamic typing but supports CAST for consistency
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build SQLite tolerant type casting: NULL on unparseable input instead of SQLite's usual
+     * dynamic-typing behaviour. SQLite's CAST-to-numeric applies "prefix" conversion — the
+     * longest numeric prefix of the string is used, or 0 if there is none — so `CAST('n/a' AS
+     * REAL)` silently yields 0.0 rather than erroring or returning NULL.
+     *
+     * SQLite has no REGEXP operator by default (it requires loading an extension, same
+     * limitation regexCondition() works around with GLOB). GLOB's `*`/`?`/`[...]` syntax can't
+     * express "one or more digits" directly, but the standard SQLite idiom for "string contains
+     * only characters from a set" is `NOT x GLOB '*[^set]*'` — true only if no character outside
+     * the set appears anywhere. That's what's used below to validate the trimmed value contains
+     * only the characters a valid decimal/integer/epoch-ms value could use, before attempting
+     * the cast; empty/whitespace-only strings are excluded separately.
+     *
+     * Known limitation: this is a character-set check, not a full grammar check, so a malformed
+     * value that still only uses allowed characters (e.g. '1.2.3' or '+-5') passes the guard and
+     * is then handled by SQLite's own prefix-based numeric parsing (never an error, but not
+     * necessarily NULL either). Clearly non-numeric input (letters, 'n/a', punctuation outside
+     * the allowed set) is reliably rejected to NULL, which is the case this method exists for.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * SQLite AVG uses IFNULL rather than COALESCE for null-to-zero handling.
      */

package/dist/server/attribute-dimensions.d.ts

@@ -0,0 +1,99 @@
+import { AnyColumn, SQL } from 'drizzle-orm';
+import { Dimension, QueryContext } from './types/index.js';
+/** The value types a generated attribute dimension can be cast to. */
+export type AttributeValueType = 'string' | 'number' | 'time';
+/** One admin-defined attribute, as loaded from the application's own table. */
+export interface AttributeDefinition {
+    /**
+     * Stable identifier. The dimension's member name is derived from this, never
+     * from the attribute's name — so renaming an attribute updates every table
+     * header without breaking saved dashboards, drill state or share links.
+     */
+    id: string | number;
+    /** Display name. Becomes the dimension's `title`, which the client renders. */
+    name: string;
+    /**
+     * Value type, if the application's attribute table records one. Filtering and
+     * sorting happen in SQL over the whole table before any row reaches the
+     * browser, so this is not cosmetic — see {@link buildAttributeDimensions}.
+     */
+    valueType?: AttributeValueType;
+}
+export interface BuildAttributeDimensionsOptions {
+    /** The attributes to generate a dimension for. */
+    attributes: AttributeDefinition[];
+    /** The junction table holding one row per (record, attribute). */
+    valueTable: unknown;
+    /** Primary key of the record being extended — e.g. `employees.id`. */
+    recordKey: AnyColumn;
+    /** Column on the junction table pointing back at the record. */
+    foreignKey: AnyColumn;
+    /** Column on the junction table identifying the attribute. */
+    attributeKey: AnyColumn;
+    /** Column on the junction table holding the value. */
+    valueColumn: AnyColumn;
+    /**
+     * Row-level security for the junction table. **Required**: the subquery reads
+     * the junction table directly, so without this a tenant sees every tenant's
+     * attribute values. It is a parameter rather than an option so that omitting
+     * it is impossible rather than merely inadvisable.
+     */
+    security: (ctx: QueryContext) => SQL;
+    /**
+     * Per-attribute type overrides, keyed by attribute id. Wins over
+     * `AttributeDefinition.valueType`.
+     */
+    types?: Record<string, AttributeValueType>;
+    /** Member-name prefix. Defaults to `attr_`. */
+    namePrefix?: string;
+    /** Passed through to each generated dimension's `shown`. */
+    shown?: boolean;
+}
+/**
+ * Build one dimension per attribute, each backed by a correlated scalar
+ * subquery against the junction table.
+ *
+ * ```ts
+ * dimensions: {
+ *   ...baseDimensions,
+ *   ...buildAttributeDimensions({
+ *     attributes: attrs,
+ *     valueTable: employeeAttributeValues,
+ *     recordKey: employees.id,
+ *     foreignKey: employeeAttributeValues.employeeId,
+ *     attributeKey: employeeAttributeValues.attributeId,
+ *     valueColumn: employeeAttributeValues.value,
+ *     security: (ctx) => eq(employeeAttributeValues.organisationId, ctx.securityContext.organisationId)
+ *   })
+ * }
+ * ```
+ *
+ * Three details that are easy to get wrong, and are handled here:
+ *
+ * - **Typing is mandatory, not cosmetic.** Sorting and filtering run in SQL
+ *   over the whole table before a page reaches the browser, so client-side
+ *   conversion cannot repair them: sorted as text, `100` sorts below `9`, and
+ *   `> 50` admits `'9'` while rejecting `'100'`. A `number` attribute is cast
+ *   in SQL — tolerantly, so one `n/a` yields NULL for that row instead of
+ *   failing the whole query.
+ * - **`LIMIT 1`.** EAV tables rarely carry a unique constraint on
+ *   (record, attribute); without it a duplicate row raises "more than one row
+ *   returned by a subquery" on Postgres.
+ * - **Security inside the subquery**, not merely on the outer query.
+ *
+ * **Grouping limitation.** The subquery correlates on the record key, so a
+ * *grouped* query must also group by that key — `dimensions: ['Employees.id',
+ * 'Employees.attr_1']` is fine, `dimensions: ['Employees.attr_1']` with a
+ * measure is not. Postgres rejects the latter with "subquery uses ungrouped
+ * column … from outer query", and MySQL with `only_full_group_by`; SQLite
+ * permits it. Record-grain listings (`ungrouped: true`) — the case this exists
+ * for — are unaffected. If you need to aggregate freely by an attribute, pivot
+ * it into a real column with a view (see the performance ladder below).
+ *
+ * Performance: projection is cheap (a page of 25 rows is 25 indexed lookups per
+ * attribute), but `ORDER BY (SELECT …)` and `WHERE (SELECT …) = …` are
+ * proportional to the base table because no index serves them. At tens of
+ * thousands of rows that is fine; beyond it, pivot the attributes into real
+ * indexable columns via a view.
+ */
+export declare function buildAttributeDimensions(options: BuildAttributeDimensionsOptions): Record<string, Dimension>;

package/dist/server/cache-utils.d.ts

@@ -24,9 +24,13 @@ export interface CacheKeyConfig {
  * @param query - The semantic query to cache
  * @param securityContext - Security context for tenant isolation
  * @param config - Cache key configuration
+ * @param cubeSetKey - Identifies the cube definitions behind the result. Always
+ *   included when present: `includeSecurityContext: false` and a custom
+ *   `securityContextSerializer` can each hash two tenants identically, so the
+ *   security-context hash alone cannot keep differing cube sets apart.
  * @returns Deterministic cache key string
  */
-export declare function generateCacheKey(query: SemanticQuery, securityContext: SecurityContext, config?: CacheKeyConfig): string;
+export declare function generateCacheKey(query: SemanticQuery, securityContext: SecurityContext, config?: CacheKeyConfig, cubeSetKey?: string): string;
 /**
  * Normalize query for consistent hashing
  * Sorts arrays and object keys to ensure same query = same hash

package/dist/server/compiler-metadata.d.ts

@@ -1,11 +1,32 @@
 import { Cube, MeasureMetadata, DimensionMetadata, CubeRelationshipMetadata, HierarchyMetadata, TimeGranularity } from './types/index.js';
 /** Default time granularities used when a time dimension omits `granularities`. */
 export declare const DEFAULT_TIME_GRANULARITIES: TimeGranularity[];
-/** Build measure metadata, normalizing drillMembers to fully-qualified names. */
+/**
+ * Build measure metadata, normalizing drillMembers to fully-qualified names.
+ *
+ * Measures with `shown: false` are omitted from the result — matching Cube.js
+ * semantics, where a hidden measure remains fully usable in queries but is
+ * excluded from metadata/UI surfaces. `shown: undefined` means shown, so
+ * today's behaviour is preserved exactly.
+ */
 export declare function buildMeasureMetadata(cube: Cube): MeasureMetadata[];
-/** Build dimension metadata, including granularities for time dimensions. */
+/**
+ * Build dimension metadata, including granularities for time dimensions.
+ *
+ * Dimensions with `shown: false` are omitted from the result — matching
+ * Cube.js semantics, where a hidden dimension remains fully usable in queries
+ * but is excluded from metadata/UI surfaces. `shown: undefined` means shown,
+ * so today's behaviour is preserved exactly.
+ */
 export declare function buildDimensionMetadata(cube: Cube): DimensionMetadata[];
 /** Build relationship metadata from a cube's joins, resolving target cubes. */
 export declare function buildRelationshipMetadata(cube: Cube, cubes: Map<string, Cube>, getColumnName: (column: any) => string): CubeRelationshipMetadata[];
-/** Build hierarchy metadata, qualifying level names to full member names. */
+/**
+ * Build hierarchy metadata, qualifying level names to full member names.
+ *
+ * Levels referencing a dimension with `shown: false` are dropped, so a
+ * hierarchy never emits a dangling reference to a dimension that has been
+ * omitted from the cube's own dimension metadata. A hierarchy left with no
+ * visible levels is omitted entirely rather than published as empty.
+ */
 export declare function buildHierarchyMetadata(cube: Cube): HierarchyMetadata[];

package/dist/server/compiler.d.ts

@@ -1,9 +1,70 @@
 import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types/index.js';
 import { PlanOptimiser } from './logical-plan/index.js';
 export { validateQueryAgainstCubes } from './query-validator.js';
+/**
+ * Identifier of the base cube set — the cubes registered with {@link
+ * SemanticLayerCompiler.registerCube}, shared by every tenant. The empty string
+ * is used so a set id can never collide with it (`registerCubeSet` rejects it).
+ */
+export declare const BASE_CUBE_SET_ID = "";
+/**
+ * Security context for deployments with no tenancy at all.
+ *
+ * Every cube-resolving method requires a `SecurityContext` so that omitting one
+ * is a compile error rather than a silent fall back to the wrong tenant's
+ * cubes. Single-tenant callers pass this constant to say "no tenancy here" out
+ * loud, instead of an anonymous `{}` that reads like an oversight.
+ */
+export declare const SINGLE_TENANT_CONTEXT: SecurityContext;
+/** Reported to `onCubeSetRegistered` after each {@link SemanticLayerCompiler.registerCubeSet}. */
+export interface CubeSetRegistrationInfo {
+    /** The set that was registered. */
+    setId: string;
+    /** Cubes in the set after merging over the base set. */
+    cubeCount: number;
+    /** Total dimensions across those cubes — the number that explains a slow boot. */
+    dimensionCount: number;
+    /**
+     * Monotonic across the whole compiler — incremented on every registration of
+     * any set, never reset. Part of the cache key, so results computed from
+     * superseded definitions can never be served.
+     */
+    generation: number;
+    /** Wall-clock cost of this registration. */
+    durationMs: number;
+}
+/** Aggregate registration cost, for a single summary line after the boot loop. */
+export interface CubeSetStats {
+    /** Number of registered sets, excluding the base set. */
+    setCount: number;
+    /** Total cubes across all sets (merged), excluding the base set. */
+    cubeCount: number;
+    /** Sum of every set's most recent registration time. */
+    totalRegistrationMs: number;
+    /** The most expensive set to register, if any sets are registered. */
+    slowestSet?: {
+        setId: string;
+        durationMs: number;
+    };
+}
 export declare class SemanticLayerCompiler {
-    private cubes;
-    private metadataCache?;
+    /** Cubes shared by every tenant. */
+    private baseCubes;
+    /** Per-tenant overlays, keyed by cube-set id. */
+    private cubeSets;
+    /** Generated metadata per cube set (`BASE_CUBE_SET_ID` for the base set). */
+    private metadataCache;
+    /** Bumped on every base-set mutation; part of every set's cache key. */
+    private baseGeneration;
+    /**
+     * Monotonic registration counter, never reset. Used as each set's generation
+     * so that unregistering a set and registering a different one under the same
+     * id cannot reproduce an earlier cache key and serve its stale results.
+     */
+    private registrationCounter;
+    private contextToCubeSetId?;
+    private missingCubeSet;
+    private onCubeSetRegistered?;
     private cacheConfig?;
     private rlsSetup?;
     private planOptimiser?;
@@ -29,6 +90,25 @@ export declare class SemanticLayerCompiler {
          * Defaults to a no-op IdentityOptimiser when omitted.
          */
         planOptimiser?: PlanOptimiser;
+        /**
+         * Maps a security context to the cube set that serves it — drizzle-cube's
+         * equivalent of Cube's `contextToAppId`. Return `undefined` (or omit this
+         * option entirely) to serve the base set, which is the single-tenant
+         * behaviour and the default.
+         */
+        contextToCubeSetId?: (securityContext: SecurityContext) => string | number | undefined;
+        /**
+         * What to do when `contextToCubeSetId` names a set that is not registered.
+         * `'base'` (default) serves the base set; `'throw'` fails the request, for
+         * deployments where every tenant is required to have its own set.
+         */
+        missingCubeSet?: 'base' | 'throw';
+        /**
+         * Called after each `registerCubeSet` with its cost. Registering a set per
+         * tenant is real startup work, so it is reported rather than hidden; emit
+         * it to your own logger or metrics.
+         */
+        onCubeSetRegistered?: (info: CubeSetRegistrationInfo) => void;
     });
     /**
      * Set or update the database connection
@@ -65,12 +145,75 @@ export declare class SemanticLayerCompiler {
      * Validates calculated measures during registration
      */
     registerCube(cube: Cube): void;
+    /**
+     * Register the cubes that serve one tenant, overlaying the base set.
+     *
+     * Cubes are matched to the base set by name, so a set can either add cubes or
+     * replace a base cube with a tenant-specific version (the usual case for
+     * generated per-tenant dimensions). Call once per tenant at application boot;
+     * calling again for the same id replaces that set and invalidates its cached
+     * metadata and query results.
+     */
+    registerCubeSet(setId: string, cubes: Cube[]): void;
+    /**
+     * Remove a tenant's cube set. That tenant then resolves to the base set (or
+     * throws, under `missingCubeSet: 'throw'`).
+     * Returns true if the set existed.
+     */
+    unregisterCubeSet(setId: string): boolean;
+    /** Whether a cube set is registered for this id. */
+    hasCubeSet(setId: string): boolean;
+    /** Ids of every registered cube set, excluding the base set. */
+    getCubeSetIds(): string[];
+    /**
+     * Aggregate registration cost across all sets — for the single summary line
+     * worth logging after a boot loop.
+     */
+    getCubeSetStats(): CubeSetStats;
+    /**
+     * Validate and enrich a cube ahead of registration, against the cubes that
+     * will be visible alongside it.
+     */
+    private prepareCube;
+    /** Base cubes with an overlay applied over them, by cube name. */
+    private mergeWithBase;
+    /** Recompute every set's merged view — after any base-set mutation. */
+    private rebuildAllMergedSets;
+    /**
+     * Resolve the cube set serving this security context.
+     *
+     * Returns {@link BASE_CUBE_SET_ID} when no mapping is configured or the
+     * mapping yields nothing. A configured id that has no registered set falls
+     * back to the base set, or throws under `missingCubeSet: 'throw'`.
+     */
+    private resolveSetId;
+    /**
+     * The cubes this security context may see.
+     *
+     * This is the only path by which cube *contents* are read for a query,
+     * metadata, validation or MCP response — so no such path can reach a cube
+     * list without a security context. The returned map must be treated as
+     * read-only; it is the live merged view, not a copy.
+     */
+    private resolveCubes;
+    /**
+     * Cache-key component identifying which cube definitions produced a result.
+     *
+     * Appended unconditionally to every query cache key: the security-context
+     * hash is not enough, because `includeSecurityContext: false` and a custom
+     * `securityContextSerializer` can both hash two tenants identically. The
+     * generation makes re-registering a set invalidate its cached results, so a
+     * retyped or renamed dimension cannot be served stale for the TTL.
+     */
+    private cubeSetCacheKey;
     /**
      * Validate that all string-based cube references in joins resolve to registered cubes.
      * Call after all cubes are registered for strict startup validation.
      * Throws an error listing all unresolved references.
      */
     validateCubeReferences(): void;
+    /** Join targets naming a cube that is absent from the given cube scope. */
+    private unresolvedJoinRefs;
     /**
      * Validate calculated measures in a cube
      * Checks template syntax, dependency existence, and circular dependencies
@@ -79,15 +222,17 @@ export declare class SemanticLayerCompiler {
     /**
      * Get a cube by name
      */
-    getCube(name: string): Cube | undefined;
+    getCube(name: string, securityContext: SecurityContext): Cube | undefined;
     /**
      * Get all registered cubes
      */
-    getAllCubes(): Cube[];
+    getAllCubes(securityContext: SecurityContext): Cube[];
     /**
-     * Get all cubes as a Map for multi-cube queries
+     * Get all cubes as a Map for multi-cube queries.
+     *
+     * Returns the live merged view for this context — treat it as read-only.
      */
-    getAllCubesMap(): Map<string, Cube>;
+    getAllCubesMap(securityContext: SecurityContext): Map<string, Cube>;
     /**
      * Unified query execution method that handles both single and multi-cube queries
      * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
@@ -107,7 +252,7 @@ export declare class SemanticLayerCompiler {
      * Uses caching to improve performance for repeated requests
      * Cache is invalidated when cubes are modified (registerCube, removeCube, clearCubes)
      */
-    getMetadata(): CubeMetadata[];
+    getMetadata(securityContext: SecurityContext): CubeMetadata[];
     /**
      * Extract column name from Drizzle column reference
      * Handles different column types and extracts the actual column name
@@ -172,7 +317,7 @@ export declare class SemanticLayerCompiler {
     /**
      * Check if a cube exists
      */
-    hasCube(name: string): boolean;
+    hasCube(name: string, securityContext: SecurityContext): boolean;
     /**
      * Unregister a cube by name.
      * Returns true if the cube existed and was removed, false if not found.
@@ -191,15 +336,17 @@ export declare class SemanticLayerCompiler {
      * Called whenever cubes are modified
      */
     private invalidateMetadataCache;
+    /** Cubes for an already-resolved set id. */
+    private cubeSetId2Cubes;
     /**
      * Get cube names
      */
-    getCubeNames(): string[];
+    getCubeNames(securityContext: SecurityContext): string[];
     /**
      * Validate a query against registered cubes
      * Ensures all referenced cubes and fields exist
      */
-    validateQuery(query: SemanticQuery): {
+    validateQuery(query: SemanticQuery, securityContext: SecurityContext): {
         isValid: boolean;
         errors: string[];
     };

package/dist/server/execution/query-result-cache.d.ts

@@ -6,7 +6,7 @@ export declare class QueryResultCache {
      * Returns the cache key when caching is enabled and a provider is configured,
      * otherwise undefined (which disables lookup and store).
      */
-    generateKey(query: SemanticQuery, securityContext: SecurityContext): string | undefined;
+    generateKey(query: SemanticQuery, securityContext: SecurityContext, cubeSetKey?: string): string | undefined;
     /**
      * Look up a cached result. Returns the cached value (with cache metadata
      * attached) on a hit, or undefined on miss / bypass / no-cache. Emits