measurr 0.2.0 → 0.4.0

package/README.md

@@ -10,11 +10,14 @@ returns shaped, typed rows.
 - Database-neutral definitions: dialects plug in through the `Dialect` interface, and Postgres
   ships today (`measurr/postgres`).
 - Tenant-scoped by construction: the engine adds the tenant filter to every statement and
-  refuses to run without a tenant. Platform admins can query every tenant only through an
-  explicit `allTenants` value that no query input can carry.
+  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. 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
@@ -50,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'
 		}),
@@ -95,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)
 })
@@ -116,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
@@ -154,9 +183,21 @@ What the hook throws or rejects with is swallowed; it cannot fail a query.
 ## Tenants and platform admins
 
 `tenant(ctx)` decides the scope of every statement, including the lookups that resolve filter
-labels. It returns a tenant id, or `allTenants` to drop the tenant filter for a caller allowed
-to see every tenant. Anything else (null, undefined, `''`, any other value) is refused with
-`AnalyticsError('missing_tenant')`, so a missing organization never widens a query.
+labels. It returns a tenant id (`TenantId`, a non-empty string or a finite number), a readonly
+list of them, or `allTenants` to drop the tenant filter for a caller allowed to see every
+tenant. Anything else is refused with `AnalyticsError('missing_tenant')`: null, undefined,
+`''`, a list containing one of those or `allTenants`, or any other value. A missing
+organization never widens a query.
+
+A list compiles to `tenantColumn IN (...)` with one parameter per id; a one-element list is
+the same statement as its id. An empty list is a scope that matches no rows: a reseller with
+no connected organizations sees zeros, never everything. Lists are for callers scoped to a set
+of organizations, such as an organization-group admin, a reseller, or either narrowed to a
+region:
+
+```ts
+tenant: (ctx: Ctx) => ctx.visibleOrganizationIds // readonly OrganizationId[]
+```
 
 The scope comes only from `ctx`, which your server builds from the session. `allTenants` is a
 symbol, so a query (JSON, a model's tool call) cannot carry it. A discriminated context keeps
@@ -183,15 +224,35 @@ 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, 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 }`. |
+| Result | `{ period, rows, totals, previous?, notes, truncated }`; `period` is `{ from, to, timezone }` or `{ all: true, timezone }`. |
 
 **Operators per dimension kind.** Closed and open dimensions take `in`, `notIn`, `isEmpty`
 and `isNotEmpty`; numeric and time dimensions take `between`, `isEmpty` and `isNotEmpty`. The
@@ -222,6 +283,21 @@ try {
 The previous period has the same length and ends the day before. Time buckets use the same
 timezone. `time` picks the time field the period applies to; a time dimension names its own.
 
+`{ all: true }` drops the time filter: every row counts, and time buckets and parts still group
+by the time field. It has no previous period, so `compareToPrevious` with it is an
+`invalid_query`. The result's `period` is then `{ all: true, timezone }` instead of
+`{ from, to, timezone }`; `previous.period` is always a range. The type follows the query. A
+query that names a range, or names no period on a dataset whose default is a range, gets
+`{ from, to, timezone }`, so `result.period.from` needs no narrowing. A query typed only as
+`AnalyticsQuery` (parsed from the schema) gets the `ResultPeriod` union; narrow it with
+`'all' in result.period`.
+
+A query that names no period (or sends null) gets the dataset's `defaultPeriod`, the last 30
+days unless the dataset says otherwise. A dataset that describes current state (units,
+organizations) sets `defaultPeriod: { all: true }`, so "how many units per status" counts
+every unit. The generated schema states each dataset's default, so a model knows what leaving
+`period` out means.
+
 **Totals are a separate, ungrouped statement**, so a many-to-many grouping (an order with
 two tags appears in two rows) never inflates them. Filters on many-to-many dimensions compile
 to `EXISTS`, so they never multiply rows either.
@@ -315,13 +391,23 @@ await assertDatasetContract({ dataset: orders, source, tenant: seededTenantId })
 It checks that every measure runs and returns a number or null, every grouping runs and its
 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 sees nothing (tenant isolation), and day buckets in a far-from-UTC timezone
-(default `Pacific/Auckland`) agree with single-day periods.
+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. 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`,
@@ -334,15 +420,16 @@ empty tenant sees nothing (tenant isolation), and day buckets in a far-from-UTC
 
 ## Stable API
 
