measurr 0.3.0 → 0.4.0

package/README.md

@@ -12,10 +12,12 @@ returns shaped, typed rows.
 - Tenant-scoped by construction: the engine adds the tenant filter to every statement and
   refuses to run without a tenant. A caller can be scoped to one tenant or a list of them;
   platform admins can query every tenant only through an explicit `allTenants` value that no
-  query input can carry.
+  query input can carry. A dataset without tenants (staff work) is only for those admins.
+- Access per dataset and per field: a staff-only measure lives on the same dataset as the
+  measures everyone may use.
 - The query schema is generated with Zod, so it doubles as an LLM tool schema
   (`z.toJSONSchema`) and as the request validator. It can be built per caller, offering only
-  the datasets they may query.
+  the datasets and fields they may use.
 - No driver or ORM dependency. `zod` is a peer dependency.
 
 ## Quick start
@@ -51,6 +53,11 @@ export const orders = defineDataset({
 	measures: {
 		orders: measure.count({ label: 'Orders' }),
 		revenue: measure.sum(order.col('amount'), { label: 'Revenue' }),
+		// Only callers `authorizeField` allows for 'staff' see or query it.
+		margin: measure.sum(order.col('amount').sub(order.col('cost')), {
+			label: 'Margin',
+			access: 'staff'
+		}),
 		refunded: measure.countWhere(exists(refund, eq(refund.col('orderId'), order.col('id'))), {
 			label: 'Refunded orders'
 		}),
@@ -96,6 +103,7 @@ export const analytics = createAnalytics({
 	},
 	tenant: (ctx: Ctx) => ctx.organizationId,
 	authorize: (dataset, ctx) => ctx.can(`analytics:${dataset.key}`),
+	authorizeField: (dataset, key, access, ctx) => ctx.roles.includes(access),
 	timezone: (ctx) => ctx.timezone,
 	onQuery: (event, ctx) => metrics.record(event.dataset, event.durationMs, event.outcome)
 })
@@ -117,18 +125,38 @@ result.rows[0]?.paidShare // Ratio | null
 
 ## Callers and tools
 
-`authorize` is the one access rule. Everything that offers datasets goes through it:
+Three rules decide what a caller may use, and everything that offers datasets goes through
+them:
+
+- `authorize(dataset, ctx)` decides which datasets `ctx` may query (all when omitted).
+- `authorizeField(dataset, key, access, ctx)` decides which marked measures and dimensions it
+  may use. A field is marked with `access`, a string your app defines (`'staff'`); unmarked
+  fields are open to everyone who may query the dataset. The hook is called only for marked
+  fields, once per access key, and is required as soon as one field is marked
+  (`createAnalytics` throws otherwise). A `ratio` also needs the access of the measures it
+  divides, so a margin rate is as restricted as the margin. The hook's `access` is typed as the
+  union of the keys the datasets use (`AccessKey`) and `key` as their field keys (`FieldKey`),
+  so a new key such as `'finance'` fails an exhaustive `switch` in the hook until it is handled.
+- A dataset without a tenant column is only for a `ctx` whose `tenant(ctx)` is `allTenants`
+  (see below).
+
+With them:
 
 - `analytics.listDatasets(ctx)` resolves to the catalog entries (measures, dimensions, closed
-  values) of the datasets `ctx` may query.
-- `analytics.querySchema({ ctx })` resolves to the input schema for those datasets, for a tool
-  built per caller. It rejects with `AnalyticsError('forbidden')` when nothing is allowed.
+  values) of the datasets `ctx` may query, without the fields it may not use. A dataset with
+  no measure left for `ctx` is left out.
+- `analytics.querySchema({ ctx })` resolves to the input schema for the same datasets and
+  fields, for a tool built per caller, so a model is never offered what it may not use. It
+  rejects with `AnalyticsError('forbidden')` when nothing is allowed.
   `analytics.querySchema({ datasets })` is the synchronous form for a list you already have
-  (typed for those datasets only), and `querySchema()` covers every dataset. Schemas are built once per set of datasets, so
-  `querySchema({ ctx })` returns the same object as `querySchema({ datasets })` for the same
-  allowed set: cache a tool built from it by its dataset keys.
-- `analytics.query` checks `authorize` again on every call, so a schema offered too widely
-  still cannot leak a dataset.
+  (typed for those datasets only), and `querySchema()` covers every dataset and field. Schemas
+  are built once per set of datasets and fields, so `querySchema({ ctx })` returns the same
+  object as `querySchema({ datasets })` when `ctx` may use every field of the allowed set:
+  cache a tool built from it by the keys of what it offers.
+- `analytics.query` checks all three again on every call, so a schema offered too widely still
+  cannot leak a dataset or a field. Naming a field `ctx` may not use (as a measure, in
+  `groupBy` or `sort`, or in a filter) fails with `AnalyticsError('forbidden')`, which names
+  the field.
 
 `AnalyticsResultSchema` is any dataset's result without its keys: rows of `{ key, label }`
 per grouped dimension and a number or null per measure, with totals, `previous?`, `notes` and
@@ -196,13 +224,33 @@ checking the session) before building `ctx`; never read it from the query input.
 lookups resolve labels across tenants, so `"Complaint"` matches every tenant's tag of that
 name.
 
