@objectstack/service-analytics 7.8.0 → 8.0.0

package/dist/index.js

@@ -202,6 +202,115 @@ function coerceFilterValueForSql(s) {
   return s;
 }
 
+// src/read-scope-sql.ts
+var IDENT = /^[a-z_][a-z0-9_]*$/i;
+function quoteIdent(name, kind) {
+  if (typeof name !== "string" || !IDENT.test(name)) {
+    throw new Error(`[read-scope-sql] unsafe ${kind} identifier "${String(name)}" \u2014 refusing to build read scope (fail-closed).`);
+  }
+  return `"${name}"`;
+}
+function compileScopedFilterToSql(filter, alias) {
+  const quotedAlias = quoteIdent(alias, "alias");
+  const params = [];
+  const sql = compileNode(filter, quotedAlias, params);
+  return { sql, params };
+}
+function compileNode(node, qAlias, params) {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) {
+    throw new Error("[read-scope-sql] read scope must be a filter object (fail-closed).");
+  }
+  const clauses = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "$and" || key === "$or") {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`[read-scope-sql] "${key}" requires a non-empty array (fail-closed).`);
+      }
+      const parts = value.map((child) => compileNode(child, qAlias, params)).filter((s) => s.length > 0);
+      if (parts.length === 0) continue;
+      const joiner = key === "$and" ? " AND " : " OR ";
+      clauses.push(`(${parts.join(joiner)})`);
+    } else if (key === "$not") {
+      const inner = compileNode(value, qAlias, params);
+      if (inner) clauses.push(`NOT (${inner})`);
+    } else if (key.startsWith("$")) {
+      throw new Error(`[read-scope-sql] unsupported top-level operator "${key}" (fail-closed).`);
+    } else {
+      clauses.push(compileField(key, value, qAlias, params));
+    }
+  }
+  return clauses.join(" AND ");
+}
+function compileField(field, value, qAlias, params) {
+  const col = `${qAlias}.${quoteIdent(field, "field")}`;
+  if (value === null) return `${col} IS NULL`;
+  if (typeof value !== "object" || value instanceof Date) {
+    params.push(value);
+    return `${col} = ?`;
+  }
+  if (Array.isArray(value)) {
+    throw new Error(`[read-scope-sql] bare array value for "${field}" \u2014 use { $in: [...] } (fail-closed).`);
+  }
+  const ops = value;
+  const keys = Object.keys(ops);
+  if (keys.length === 0 || keys.some((k) => !k.startsWith("$"))) {
+    throw new Error(`[read-scope-sql] "${field}" has a nested/relation value which is not supported in a read scope (fail-closed).`);
+  }
+  const parts = [];
+  for (const op of keys) {
+    parts.push(compileOperator(col, op, ops[op], field, params));
+  }
+  return parts.length === 1 ? parts[0] : `(${parts.join(" AND ")})`;
+}
+function bind(params, v) {
+  params.push(v);
+  return "?";
+}
+function compileOperator(col, op, val, field, params) {
+  switch (op) {
+    case "$eq":
+      return val === null ? `${col} IS NULL` : `${col} = ${bind(params, val)}`;
+    case "$ne":
+      return val === null ? `${col} IS NOT NULL` : `${col} <> ${bind(params, val)}`;
+    case "$gt":
+      return `${col} > ${bind(params, val)}`;
+    case "$gte":
+      return `${col} >= ${bind(params, val)}`;
+    case "$lt":
+      return `${col} < ${bind(params, val)}`;
+    case "$lte":
+      return `${col} <= ${bind(params, val)}`;
+    case "$in": {
+      if (!Array.isArray(val)) throw new Error(`[read-scope-sql] $in for "${field}" needs an array (fail-closed).`);
+      if (val.length === 0) return "1 = 0";
+      return `${col} IN (${val.map((v) => bind(params, v)).join(", ")})`;
+    }
+    case "$nin": {
+      if (!Array.isArray(val)) throw new Error(`[read-scope-sql] $nin for "${field}" needs an array (fail-closed).`);
+      if (val.length === 0) return "1 = 1";
+      return `${col} NOT IN (${val.map((v) => bind(params, v)).join(", ")})`;
+    }
+    case "$between": {
+      if (!Array.isArray(val) || val.length !== 2) throw new Error(`[read-scope-sql] $between for "${field}" needs [min,max] (fail-closed).`);
+      return `${col} BETWEEN ${bind(params, val[0])} AND ${bind(params, val[1])}`;
+    }
+    case "$contains":
+      return `${col} LIKE ${bind(params, `%${String(val)}%`)}`;
+    case "$notContains":
+      return `${col} NOT LIKE ${bind(params, `%${String(val)}%`)}`;
+    case "$startsWith":
+      return `${col} LIKE ${bind(params, `${String(val)}%`)}`;
+    case "$endsWith":
+      return `${col} LIKE ${bind(params, `%${String(val)}`)}`;
+    case "$null":
+      return val ? `${col} IS NULL` : `${col} IS NOT NULL`;
+    case "$exists":
+      return val ? `${col} IS NOT NULL` : `${col} IS NULL`;
+    default:
+      throw new Error(`[read-scope-sql] unsupported operator "${op}" on "${field}" (fail-closed).`);
+  }
+}
+
 // src/strategies/native-sql-strategy.ts
 var NativeSQLStrategy = class {
   constructor() {
@@ -265,6 +374,21 @@ var NativeSQLStrategy = class {
         }
       }
     }