-Kept stable for publishing: `createAnalytics` and its options, `allTenants`, `analytics.query`,
-`explain`, `querySchema`, `resultSchema`, `listDatasets`; `AnalyticsResultSchema`,
-`analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset`, `measure.*`,
-`dimension.*`, `table` / `Table`, the expression builders; the `Dialect`, `SqlRenderer` and
-`AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
-`assertDatasetContract`; and the types
-`AnalyticsQuery`, `AnalyticsResult`, `Ratio`, `AnalyticsError` codes and their details
-(`isAnalyticsError`). `ExprNode` and `SelectStatement` are
-exported for dialect authors and may grow new node kinds.
+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`, `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,14 +53,19 @@ 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. */
     sources: Record<string, AnalyticsSource>;
     /**
-     * The tenant every query is scoped to. Queries without one (null, undefined, '') are
-     * refused. Return `allTenants` to drop the tenant filter, only for callers allowed to see
-     * every tenant's rows.
+     * The tenant every query is scoped to, or a list of them (an empty list matches no rows).
+     * Queries without one (null, undefined, '', a list holding one of those) are refused.
+     * Return `allTenants` to drop the tenant filter, only for callers allowed to see every
+     * tenant's rows.
      */
     tenant: (ctx: Ctx) => Tenant | null | undefined;
     /**
@@ -68,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. */
@@ -122,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

@@ -1,12 +1,23 @@
 import { type Expr, type ExprNode, type SqlType, type Table, type TableRef, type TimeBucketUnit, type TimePartName } from './expr.js';
+import { DEFAULT_PERIOD, type PeriodInput } from './period.js';
 declare const ratioBrand: unique symbol;
 /** A share or ratio between 0 and 1. Branded so nobody renders 0.42 as "0.42%". */
 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
@@ -18,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';
     }>;
@@ -27,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;
 };
@@ -35,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;
 };
@@ -45,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:
@@ -81,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;
 };
@@ -104,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. */
@@ -186,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
@@ -217,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'>;
@@ -227,30 +243,33 @@ 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;
     readonly label: string;
 };
-export type Dataset<K extends string = string, M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>, T extends string = string> = {
+export type Dataset<K extends string = string, M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>, T extends string = string, P extends PeriodInput = PeriodInput> = {
     readonly key: K;
     readonly label: string;
     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;
+    /** Kept as a type, so results know whether a query without a period covers all time. */
+    readonly defaultPeriod: P;
     readonly measures: M;
     readonly dimensions: Dm;
 };
@@ -272,7 +291,7 @@ type CheckDimensions<Dm, T extends string> = {
         time: T;
     } : unknown;
 };
-export type DatasetDefinition<K extends string, M extends Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension>, T extends string> = {
+export type DatasetDefinition<K extends string, M extends Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension>, T extends string, P extends PeriodInput> = {
     key: K;
     label: string;
     /** Tells a reader (and a model) what one row of the dataset is. */
@@ -282,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, {
@@ -292,6 +315,11 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
     }>;
     /** The time field periods apply to when a query names none; the first one by default. */
     defaultTime?: NoInfer<T> | undefined;
+    /**
+     * The period of a query that names none; the last 30 days by default. A dataset of current
+     * state (units, organizations) sets `{ all: true }`.
+     */
+    defaultPeriod?: P | undefined;
     measures: M & CheckMeasures<M>;
     dimensions: Dm & CheckDimensions<Dm, NoInfer<T>>;
 };
@@ -299,5 +327,5 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
  * Declares a dataset: one fact table with its tenant column, time fields, measures and
  * dimensions. Keys stay literal types, so queries and result rows are typed from it.
  */
-export declare function defineDataset<const K extends string, const M extends Record<string, AnyMeasure>, const Dm extends Record<string, AnyDimension>, const T extends string>(definition: DatasetDefinition<K, M, Dm, T>): Dataset<K, M, Dm, T>;
+export declare function defineDataset<const K extends string, const M extends Record<string, AnyMeasure>, const Dm extends Record<string, AnyDimension>, const T extends string, const P extends PeriodInput = typeof DEFAULT_PERIOD>(definition: DatasetDefinition<K, M, Dm, T, P>): Dataset<K, M, Dm, T, P>;
 export {};

package/dist/guidance.d.ts

@@ -2,4 +2,4 @@
  * How a model should use an analytics query tool, as markdown bullets for its instructions.
  * It does not name the tool, so add a line that does.
  */
-export declare const analyticsToolGuidance = "- Answer every \"how many\", \"how much\", \"per week\" or \"split by\" question with the analytics tool. Never count by hand from lists or pages.\n- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.\n- Say which period and filters the numbers cover, using the dates in the result (\"1-30 September\").\n- Compare with the previous period (compareToPrevious) when the change is the point, such as \"is it going up\".\n- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.\n- Ask one short question only when the period is genuinely ambiguous (\"this season\") and someone can answer; otherwise take the natural reading and state it.";
+export declare const analyticsToolGuidance = "- Answer every \"how many\", \"how much\", \"per week\" or \"split by\" question with the analytics tool. Never count by hand from lists or pages.\n- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.\n- Say which period and filters the numbers cover, using the dates in the result (\"1-30 September\", or \"all time\").\n- Compare with the previous period (compareToPrevious) when the change is the point, such as \"is it going up\".\n- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.\n- Ask one short question only when the period is genuinely ambiguous (\"this season\") and someone can answer; otherwise take the natural reading and state it.";