+**Datasets without tenants.** Some tables belong to no organization, such as maintenance
+cases staff work on. Declare them with `tenantColumn: null`. The key stays required, so a
+forgotten tenant column still fails typecheck.
+
+```ts
+export const maintenance = defineDataset({
+	key: 'maintenance',
+	label: 'Maintenance',
+	description: 'One row per maintenance case.',
+	from: maintenanceCase,
+	tenantColumn: null,
+	// ...
+})
+```
+
+Only a `ctx` whose `tenant(ctx)` is `allTenants` may query such a dataset, label lookups
+included. An id or a list of ids, even an empty one, fails with `AnalyticsError('forbidden')`
+before any statement runs; a narrower scope is never ignored. `listDatasets(ctx)` and
+`querySchema({ ctx })` leave the dataset out for those callers.
+
 ## The model
 
 | Concept | What it is |
 | --- | --- |
-| Dataset | One fact table: tenant column, optional scope, time fields, default period, measures, dimensions, source. |
-| Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another) or `ratio` (one measure over another, after aggregation). |
-| Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). |
+| Dataset | One fact table: tenant column (or `null`), optional scope, time fields, default period, measures, dimensions, source. |
+| Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another) or `ratio` (one measure over another, after aggregation). Optionally restricted with `access`. |
+| Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). Optionally restricted with `access`. |
 | Query | `dataset`, 1-4 `measures`, 0-2 `groupBy`, `filters`, `period`, `time`, `compareToPrevious`, `sort` (by an asked measure or grouped dimension), `limit` (1-100, default 20). |
 | Result | `{ period, rows, totals, previous?, notes, truncated }`; `period` is `{ from, to, timezone }` or `{ all: true, timezone }`. |
 
@@ -344,12 +392,22 @@ It checks that every measure runs and returns a number or null, every grouping r
 groups add up to the total (except many-to-many), `isEmpty` plus `isNotEmpty` equals the total,
 open dimensions filter by label to their group's count, closed dimensions filter by value, an
 empty tenant and an empty tenant list see nothing (tenant isolation), and day buckets in a
-far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods.
+far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods. Fields marked
+with `access` are checked like any other.
+
+A dataset without a tenant column has no tenant rows to isolate. Pass `tenant: allTenants`,
+and the kit replaces the isolation checks with one that an empty tenant and an empty tenant
+list are refused with `forbidden`. Every other check runs as usual.
+
+```ts
+await assertDatasetContract({ dataset: maintenance, source, tenant: allTenants })
+```
 
 ## Extending
 
 - **A measure or dimension** is one entry in a dataset. Dimensions are groupable and