+    const allowed = ctx.getAllowedRelationships?.(query.cube);
+    if (allowed) {
+      for (const alias of joins.keys()) {
+        if (!allowed.has(alias)) {
+          throw new Error(
+            `[NativeSQLStrategy] join "${alias}" is not backed by a declared relationship on cube "${query.cube}". v1 only joins along relationships listed in the dataset's \`include\`.`
+          );
+        }
+      }
+    }
+    this.applyReadScope(this.extractObjectName(cube), tableName, ctx, whereClauses, params);
+    for (const alias of joins.keys()) {
+      const joinedObject = cube.joins?.[alias]?.name ?? alias;
+      this.applyReadScope(joinedObject, alias, ctx, whereClauses, params);
+    }
     let sql = `SELECT ${selectClauses.join(", ")} FROM "${tableName}"`;
     if (joins.size > 0) {
       sql += " " + Array.from(joins.values()).join(" ");
@@ -288,6 +412,28 @@ var NativeSQLStrategy = class {
     return { sql, params };
   }
   // ── Helpers ──────────────────────────────────────────────────────
+  /**
+   * ADR-0021 D-C — inject an object's read scope (tenant + RLS predicate) into
+   * the WHERE clause. The scope is a canonical `FilterCondition` (what the
+   * RLSCompiler emits); `compileScopedFilterToSql` turns it into alias-qualified,
+   * parameterized SQL (fail-closed — it throws rather than drop a predicate).
+   * The `?` placeholders are then renumbered into the strategy's `$N` scheme.
+   * No-op when the runtime provides no scope hook (the caller is then
+   * responsible for isolation — see contract note).
+   */
+  applyReadScope(objectName, alias, ctx, whereClauses, params) {
+    if (typeof ctx.getReadScope !== "function") return;
+    const filter = ctx.getReadScope(objectName);
+    if (filter === void 0 || filter === null) return;
+    const { sql, params: scopeParams } = compileScopedFilterToSql(filter, alias);
+    if (!sql) return;
+    let i = 0;
+    const rendered = sql.replace(/\?/g, () => {
+      params.push(scopeParams[i++]);
+      return `$${params.length}`;
+    });
+    whereClauses.push(`(${rendered})`);
+  }
   /**
    * Resolve a dimension/measure/filter SQL expression that may reference a
    * related table via dot notation (e.g. `account.industry`).
@@ -306,15 +452,17 @@ var NativeSQLStrategy = class {
    * Returns the qualified SQL reference (e.g. `"account"."industry"`).
    * Pure column references (no dot) are returned as-is.
    */
-  qualifyAndRegisterJoin(rawSql, parentTable, joins) {
+  qualifyAndRegisterJoin(rawSql, parentTable, joins, cube) {
     if (!rawSql.includes(".")) return rawSql;
     const [alias, ...rest] = rawSql.split(".");
     if (!alias || rest.length === 0) return rawSql;
     const column = rest.join(".");
     if (!joins.has(alias)) {
+      const joinTable = cube?.joins?.[alias]?.name ?? alias;
+      const tableRef = joinTable === alias ? `"${alias}"` : `"${joinTable}" "${alias}"`;
       joins.set(
         alias,
-        `LEFT JOIN "${alias}" ON "${parentTable}"."${alias}" = "${alias}"."id"`
+        `LEFT JOIN ${tableRef} ON "${parentTable}"."${alias}" = "${alias}"."id"`
       );
     }
     return `"${alias}"."${column}"`;
@@ -353,12 +501,12 @@ var NativeSQLStrategy = class {
   resolveDimensionSql(cube, member, parentTable, joins) {
     const dim = this.lookupMember(cube, member, "dimension");
     const raw = dim ? dim.sql : member.includes(".") ? member.split(".")[1] : member;
-    return this.qualifyAndRegisterJoin(raw, parentTable, joins);
+    return this.qualifyAndRegisterJoin(raw, parentTable, joins, cube);
   }
   resolveMeasureSql(cube, member, parentTable, joins) {
     const measure = this.lookupMember(cube, member, "measure");
     if (!measure) return `COUNT(*)`;
-    const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins);
+    const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins, cube);
     switch (measure.type) {
       case "count":
         return "COUNT(*)";
@@ -378,9 +526,9 @@ var NativeSQLStrategy = class {
   }
   resolveFieldSql(cube, member, parentTable, joins) {
     const dim = this.lookupMember(cube, member, "dimension");
-    if (dim) return this.qualifyAndRegisterJoin(dim.sql, parentTable, joins);
+    if (dim) return this.qualifyAndRegisterJoin(dim.sql, parentTable, joins, cube);
     const measure = this.lookupMember(cube, member, "measure");
-    if (measure) return this.qualifyAndRegisterJoin(measure.sql, parentTable, joins);
+    if (measure) return this.qualifyAndRegisterJoin(measure.sql, parentTable, joins, cube);
     const fieldName = member.includes(".") ? member.split(".")[1] : member;
     return fieldName;
   }
@@ -634,6 +782,309 @@ var ObjectQLStrategy = class {
   }
 };
 
+// src/dataset-compiler.ts
+var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set(["array_agg", "string_agg"]);
+function aggregateToMetricType(m) {
+  if (UNSUPPORTED_AGGREGATES.has(m.aggregate)) {
+    throw new Error(
+      `[dataset-compiler] measure "${m.name}" uses aggregate "${m.aggregate}" which is not supported by the v1 dataset runtime (supported: count, sum, avg, min, max, count_distinct).`
+    );
+  }
+  return m.aggregate;
+}
+function dimensionType(d) {
+  switch (d.type) {
+    case "date":
+      return "time";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "lookup":
+      return "string";
+    case "string":
+      return "string";
+    default:
+      return "string";
+  }
+}
+function relationshipPrefix(field) {
+  const idx = field.indexOf(".");
+  return idx > 0 ? field.slice(0, idx) : null;
+}
+function compileDataset(dataset, resolver) {
+  const include = dataset.include ?? [];
+  const allowedRelationships = new Set(include);
+  const joins = {};
+  for (const rel of include) {
+    let targetTable = rel;
+    if (resolver) {
+      const resolved = resolver(dataset.object, rel);
+      if (!resolved) {
+        throw new Error(
+          `[dataset-compiler] dataset "${dataset.name}" includes relationship "${rel}" which does not exist on object "${dataset.object}".`
+        );
+      }
+      targetTable = resolved;
+    }
+    joins[rel] = {
+      name: targetTable,
+      relationship: "many_to_one",
+      sql: `${dataset.object}.${rel} = ${rel}.id`
+    };
+  }
+  const assertDeclared = (field, ownerKind, ownerName) => {
+    const prefix = relationshipPrefix(field);
+    if (prefix && !allowedRelationships.has(prefix)) {
+      throw new Error(
+        `[dataset-compiler] ${ownerKind} "${ownerName}" references relationship "${prefix}" via "${field}", but "${prefix}" is not declared in the dataset's \`include\`. v1 only joins along declared relationships.`
+      );
+    }
+  };
+  const dimensions = {};
+  for (const d of dataset.dimensions) {
+    assertDeclared(d.field, "dimension", d.name);
+    const dim = {
+      name: d.name,
+      label: typeof d.label === "string" ? d.label : d.name,
+      type: dimensionType(d),
+      sql: d.field
+    };
+    if (dim.type === "time") {
+      dim.granularities = d.dateGranularity ? [d.dateGranularity] : ["day", "week", "month", "quarter", "year"];
+    }
+    dimensions[d.name] = dim;
+  }
+  const measures = {};
+  const derived = [];
+  const measureFilters = {};
+  for (const m of dataset.measures) {
+    if (m.derived) {
+      derived.push({ name: m.name, op: m.derived.op, of: m.derived.of });
+      continue;
+    }
+    if (m.field) assertDeclared(m.field, "measure", m.name);
+    const metric = {
+      name: m.name,
+      label: typeof m.label === "string" ? m.label : m.name,
+      type: aggregateToMetricType(m),
+      // `count` with no field aggregates over rows (*).
+      sql: m.field ?? "*"
+    };
+    if (typeof m.format === "string") metric.format = m.format;
+    measures[m.name] = metric;
+    if (m.filter) measureFilters[m.name] = m.filter;
+  }
+  const cube = {
+    name: dataset.name,
+    title: typeof dataset.label === "string" ? dataset.label : dataset.name,
+    sql: dataset.object,
+    measures,
+    dimensions,
+    public: false
+  };
+  if (Object.keys(joins).length > 0) cube.joins = joins;
+  return {
+    cube,
+    allowedRelationships,
+    derived,
+    filter: dataset.filter,
+    measureFilters
+  };
+}
+
+// src/dataset-executor.ts
+function combineFilters(a, b) {
+  if (a && b) return { $and: [a, b] };
+  return a ?? b;
+}
+function evaluateDerivedMeasures(rows, derived) {
+  if (derived.length === 0) return rows;
+  return rows.map((row) => {
+    const out = { ...row };
+    for (const d of derived) {
+      out[d.name] = computeDerived(d, out);
+    }
+    return out;
+  });
+}
+function num(v) {
+  if (v == null) return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+function computeDerived(d, row) {
+  const vals = d.of.map((name) => num(row[name]));
+  if (vals.some((v) => v === null)) return null;
+  const nums = vals;
+  switch (d.op) {
+    case "ratio": {
+      if (nums.length < 2 || nums[1] === 0) return null;
+      return nums[0] / nums[1];
+    }
+    case "difference":
+      return nums.slice(1).reduce((acc, v) => acc - v, nums[0]);
+    case "sum":
+      return nums.reduce((acc, v) => acc + v, 0);
+    case "product":
+      return nums.reduce((acc, v) => acc * v, 1);
+    default:
+      return null;
+  }
+}
+function parseUTC(date) {
+  const ms = Date.parse(date.length === 10 ? `${date}T00:00:00Z` : date);
+  if (Number.isNaN(ms)) throw new Error(`[dataset-executor] invalid date in dateRange: "${date}"`);
+  return ms;
+}
+var DAY_MS = 864e5;
+function toISODate(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+function shiftYear(date, years) {
+  const d = new Date(parseUTC(date));
+  d.setUTCFullYear(d.getUTCFullYear() + years);
+  return toISODate(d.getTime());
+}
+function shiftRange(range, kind) {
+  const [start, end] = range;
+  if (kind === "previousYear") {
+    return [shiftYear(start, -1), shiftYear(end, -1)];
+  }
+  const startMs = parseUTC(start);
+  const endMs = parseUTC(end);
+  const lengthDays = Math.round((endMs - startMs) / DAY_MS) + 1;
+  const prevEndMs = startMs - DAY_MS;
+  const prevStartMs = prevEndMs - (lengthDays - 1) * DAY_MS;
+  return [toISODate(prevStartMs), toISODate(prevEndMs)];
+}
+var DatasetExecutor = class {
+  constructor(service) {
+    this.service = service;
+  }
+  /**
+   * Execute a dataset selection and return the shaped rows (+ field metadata).
+   *
+   * @param context - The request's ExecutionContext, threaded into every
+   *   underlying `IAnalyticsService.query` so the tenant/RLS read scope is
+   *   applied per request (ADR-0021 D-C).
+   */
+  async execute(compiled, selection, context) {
+    const derivedByName = new Map(compiled.derived.map((d) => [d.name, d]));
+    const selectedDerived = selection.measures.map((m) => derivedByName.get(m)).filter((d) => !!d);
+    const baseMeasures = /* @__PURE__ */ new Set();
+    for (const m of selection.measures) {
+      if (!derivedByName.has(m)) baseMeasures.add(m);
+    }
+    for (const d of selectedDerived) {
+      for (const dep of d.of) baseMeasures.add(dep);
+    }
+    const unfiltered = [];
+    const filtered = [];
+    for (const m of baseMeasures) {
+      (compiled.measureFilters[m] ? filtered : unfiltered).push(m);
+    }
+    const baseFilter = combineFilters(compiled.filter, selection.runtimeFilter);
+    const dimensions = selection.dimensions ?? [];
+    let result;
+    if (unfiltered.length > 0 || filtered.length === 0) {
+      result = await this.service.query(this.buildQuery(compiled, {
+        measures: unfiltered,
+        dimensions,
+        where: baseFilter,
+        selection
+      }), context);
+    } else {
+      result = { rows: [], fields: [] };
+    }
+    for (const m of filtered) {
+      const mFilter = combineFilters(baseFilter, compiled.measureFilters[m]);
+      const sub = await this.service.query(this.buildQuery(compiled, {
+        measures: [m],
+        dimensions,
+        where: mFilter,
+        selection
+      }), context);
+      result.rows = mergeByDimensions(result.rows, sub.rows, dimensions, [m]);
+      result.fields.push({ name: m, type: "number" });
+    }
+    if (selection.compareTo) {
+      const compareRows = await this.runCompare(compiled, selection, [...baseMeasures], dimensions, baseFilter, context);
+      result.rows = mergeByDimensions(
+        result.rows,
+        compareRows,
+        dimensions,
+        [...baseMeasures].map((m) => `${m}__compare`)
+      );
+      for (const m of baseMeasures) result.fields.push({ name: `${m}__compare`, type: "number" });
+    }
+    result.rows = evaluateDerivedMeasures(result.rows, selectedDerived);
+    for (const d of selectedDerived) result.fields.push({ name: d.name, type: "number" });
+    return result;
+  }
+  buildQuery(compiled, opts) {
+    const q = {
+      cube: compiled.cube.name,
+      measures: opts.measures,
+      dimensions: opts.dimensions,
+      timezone: opts.selection.timezone ?? "UTC"
+    };
+    if (opts.where) q.where = opts.where;
+    if (opts.selection.timeDimensions) q.timeDimensions = opts.selection.timeDimensions;
+    if (opts.selection.order) q.order = opts.selection.order;
+    if (opts.selection.limit != null) q.limit = opts.selection.limit;
+    if (opts.selection.offset != null) q.offset = opts.selection.offset;
+    return q;
+  }
+  async runCompare(compiled, selection, measures, dimensions, baseFilter, context) {
+    const cmp = selection.compareTo;
+    const td = (selection.timeDimensions ?? []).find((t) => t.dimension === cmp.dimension);
+    if (!td || !td.dateRange) {
+      throw new Error(
+        `[dataset-executor] compareTo requires a timeDimension "${cmp.dimension}" with a dateRange.`
+      );
+    }
+    const range = Array.isArray(td.dateRange) ? [td.dateRange[0], td.dateRange[1] ?? td.dateRange[0]] : [td.dateRange, td.dateRange];
+    const shifted = shiftRange(range, cmp.kind);
+    const shiftedTd = (selection.timeDimensions ?? []).map(
+      (t) => t.dimension === cmp.dimension ? { ...t, dateRange: shifted } : t
+    );
+    const sub = await this.service.query({
+      cube: compiled.cube.name,
+      measures,
+      dimensions,
+      where: baseFilter,
+      timeDimensions: shiftedTd,
+      timezone: selection.timezone ?? "UTC"
+    }, context);
+    return sub.rows.map((row) => {
+      const out = {};
+      for (const dim of dimensions) out[dim] = row[dim];
+      for (const m of measures) out[`${m}__compare`] = row[m];
+      return out;
+    });
+  }
+};
+function mergeByDimensions(base, extra, dimensions, valueColumns) {
+  const keyOf = (row) => dimensions.map((d) => String(row[d] ?? "")).join("
");
+  const index = /* @__PURE__ */ new Map();
+  for (const row of base) index.set(keyOf(row), row);
+  for (const row of extra) {
+    const key = keyOf(row);
+    const target = index.get(key);
+    if (target) {
+      for (const c of valueColumns) target[c] = row[c];
+    } else {
+      const fresh = {};
+      for (const d of dimensions) fresh[d] = row[d];
+      for (const c of valueColumns) fresh[c] = row[c];
+      index.set(key, fresh);
+      base.push(fresh);
+    }
+  }
+  return base;
+}
+
 // src/analytics-service.ts
 var DEFAULT_CAPABILITIES = {
   nativeSql: false,
@@ -642,17 +1093,33 @@ var DEFAULT_CAPABILITIES = {
 };
 var AnalyticsService = class {
   constructor(config = {}) {
+    /** Compiled datasets by name — feeds the join allowlist (D-C) and queryDataset. */
+    this.datasetRegistry = /* @__PURE__ */ new Map();
     this.logger = config.logger || createLogger({ level: "info", format: "pretty" });
     this.cubeRegistry = new CubeRegistry();
     if (config.cubes) {
       this.cubeRegistry.registerAll(config.cubes);
     }
-    this.strategyCtx = {
+    this.readScopeProvider = config.getReadScope;
+    this.relationshipResolver = config.relationshipResolver;
+    if (config.datasets) {
+      for (const ds of config.datasets) {
+        try {
+          this.registerDataset(ds);
+        } catch (e) {
+          this.logger?.warn?.(`[Analytics] Failed to register dataset "${ds?.name}": ${String(e?.message ?? e)}`);
+        }
+      }
+    }
+    this.baseCtx = {
       getCube: (name) => this.cubeRegistry.get(name),
       queryCapabilities: config.queryCapabilities || (() => DEFAULT_CAPABILITIES),
       executeRawSql: config.executeRawSql,
       executeAggregate: config.executeAggregate,
-      fallbackService: config.fallbackService
+      fallbackService: config.fallbackService,
+      // Prefer a compiled dataset's declared relationships (D-C join allowlist);
+      // fall back to any explicitly-configured provider for legacy cubes.
+      getAllowedRelationships: (cubeName) => this.datasetRegistry.get(cubeName)?.allowedRelationships ?? config.getAllowedRelationships?.(cubeName)
     };
     const builtIn = [
       new NativeSQLStrategy(),
@@ -667,17 +1134,52 @@ var AnalyticsService = class {
       `[Analytics] Initialized with ${this.cubeRegistry.size} cubes, ${this.strategies.length} strategies: ${this.strategies.map((s) => s.name).join(" \u2192 ")}`
     );
   }
+  /**
+   * Build a per-call StrategyContext that binds the read-scope provider to the
+   * current request's ExecutionContext (ADR-0021 D-C). The strategy then sees a
+   * `getReadScope(objectName)` that already knows the active tenant.
+   */
+  callCtx(context) {
+    if (!this.readScopeProvider) return this.baseCtx;
+    return {
+      ...this.baseCtx,
+      getReadScope: (objectName) => this.readScopeProvider(objectName, context)
+    };
+  }
   /**
    * Execute an analytical query by delegating to the first capable strategy.
    */
-  async query(query) {
+  async query(query, context) {
     if (!query.cube) {
       throw new Error("Cube name is required in analytics query");
     }
     this.ensureCube(query);
-    const strategy = this.resolveStrategy(query);
+    const ctx = this.callCtx(context);
+    const strategy = this.resolveStrategy(query, ctx);
     this.logger.debug(`[Analytics] Query on cube "${query.cube}" \u2192 ${strategy.name}`);
-    return strategy.execute(query, this.strategyCtx);
+    return strategy.execute(query, ctx);
+  }
+  /**
+   * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
+   * can be queried by name. Idempotent (re-registering overwrites). Returns the
+   * compiled dataset.
+   */
+  registerDataset(dataset) {
+    const compiled = compileDataset(dataset, this.relationshipResolver);
+    this.cubeRegistry.register(compiled.cube);
+    this.datasetRegistry.set(dataset.name, compiled);
+    return compiled;
+  }
+  /**
+   * Execute a semantic-layer dataset (ADR-0021). Compiles the dataset (saved or
+   * inline draft — Studio preview), registers its Cube + join allowlist, then
+   * runs the selection through the `DatasetExecutor` with the request context so
+   * tenant/RLS scoping (D-C) is applied. See {@link IAnalyticsService.queryDataset}.
+   */
+  async queryDataset(dataset, selection, context) {
+    const compiled = this.registerDataset(dataset);
+    this.logger.debug(`[Analytics] queryDataset "${dataset.name}" (object=${dataset.object}, include=${(dataset.include ?? []).join(",") || "\u2014"})`);
+    return new DatasetExecutor(this).execute(compiled, selection, context);
   }
   /**
    * Get cube metadata for discovery.
@@ -702,14 +1204,15 @@ var AnalyticsService = class {
   /**
    * Generate SQL for a query without executing it (dry-run).
    */
-  async generateSql(query) {
+  async generateSql(query, context) {
     if (!query.cube) {
       throw new Error("Cube name is required for SQL generation");
     }
     this.ensureCube(query);
-    const strategy = this.resolveStrategy(query);
+    const ctx = this.callCtx(context);
+    const strategy = this.resolveStrategy(query, ctx);
     this.logger.debug(`[Analytics] generateSql on cube "${query.cube}" \u2192 ${strategy.name}`);
-    return strategy.generateSql(query, this.strategyCtx);
+    return strategy.generateSql(query, ctx);
   }
   // ── Internal ─────────────────────────────────────────────────────
   /**
@@ -802,9 +1305,9 @@ var AnalyticsService = class {
   /**
    * Walk the strategy chain and return the first strategy that can handle the query.
    */
-  resolveStrategy(query) {
+  resolveStrategy(query, ctx) {
     for (const strategy of this.strategies) {
-      if (strategy.canHandle(query, this.strategyCtx)) {
+      if (strategy.canHandle(query, ctx)) {
         return strategy;
       }
     }
@@ -944,14 +1447,56 @@ var AnalyticsServicePlugin = class {
       objectqlAggregate: !!executeAggregate,
       inMemory: false
     }));
+    let getReadScope = this.options.getReadScope;
+    let autoBridgedReadScope = false;
+    if (!getReadScope) {
+      const trySecurity = () => {
+        try {
+          const svc = ctx.getService("security");
+          return svc && typeof svc.getReadFilter === "function" ? svc : void 0;
+        } catch {
+          return void 0;
+        }
+      };
+      if (trySecurity()) {
+        getReadScope = (object, context) => trySecurity()?.getReadFilter(object, context);
+        autoBridgedReadScope = true;
+      }
+    }
+    const relationshipResolver = (baseObject, relationshipName) => {
+      const engine = (() => {
+        try {
+          const svc = ctx.getService("data");
+          return svc && typeof svc.getObject === "function" ? svc : void 0;
+        } catch {
+          return void 0;
+        }
+      })();
+      const obj = engine?.getObject?.(baseObject);
+      const field = obj?.fields?.[relationshipName];
+      if (field && (field.type === "lookup" || field.type === "master_detail") && field.reference) {
+        return field.reference;
+      }
+      return engine ? void 0 : relationshipName;
+    };
     const config = {
       cubes: this.options.cubes,
       logger: ctx.logger,
       queryCapabilities,
       executeRawSql,
       executeAggregate,
-      fallbackService
+      fallbackService,
+      getReadScope,
+      getAllowedRelationships: this.options.getAllowedRelationships,
+      relationshipResolver
     };
+    if (autoBridgedReadScope) {
+      ctx.logger.info('[Analytics] Auto-bridged getReadScope \u2192 "security" service (getReadFilter)');
+    } else if (!getReadScope) {
+      ctx.logger.warn(
+        '[Analytics] No getReadScope configured and no "security" service with getReadFilter found \u2014 the raw-SQL analytics path will NOT enforce tenant/RLS scoping on joined objects (ADR-0021 D-C). Supply getReadScope or register a security service in multi-tenant deployments.'
+      );
+    }
     if (autoBridged) {
       ctx.logger.info('[Analytics] Auto-bridged executeAggregate \u2192 "data" service (IDataEngine)');
     }
@@ -986,7 +1531,14 @@ export {
   AnalyticsService,
   AnalyticsServicePlugin,
   CubeRegistry,
+  DatasetExecutor,
   NativeSQLStrategy,
-  ObjectQLStrategy
+  ObjectQLStrategy,
+  combineFilters,
+  compileDataset,
+  compileScopedFilterToSql,
+  evaluateDerivedMeasures,
+  mergeByDimensions,
+  shiftRange
 };
 //# sourceMappingURL=index.js.map