-  filterable unless `groupOnly` or `filterOnly` says otherwise. The contract kit covers it
+  filterable unless `groupOnly` or `filterOnly` says otherwise, and every field is open to
+  everyone who may query the dataset unless `access` restricts it. The contract kit covers it
   without a new test.
 - **A dataset** is one `defineDataset` call added to `createAnalytics({ datasets })`.
 - **A computed value** is written with the expression builders (`caseWhen`, `exists`,
@@ -362,15 +420,16 @@ far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods
 
 ## Stable API
 
-Kept stable for publishing: `createAnalytics` and its options, `allTenants`, `analytics.query`,
-`explain`, `querySchema`, `resultSchema`, `listDatasets`; `AnalyticsResultSchema`,
-`analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset` (with `defaultPeriod`),
-`measure.*`, `dimension.*`, `table` / `Table`, the expression builders; the `Dialect`,
+Kept stable for publishing: `createAnalytics` and its options (with `authorize` and
+`authorizeField`), `allTenants`, `analytics.query`, `explain`, `querySchema`, `resultSchema`,
+`listDatasets`; `AnalyticsResultSchema`, `analyticsToolGuidance`, `AnalyticsQueryEvent`;
+`defineDataset` (with `defaultPeriod` and `tenantColumn: null`), `measure.*` and `dimension.*`
+(with `access`), `table` / `Table`, the expression builders; the `Dialect`,
 `SqlRenderer` and `AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
 `assertDatasetContract`; and the types `AnalyticsQuery`, `AnalyticsResult`, `ResultPeriod`,
-`PeriodInput`, `Tenant`, `TenantId`, `Ratio`, `AnalyticsError` codes and their details
-(`isAnalyticsError`). `ExprNode` and `SelectStatement` are
-exported for dialect authors and may grow new node kinds.
+`PeriodInput`, `Tenant`, `TenantId`, `AccessKey`, `FieldKey`, `Ratio`, `AnalyticsError` codes
+and their details (`isAnalyticsError`). `ExprNode` and `SelectStatement` are exported for
+dialect authors and may grow new node kinds.
 
 ## Install
 

package/dist/analytics.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { CompiledStatement, Dialect } from './compile.js';
-import type { AnyDataset, AnyDimension } from './dataset.js';
+import type { AnyDataset, AnyDimension, Dataset } from './dataset.js';
 import { type Tenant } from './plan.js';
 import { type DatasetQuery, type QueryResult, type ResultOf } from './query.js';
 export type Row = Record<string, unknown>;
@@ -53,6 +53,10 @@ export type AnalyticsQueryEvent = {
     /** What the query threw, on error. */
     error?: unknown;
 };
+/** The measure and dimension keys of a dataset (of any dataset, for a union). */
+export type FieldKey<D> = D extends Dataset<string, infer M, infer Dm> ? keyof (M & Dm) & string : never;
+/** The access keys a dataset's measures and dimensions are marked with. */
+export type AccessKey<D> = D extends Dataset<string, infer M, infer Dm> ? NonNullable<(M & Dm)[keyof (M & Dm)]['access']> : never;
 export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
     datasets: DS;
     /** Databases by name; a dataset's `source` picks one, or the only one is used. */
@@ -69,6 +73,14 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
      * `listDatasets(ctx)` and `querySchema({ ctx })` offer, and is checked again on every query.
      */
     authorize?: ((dataset: DS[number], ctx: Ctx) => boolean | Promise<boolean>) | undefined;
+    /**
+     * Whether `ctx` may use the measure or dimension `key` of `dataset`, which is marked with
+     * `access`. Called only for marked fields, once per access key: a ratio also needs the
+     * access of the measures it divides. Required when any field is marked. It decides which
+     * fields `listDatasets(ctx)` and `querySchema({ ctx })` offer, and is checked again on every
+     * query. `access` is the union of the keys the datasets use, so a new key shows up here.
+     */
+    authorizeField?: ((dataset: DS[number], key: FieldKey<DS[number]>, access: AccessKey<DS[number]>, ctx: Ctx) => boolean | Promise<boolean>) | undefined;
     /** IANA timezone periods and time buckets resolve in. UTC when omitted. */
     timezone?: ((ctx: Ctx) => string | null | undefined | Promise<string | null | undefined>) | undefined;
     /** The clock periods and `minutesAgo` resolve against. */
@@ -123,15 +135,15 @@ export type Analytics<DS extends readonly AnyDataset[], Ctx> = {
         key: K;
     }>>>;
     /**
-     * The input schema for the datasets `authorize` allows `ctx`, for a tool built per caller.
-     * Rejects with `forbidden` when none are allowed.
+     * The input schema for the datasets `ctx` may query, without the fields `authorizeField`
+     * refuses it, for a tool built per caller. Rejects with `forbidden` when none are allowed.
      */
     querySchema(options: {
         ctx: Ctx;
     }): Promise<z.ZodType<DatasetQuery<DS[number]>>>;
     /** The result schema for one dataset. */
     resultSchema(dataset: DS[number]['key']): z.ZodType<QueryResult<Row, Row>>;
-    /** The datasets `authorize` allows `ctx`, with their measures and dimensions. */
+    /** The datasets `ctx` may query, with the measures and dimensions it may use. */
     listDatasets(ctx: Ctx): Promise<DatasetCatalogEntry<DS[number]['key']>[]>;
 };
 export type AnalyticsQuery<A> = A extends Analytics<infer DS, never> ? DatasetQuery<DS[number]> : never;

package/dist/dataset.d.ts

@@ -5,9 +5,19 @@ declare const ratioBrand: unique symbol;
 export type Ratio = number & {
     readonly [ratioBrand]: 'zeroToOne';
 };
-type Described = {
+type Described<Access extends string = string> = {
     label: string;
     description?: string | undefined;
+    /**
+     * Restricts the field to callers `authorizeField` allows for this access key (a string the
+     * app defines, such as `'staff'`). Unmarked fields are open to everyone who may query the
+     * dataset.
+     */
+    access?: Access | undefined;
+};
+/** Keeps a field's access key literal, so `authorizeField` is typed with the keys in use. */
+export type Marked<Access extends string> = {
+    readonly access: Access | undefined;
 };
 /**
  * `count` results are never null. `number` results (sum, avg, median) are null for an empty
@@ -19,6 +29,7 @@ export type AggregateMeasure<R extends 'count' | 'number' = 'count' | 'number'>
     readonly result: R;
     readonly label: string;
     readonly description: string | undefined;
+    readonly access: string | undefined;
     readonly node: Extract<ExprNode, {
         kind: 'aggregate';
     }>;
@@ -28,6 +39,7 @@ export type ShareMeasure = {
     readonly result: 'ratio';
     readonly label: string;
     readonly description: string | undefined;
+    readonly access: string | undefined;
     readonly numerator: ExprNode;
     readonly denominator: ExprNode | null;
 };
@@ -36,6 +48,8 @@ export type RatioMeasure<A extends string = string, B extends string = string> =
     readonly result: 'ratio';
     readonly label: string;
     readonly description: string | undefined;
+    /** A ratio also needs the access of the measures it divides. */
+    readonly access: string | undefined;
     readonly numerator: A;
     readonly denominator: B;
 };
@@ -46,32 +60,32 @@ export type MeasureValue<M> = M extends {
 } ? number : M extends {
     result: 'number';
 } ? number | null : Ratio | null;
-type Filtered = Described & {
+type Filtered<Access extends string> = Described<Access> & {
     where?: Expr<'boolean'> | undefined;
 };
 export declare const measure: {
     /** Number of rows, optionally only those matching `where`. */
-    count(options: Filtered): AggregateMeasure<'count'>;
+    count<Access extends string = never>(options: Filtered<Access>): AggregateMeasure<'count'> & Marked<NoInfer<Access>>;
     /** Number of rows matching `condition`. */
-    countWhere(condition: Expr<'boolean'>, options: Described): AggregateMeasure<'count'>;
+    countWhere<Access extends string = never>(condition: Expr<'boolean'>, options: Described<Access>): AggregateMeasure<'count'> & Marked<NoInfer<Access>>;
     /** Number of distinct non-null values of `expr`. */
-    countDistinct(expr: Expr<SqlType>, options: Filtered): AggregateMeasure<'count'>;
-    sum(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
-    avg(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
-    median(expr: Expr<'number'>, options: Filtered): AggregateMeasure<'number'>;
+    countDistinct<Access extends string = never>(expr: Expr<SqlType>, options: Filtered<Access>): AggregateMeasure<'count'> & Marked<NoInfer<Access>>;
+    sum<Access extends string = never>(expr: Expr<'number'>, options: Filtered<Access>): AggregateMeasure<'number'> & Marked<NoInfer<Access>>;
+    avg<Access extends string = never>(expr: Expr<'number'>, options: Filtered<Access>): AggregateMeasure<'number'> & Marked<NoInfer<Access>>;
+    median<Access extends string = never>(expr: Expr<'number'>, options: Filtered<Access>): AggregateMeasure<'number'> & Marked<NoInfer<Access>>;
     /**
      * The share of rows matching `numerator` among rows matching `denominator` (all rows when
      * omitted). A `Ratio` from 0 to 1.
      */
-    share(options: Described & {
+    share<Access extends string = never>(options: Described<Access> & {
         numerator: Expr<'boolean'>;
         denominator?: Expr<'boolean'> | undefined;
-    }): ShareMeasure;
+    }): ShareMeasure & Marked<NoInfer<Access>>;
     /**
      * One measure of this dataset over another, computed after aggregation. Both keys must be
      * measures of the same dataset; `defineDataset` checks them.
      */
-    ratio<const A extends string, const B extends string>(numerator: A, denominator: B, options: Described): RatioMeasure<A, B>;
+    ratio<const A extends string, const B extends string, Access extends string = never>(numerator: A, denominator: B, options: Described<Access>): RatioMeasure<A, B> & Marked<NoInfer<Access>>;
 };
 /**
  * How a dimension filters:
@@ -82,22 +96,22 @@ export declare const measure: {
  * - `time`: time buckets keyed by ISO date - `between`, `isEmpty`, `isNotEmpty`.
  */
 export type DimensionCategory = 'closed' | 'open' | 'numeric' | 'time';
-type DimensionOptions<G extends boolean = boolean, F extends boolean = boolean> = Described & {
+type DimensionOptions<G extends boolean = boolean, F extends boolean = boolean, Access extends string = string> = Described<Access> & {
     /** Only offered for grouping. */
     groupOnly?: G | undefined;
     /** Only offered for filtering. */
     filterOnly?: F | undefined;
 };
 /** Time dimensions name themselves after their unit unless given a label. */
-type TimeDimensionOptions<G extends boolean, F extends boolean, Key> = Omit<DimensionOptions<G, F>, 'label'> & {
+type TimeDimensionOptions<G extends boolean, F extends boolean, Key, Access extends string> = Omit<DimensionOptions<G, F, Access>, 'label'> & {
     label?: string | undefined;
     labelFor?: ((key: Key) => string) | undefined;
 };
 /**
  * `groupOnly: true` makes `filterable` the literal `false` (and `filterOnly`, `groupable`), so
- * queries cannot filter or group by what the dimension does not offer.
+ * queries cannot filter or group by what the dimension does not offer. `access` stays literal.
  */
-export type DimensionAccess<G extends boolean, F extends boolean> = {
+export type DimensionAccess<G extends boolean, F extends boolean, Access extends string = never> = Marked<Access> & {
     readonly groupable: [F] extends [true] ? false : boolean;
     readonly filterable: [G] extends [true] ? false : boolean;
 };
@@ -105,6 +119,7 @@ type DimensionBase<C extends DimensionCategory, Key> = {
     readonly category: C;
     readonly label: string;
     readonly description: string | undefined;
+    readonly access: string | undefined;
     readonly groupable: boolean;
     readonly filterable: boolean;
     /** Phantom: the key type in result rows. */
@@ -187,29 +202,29 @@ export declare const dimension: {
      * every value, so adding an enum value fails typecheck until it has a label, and a column
      * typed with values outside `values` fails too. A nullable column gives null keys.
      */
-    enum<const E extends Record<string, string>, V extends string | null, G extends boolean = boolean, F extends boolean = boolean>(expr: Expr<'string', V> & CoversValues<V, E[keyof E]>, values: E, options: DimensionOptions<G, F> & EmptyOption & {
+    enum<const E extends Record<string, string>, V extends string | null, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(expr: Expr<'string', V> & CoversValues<V, E[keyof E]>, values: E, options: DimensionOptions<G, F, Access> & EmptyOption & {
         labels: Record<E[keyof E], string>;
-    }): EnumDimension<E[keyof E], EmptyOf<V>> & DimensionAccess<G, F>;
+    }): EnumDimension<E[keyof E], EmptyOf<V>> & DimensionAccess<G, F, NoInfer<Access>>;
     /**
      * A value computed from other columns with the expression builders, usually `caseWhen`.
      * `values` lists every value the expression can produce, with its label; a plain value of
      * the expression missing from `values` fails typecheck. A `caseWhen` without `otherwise`
      * gives null keys.
      */
-    computed<V extends string | null, const K extends string, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & EmptyOption & {
+    computed<V extends string | null, const K extends string, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(options: DimensionOptions<G, F, Access> & EmptyOption & {
         expr: Expr<'string', V> & CoversValues<V, NoInfer<K>>;
         values: Record<K, string>;
-    }): EnumDimension<K, EmptyOf<V>> & DimensionAccess<G, F>;
+    }): EnumDimension<K, EmptyOf<V>> & DimensionAccess<G, F, NoInfer<Access>>;
     /**
      * A to-one relation such as a team. The key type comes from the `key` column, so a branded
      * id column types the key in filters and rows. Rows without a related record get the
      * `empty` label and a null key.
      */
-    relation<Key extends string | number, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & {
+    relation<Key extends string | number, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(options: DimensionOptions<G, F, Access> & {
         key: Expr<Key extends number ? 'number' : 'string', Key | null>;
         name: Expr<'string'>;
         empty?: string | undefined;
-    }): RelationDimension<Key> & DimensionAccess<G, F>;
+    }): RelationDimension<Key> & DimensionAccess<G, F, NoInfer<Access>>;
     /**
      * A to-many relation through a link table, such as tags. Grouping counts a row once per
      * related value, so totals for such a grouping come from a separate query. Filtering
@@ -218,7 +233,7 @@ export declare const dimension: {
      * `through.table` is the link table as a standalone `table()` (further joins hang off it),
      * and `through.on` links it to the dataset's table.
      */
-    manyToMany<Row = unknown, G extends boolean = boolean, F extends boolean = boolean>(options: DimensionOptions<G, F> & {
+    manyToMany<Row = unknown, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(options: DimensionOptions<G, F, Access> & {
         through: {
             table: Table<Row>;
             on: Expr<'boolean'>;
@@ -228,15 +243,15 @@ export declare const dimension: {
         /** Explains the overlap to the reader of a grouped result. */
         note?: string | undefined;
         empty?: string | undefined;
-    }): ManyToManyDimension & DimensionAccess<G, F>;
+    }): ManyToManyDimension & DimensionAccess<G, F, NoInfer<Access>>;
     /** A numeric column, grouped by its exact values and filtered with `between`. */
-    number<G extends boolean = boolean, F extends boolean = boolean>(expr: Expr<'number'>, options: DimensionOptions<G, F> & {
+    number<G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(expr: Expr<'number'>, options: DimensionOptions<G, F, Access> & {
         labelFor?: ((key: number) => string) | undefined;
-    }): NumberDimension & DimensionAccess<G, F>;
+    }): NumberDimension & DimensionAccess<G, F, NoInfer<Access>>;
     /** Day, ISO week (starting Monday) or month of a time field, in the tenant's timezone. */
-    timeBucket<const T extends string, G extends boolean = boolean, F extends boolean = boolean>(time: T, unit: TimeBucketUnit, options?: TimeDimensionOptions<G, F, string>): TimeBucketDimension<T> & DimensionAccess<G, F>;
+    timeBucket<const T extends string, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(time: T, unit: TimeBucketUnit, options?: TimeDimensionOptions<G, F, string, Access>): TimeBucketDimension<T> & DimensionAccess<G, F, NoInfer<Access>>;
     /** ISO weekday (1 = Monday) or hour (0-23) of a time field, in the tenant's timezone. */
-    timePart<const T extends string, G extends boolean = boolean, F extends boolean = boolean>(time: T, part: TimePartName, options?: TimeDimensionOptions<G, F, number>): TimePartDimension<T> & DimensionAccess<G, F>;
+    timePart<const T extends string, G extends boolean = boolean, F extends boolean = boolean, Access extends string = never>(time: T, part: TimePartName, options?: TimeDimensionOptions<G, F, number, Access>): TimePartDimension<T> & DimensionAccess<G, F, NoInfer<Access>>;
 };
 export type TimeField = {
     readonly column: ExprNode;
@@ -248,7 +263,8 @@ export type Dataset<K extends string = string, M extends Record<string, AnyMeasu
     readonly description: string;
     readonly from: TableRef;
     readonly source: string | undefined;
-    readonly tenantColumn: ExprNode;
+    /** Null for a dataset without tenants, which only `allTenants` may query. */
+    readonly tenantColumn: ExprNode | null;
     readonly scope: ExprNode | null;
     readonly time: Readonly<Record<T, TimeField>>;
     readonly defaultTime: T;
@@ -285,8 +301,12 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
     };
     /** Which source (database) the dataset runs on; the default when there is one source. */
     source?: string | undefined;
-    /** The column every query is filtered by; the value comes from `tenant(ctx)`. */
-    tenantColumn: Expr<SqlType>;
+    /**
+     * The column every query is filtered by; the value comes from `tenant(ctx)`. `null` for a
+     * dataset whose rows belong to no tenant (staff work, platform-wide records): only a caller
+     * whose `tenant(ctx)` is `allTenants` may query it, and everyone else is refused.
+     */
+    tenantColumn: Expr<SqlType> | null;
     /** Always applied, for example excluding test rows. */
     scope?: Expr<'boolean'> | undefined;
     time: Record<T, {