@segmentstream-cloud/ontology 0.16.0 → 0.18.0

package/dist/measure.js

@@ -1,23 +1,36 @@
+/** The aggregates a measure expression may contain, `count` included. */
+export const MEASURE_AGGREGATES = ["count", "sum", "countDistinct", "avg", "min", "max"];
 function binary(op) {
     return (left, right, options) => ({ op, args: [left, right], ...options });
 }
-/** Arithmetic combines aggregates; references name another measure of the same entity. */
-export const m = {
-    count: (options) => ({ op: "count", ...options }),
-    sum: (property, options) => ({
-        op: "sum",
+/** An aggregate of one property of the entity. */
+function aggregate(op) {
+    return (property, options) => ({
+        op,
         args: [{ op: "column", name: property }],
         ...options,
-    }),
+    });
+}
+/**
+ * Arithmetic combines aggregates; references name another measure of the same entity. Every
+ * aggregate takes `where`, conditions on properties of the entity that the rows it reads must meet,
+ * and `balanceOver`, the date its rows are snapshots over.
+ */
+export const m = {
+    count: (options) => ({ op: "count", ...options }),
+    /** The sum of an integer or number property. */
+    sum: aggregate("sum"),
     /**
      * The number of distinct non-null values of a text, email, url, select, integer, date or timestamp
      * property. Distinct counts do not add up across groups.
      */
-    countDistinct: (property, options) => ({
-        op: "countDistinct",
-        args: [{ op: "column", name: property }],
-        ...options,
-    }),
+    countDistinct: aggregate("countDistinct"),
+    /** The average of an integer or number property, ignoring nulls. Averages do not add up. */
+    avg: aggregate("avg"),
+    /** The least value of an integer or number property. Minimums do not add up. */
+    min: aggregate("min"),
+    /** The greatest value of an integer or number property. Maximums do not add up. */
+    max: aggregate("max"),
     ref: (name, options) => ({ op: "measure", name, ...options }),
     literal: (value, options) => ({
         op: "literal",
@@ -29,12 +42,52 @@ export const m = {
     multiply: binary("multiply"),
     divide: binary("divide"),
 };
+/** The conditions an expression declares: an aggregate's `where` option, or a `filtered` node's. */
+export function conditionsOf(value) {
+    return "where" in value ? value.where : undefined;
+}
+/** The balance property an expression node declares: an aggregate's `balanceOver` option. */
+export function balanceOf(value) {
+    return "balanceOver" in value ? value.balanceOver : undefined;
+}
 /**
- * Strip authoring options and resolve logical properties to physical columns for the manifest: a
- * warehouse-backed property's `column`, or a stored property's replication view column, which is its
- * wire name.
+ * The balance properties a measure's own aggregates declare, top-level or inside arithmetic and
+ * `filtered` expressions, without duplicates. References are not followed: the platform inherits a
+ * referenced measure's balance itself.
  */
-export function measureExpression(value, columns) {
+export function balancesOf(value) {
+    const balances = new Set();
+    const visit = (expression, depth) => {
+        const balance = balanceOf(expression);
+        if (typeof balance === "string") {
+            balances.add(balance);
+        }
+        if ("args" in expression && Array.isArray(expression.args) && depth < 30) {
+            for (const arg of expression.args) {
+                visit(arg, depth + 1);
+            }
+        }
+    };
+    visit(value, 0);
+    return [...balances];
+}
+/** The property a condition names: `property` as authored, `column` in a `filtered` expression. */
+export function conditionProperty(condition) {
+    if ("property" in condition) {
+        return condition.property;
+    }
+    return "column" in condition ? condition.column : undefined;
+}
+function columnCondition(condition, columns) {
+    const property = "property" in condition ? condition.property : condition.column;
+    return {
+        column: columns.get(property) ?? property,
+        operator: condition.operator,
+        ...(condition.value === undefined ? {} : { value: condition.value }),
+        ...(condition.values === undefined ? {} : { values: [...condition.values] }),
+    };
+}
+function bareExpression(value, columns) {
     switch (value.op) {
         case "count":
             return { op: "count" };
@@ -44,7 +97,31 @@ export function measureExpression(value, columns) {
             return { op: "measure", name: value.name };
         case "literal":
             return { op: "literal", value: value.value };
+        case "filtered":
+            return {
+                op: "filtered",
+                args: value.args.map((arg) => measureExpression(arg, columns)),
+                where: value.where.map((condition) => columnCondition(condition, columns)),
+            };
         default:
             return { op: value.op, args: value.args.map((arg) => measureExpression(arg, columns)) };
     }
 }
+/**
+ * Strip authoring options and resolve logical properties to physical columns for the manifest: a
+ * warehouse-backed property's `column`, or a stored property's replication view column, which is its
+ * wire name. An aggregate's `where` becomes the `filtered` expression that wraps it, its conditions
+ * naming columns too.
+ */
+export function measureExpression(value, columns) {
+    const expression = bareExpression(value, columns);
+    const where = conditionsOf(value);
+    if (where === undefined || value.op === "filtered") {
+        return expression;
+    }
+    return {
+        op: "filtered",
+        args: [expression],
+        where: where.map((condition) => columnCondition(condition, columns)),
+    };
+}

package/dist/migrate/model.d.ts

@@ -44,6 +44,17 @@ export declare const MigrationPlan: Schema.Struct<{
     readonly currentHash: Schema.optionalKey<Schema.String>;
     readonly target: Schema.Union<readonly [Schema.encodeKeys<Schema.Struct<{
         readonly entities: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
+            readonly measures: Schema.optionalKey<Schema.$Array<Schema.encodeKeys<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly label: Schema.String;
+                readonly description: Schema.String;
+                readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+                readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+                readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+                readonly balanceOver: Schema.optionalKey<Schema.String>;
+            }>, {
+                readonly balanceOver: "balance_over";
+            }>>>;
             readonly properties: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
                 readonly column: Schema.optionalKey<Schema.String>;
                 readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
@@ -96,14 +107,6 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly key: Schema.$Array<Schema.String>;
                 readonly currency: Schema.optionalKey<Schema.String>;
             }>>;
-            readonly measures: Schema.optionalKey<Schema.$Array<Schema.Struct<{
-                readonly name: Schema.String;
-                readonly label: Schema.String;
-                readonly description: Schema.String;
-                readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
-                readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
-                readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-            }>>>;
             readonly id: Schema.String;
             readonly name: Schema.String;
             readonly label: Schema.String;
@@ -175,6 +178,7 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
                 readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
                 readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+                readonly balanceOver: Schema.optionalKey<Schema.String>;
             }>>>;
             readonly id: Schema.String;
             readonly name: Schema.String;

package/dist/property.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import { BlobValue, type BLOB_CONTENT_TYPES } from "./blob.js";
+import { BlobValue } from "./blob.js";
 /** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
 export declare const PROPERTY_TYPES: readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"];
 export type PropertyType = (typeof PROPERTY_TYPES)[number];
@@ -131,10 +131,11 @@ declare function ref<const O extends ReferenceOptions>(target: string | {
 }, options?: O): ReferenceOf<O>;
 /** Property constructors. */
 export interface BlobOptions extends Omit<PropertyOptions<BlobValue>, "default" | "unique"> {
-    readonly accept: ReadonlyArray<(typeof BLOB_CONTENT_TYPES)[number]>;
+    /** MIME types or ranges such as image/*; omitted means any file. */
+    readonly accept?: ReadonlyArray<string>;
     readonly maxBytes?: number;
 }
-declare function blob<const O extends BlobOptions>(options: O): PropertyOf<BlobValue, O>;
+declare function blob<const O extends BlobOptions>(options?: O): PropertyOf<BlobValue, O>;
 export declare const p: {
     readonly text: typeof text;
     readonly email: typeof email;

package/dist/property.js

@@ -181,10 +181,15 @@ function ref(target, options) {
     return (settings.optional === true ? Schema.optionalKey(schema) : schema);
 }
 function blob(options) {
+    const settings = options ?? {};
     return construct({
         type: "blob",
         base: BlobValue,
-        options: { ...options, maxBytes: options.maxBytes ?? MAX_BLOB_BYTES },
+        options: {
+            ...settings,
+            accept: settings.accept ?? ["*/*"],
+            maxBytes: settings.maxBytes ?? MAX_BLOB_BYTES,
+        },
     });
 }
 export const p = {

package/dist/render.d.ts

@@ -1,4 +1,4 @@
-import type { ActionManifest, EntityManifest, OntologyManifest } from "./manifest.js";
+import type { ActionManifest, EntityManifest, MeasureManifest, OntologyManifest } from "./manifest.js";
 export interface RenderOptions {
     /**
      * The permissions of the reader. Only the actions these permissions may run are listed, and only
@@ -9,6 +9,11 @@ export interface RenderOptions {
 }
 /** What an action of the manifest requires; version 1 manifests leave it implicit. */
 export declare function actionPermission(entity: string, action: ActionManifest): string;
+/**
+ * A measure's description followed by its conditions and balance note, as `describe`, the MCP
+ * measure list and the console show it: `Revenue of won orders. Where status = "won".`
+ */
+export declare function measureDescription(entity: EntityManifest, measure: MeasureManifest): string;
 /**
  * Renders the catalog as prose for agents and people: each entity with its properties, both
  * directions of its relationships and its actions, then the roles with their permissions. Without a
@@ -22,7 +27,6 @@ export declare function renderCatalog(manifest: OntologyManifest, options?: Rend
  * or everything without them.
  */
 export declare function describeCatalog(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;
-type MeasureManifest = NonNullable<EntityManifest["measures"]>[number];
 /** A measure as aggregates name it: `<entity>.<measure>`. */
 export interface NamedMeasure {
     readonly name: string;
@@ -59,4 +63,3 @@ export declare function reachesOf(manifest: OntologyManifest, from: string, perm
  * per measure entity the entities it reaches. Empty when the reader may read no measure.
  */
 export declare function renderAggregates(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;
-export {};

package/dist/render.js

@@ -154,6 +154,162 @@ function section(title, lines) {
         ? []
         : [`${INDENT}${title}:`, ...lines.map((line) => `${INDENT}${INDENT}${line}`)];
 }
+/** How a condition's operator reads between its property and its value. */
+const CONDITION_OPERATORS = {
+    equals: "=",
+    notEquals: "!=",
+    gt: ">",
+    gte: ">=",
+    lt: "<",
+    lte: "<=",
+    contains: "contains",
+    startsWith: "starts with",
+    endsWith: "ends with",
+};
+function literal(value) {
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+/** `status = "won"`, `status in ("won", "invoiced")`, `amount >= 100`, `name contains "x"`. */
+function conditionText(condition, property) {
+    const { operator, value } = condition;
+    const values = Array.isArray(condition.values) ? condition.values : [];
+    const list = `(${values.map(literal).join(", ")})`;
+    switch (operator) {
+        case "in":
+            return `${property} in ${list}`;
+        case "notIn":
+            return `${property} not in ${list}`;
+        case "isNull":
+            return `${property} is null`;
+        case "isNotNull":
+            return `${property} is not null`;
+        case "between":
+            return `${property} between ${literal(values[0])} and ${literal(values[1])}`;
+        default: {
+            const symbol = CONDITION_OPERATORS[String(operator)] ?? String(operator);
+            return value === undefined
+                ? `${property} ${symbol}`
+                : `${property} ${symbol} ${literal(value)}`;
+        }
+    }
+}
+/** How an aggregate reads in a sentence: `count`, `sum of amount`. */
+const AGGREGATE_NAMES = {
+    count: "count",
+    sum: "sum",
+    countDistinct: "distinct count",
+    avg: "average",
+    min: "minimum",
+    max: "maximum",
+};
+/**
+ * Every aggregate a measure reads: its own, top-level or inside arithmetic, and those of the
+ * measures it references, followed once each.
+ */
+function readAggregates(entity, measure) {
+    const found = [];
+    const visited = new Set();
+    const visit = (expression, where, depth) => {
+        if (!isRecord(expression) || depth > 30) {
+            return;
+        }
+        const args = Array.isArray(expression.args) ? expression.args : [];
+        const name = AGGREGATE_NAMES[String(expression.op)];
+        if (expression.op === "filtered" && Array.isArray(expression.where)) {
+            const conditions = expression.where.filter(isRecord);
+            args.forEach((arg) => visit(arg, conditions, depth + 1));
+        }
+        else if (expression.op === "measure") {
+            const referenced = entity.measures?.find((other) => other.name === expression.name);
+            if (referenced !== undefined && !visited.has(referenced.name)) {
+                visited.add(referenced.name);
+                visit(referenced.expression, undefined, depth + 1);
+            }
+        }
+        else if (name !== undefined) {
+            const [argument] = args;
+            const column = isRecord(argument) && argument.op === "column" ? argument.name : undefined;
+            found.push({ name, column, where });
+        }
+        else {
+            args.forEach((arg) => visit(arg, where, depth + 1));
+        }
+    };
+    visited.add(measure.name);
+    visit(measure.expression, undefined, 0);
+    return found;
+}
+/**
+ * The columns a measure is a balance over: its own `balanceOver`, and that of every measure its
+ * expression references, since an expression is a balance when any measure it reads is.
+ */
+function balanceColumns(entity, measure) {
+    const columns = new Set();
+    const visited = new Set();
+    const visit = (candidate) => {
+        if (visited.has(candidate.name)) {
+            return;
+        }
+        visited.add(candidate.name);
+        if (candidate.balanceOver !== undefined) {
+            columns.add(candidate.balanceOver);
+        }
+        for (const name of referencedMeasures(candidate.expression)) {
+            const referenced = entity.measures?.find((other) => other.name === name);
+            if (referenced !== undefined) {
+                visit(referenced);
+            }
+        }
+    };
+    visit(measure);
+    return [...columns];
+}
+function referencedMeasures(expression) {
+    if (!isRecord(expression)) {
+        return [];
+    }
+    if (expression.op === "measure" && typeof expression.name === "string") {
+        return [expression.name];
+    }
+    return Array.isArray(expression.args) ? expression.args.flatMap(referencedMeasures) : [];
+}
+/**
+ * What a measure's definition adds to its description: the conditions its aggregates read rows by,
+ * and the property a balance must be grouped by or filtered to one day of. `Where …` only when every
+ * aggregate it reads, references followed, has the same conditions; otherwise a sentence per
+ * restricted aggregate. Columns read as the properties that map them, the names requests use.
+ */
+function measureNotes(entity, measure) {
+    const propertyOf = (column) => entity.properties.find((property) => (property.column ?? property.name) === column)?.name ??
+        String(column);
+    const aggregates = readAggregates(entity, measure).map(({ name, column, where }) => ({
+        name: column === undefined ? name : `${name} of ${propertyOf(column)}`,
+        conditions: where
+            ?.map((condition) => conditionText(condition, propertyOf(condition.column)))
+            .join(" and "),
+    }));
+    const conditions = aggregates.map((aggregate) => aggregate.conditions);
+    const [first] = conditions;
+    const balances = balanceColumns(entity, measure).map((column) => `Balance over ${propertyOf(column)}: group by it or filter it to one day.`);
+    // "Where" holds only when every aggregate, references followed, reads by the same condition.
+    if (first !== undefined && conditions.every((candidate) => candidate === first)) {
+        return [`Where ${first}.`, ...balances];
+    }
+    const restricted = aggregates.flatMap(({ name, conditions: text }) => text === undefined ? [] : [`Its ${name} reads rows where ${text}.`]);
+    return [...new Set(restricted), ...balances];
+}
+/**
+ * A measure's description followed by its conditions and balance note, as `describe`, the MCP
+ * measure list and the console show it: `Revenue of won orders. Where status = "won".`
+ */
+export function measureDescription(entity, measure) {
+    const notes = measureNotes(entity, measure);
+    if (notes.length === 0) {
+        return measure.description;
+    }
+    const described = measure.description === "" ? [] : [sentence(measure.description)];
+    return [...described, ...notes].join(" ");
+}
 function renderEntity(entity, manifest, entities, options) {
     const reader = options.as;
     const actions = entity.actions.filter((action) => reader === undefined ||
@@ -170,7 +326,7 @@ function renderEntity(entity, manifest, entities, options) {
             ? [`${INDENT}Source: ${entity.source.asset}; key: ${entity.source.key.join(", ")}.`]
             : []),
         ...section("Properties", entity.properties.flatMap((property) => propertyLines({ property, warehouseBacked: entity.source !== undefined }))),
-        ...section("Measures", (entity.measures ?? []).map((measure) => `${measure.name}: ${measure.description} (${measure.unit}).`)),
+        ...section("Measures", (entity.measures ?? []).map((measure) => `${measure.name}: ${measureDescription(entity, measure)} (${measure.unit}).`)),
         ...section("Relationships", relationshipLines(entity, entities, manifest.entities)),
         ...section(reader === undefined ? "Actions" : "Actions you may run", actions.flatMap((action) => actionLines(action, reader === undefined
             ? requirement("Requires", actionPermission(entity.name, action), manifest.roles)
@@ -273,7 +429,7 @@ export function renderAggregates(manifest, permissions) {
         const reaches = reachesOf(manifest, owner, permissions);
         return reaches.length === 0 ? [] : [reachLine(owner, reaches)];
     });
-    const measureLines = measures.map(({ name, measure }) => `${name} (${measure.unit}): ${sentence(measure.description)}`);
+    const measureLines = measures.map(({ name, entity, measure }) => `${name} (${measure.unit}): ${sentence(measureDescription(entity, measure))}`);
     return [
         `Aggregates: ${RECORDS_OR_AGGREGATES} (POST /api/ontology/aggregate, or the aggregate tool).`,
         `${INDENT}Measures, as <entity>.<measure>:`,

package/dist/service/mcp/server.js

@@ -6,7 +6,7 @@ import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { SCOPE_MISMATCH } from "../aggregate-platform.js";
 import { CurrentPrincipal, withPrincipal } from "../authentication.js";
 import { catalogFor } from "../catalog.js";
-import { describeCatalog, measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
+import { describeCatalog, measureDescription, measuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
 import { RequestId, errorBodyForWire, expectedFailure, internalError, schemaIssues, } from "../errors.js";
 import { publicOrigin } from "../oauth/protocol.js";
 import { mcpChallenge, mcpResource } from "../oauth/server.js";
@@ -287,7 +287,7 @@ function instructions({ built }, permissions) {
         return (definition.source === undefined && isAllowed(permissionOf(name, READ_VERB), { permissions }));
     })
         .map(({ name, resolved }) => `- ${name}: ${resolved.entity.definition.description}`);
-    const measures = measuresFor(manifest, permissions).map(({ name, measure }) => `- ${name}: ${measure.description}`);
+    const measures = measuresFor(manifest, permissions).map(({ name, entity, measure }) => `- ${name}: ${measureDescription(entity, measure)}`);
     return [
         "This server is the app's ontology: the records the company works with and the actions " +
             "that change them. Every change goes through an action, is checked against your " +

package/dist/service/mcp/tools.js

@@ -5,11 +5,11 @@ import { isValueMatched } from "../../manifest.js";
 import { GENERATED_UPSERT_PREFIX, humanize, mcpToolName } from "../../names.js";
 import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { queryJsonSchema } from "../../query.js";
-import { measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
+import { measureDescription, measuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
 import { uploadFields } from "../../storage/attachments.js";
 import { actionDescription, requires } from "../descriptions.js";
-import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, HistoryPage, Me, } from "../schemas.js";
+import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, AGGREGATE_PERIOD_UNITS, AGGREGATE_PERIODS, HistoryPage, MAXIMUM_TIMEZONE_LENGTH, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
 /**
  * A JSON Schema whose root is an object schema, as MCP requires of tool inputs and outputs: a root
@@ -243,11 +243,30 @@ const AGGREGATE_NAME = {
 const AGGREGATE_VALUE = {
     anyOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }],
 };
+/** `a, b or c`. */
+function alternatives(values) {
+    return values.length < 2
+        ? values.join("")
+        : `${values.slice(0, -1).join(", ")} or ${values[values.length - 1]}`;
+}
+const PERIODS = `${alternatives(AGGREGATE_PERIODS)}; or last N ${alternatives(AGGREGATE_PERIOD_UNITS)}, N at ` +
+    "least 1. Write a period exactly so: lowercase, single spaces, plural units even for 1 (last 1 " +
+    "days). last N days ends yesterday; last N weeks, months, quarters or years are whole units " +
+    "before the current one. Weeks start on Monday.";
+const FILTER_OPERATOR_DESCRIPTION = "equals, notEquals, gt, gte, lt, lte, contains, startsWith, endsWith and inPeriod take value; " +
+    "in, notIn and between take values; isNull and isNotNull take neither. notEquals and notIn also " +
+    "match null values and rows a route finds nothing for, so equals and notEquals together cover " +
+    "every row.";
+const FILTER_VALUE_DESCRIPTION = "equals, notEquals: the value. gt, gte, lt, lte: the bound, of a date, timestamp or number " +
+    "dimension; a date covers whole days on a timestamp. contains, startsWith, endsWith: a " +
+    "non-empty string, matched case-sensitively, without wildcards. inPeriod: a date or timestamp " +
+    `dimension's period, today being the date in the request's timezone: ${PERIODS}`;
 /** One `anyOf` branch per measure: a JSON Schema `enum` cannot describe its values. */
 function measureChoice({ name, entity, measure }) {
     return {
         const: name,
-        description: `${entity.label} · ${measure.label} (${measure.unit}): ${measure.description}`,
+        description: `${entity.label} · ${measure.label} (${measure.unit}): ` +
+            measureDescription(entity, measure),
     };
 }
 /** The aggregate tool's input for a caller: the request of `POST /api/ontology/aggregate`. */
@@ -280,15 +299,18 @@ function aggregateInput(measures) {
                     type: "object",
                     properties: {
                         dimension: AGGREGATE_NAME,
-                        operator: { enum: [...AGGREGATE_FILTER_OPERATORS] },
-                        value: { ...AGGREGATE_VALUE, description: "The value of equals." },
+                        operator: {
+                            enum: [...AGGREGATE_FILTER_OPERATORS],
+                            description: FILTER_OPERATOR_DESCRIPTION,
+                        },
+                        value: { ...AGGREGATE_VALUE, description: FILTER_VALUE_DESCRIPTION },
                         values: {
                             type: "array",
                             minItems: 1,
                             maxItems: AGGREGATE_LIMITS.values,
                             items: AGGREGATE_VALUE,
-                            description: "The values of in, or the two inclusive bounds of between, for example " +
-                                '["2026-09-01", "2026-09-30"].',
+                            description: "The values of in and notIn, or the two inclusive bounds of between, for example " +
+                                '["2026-09-01", "2026-09-30"]; dates cover whole days on a timestamp.',
                         },
                     },
                     required: ["dimension", "operator"],
@@ -297,9 +319,17 @@ function aggregateInput(measures) {
             },
             granularity: {
                 enum: [...AGGREGATE_GRANULARITIES],
-                description: "Buckets the date or timestamp dimension granularityOf names.",
+                description: "Buckets the date or timestamp dimension granularityOf names; hour applies to " +
+                    "timestamps only. Weeks start on Monday.",
             },
             granularityOf: { ...AGGREGATE_NAME, description: "A requested date or timestamp dimension." },
+            timezone: {
+                type: "string",
+                maxLength: MAXIMUM_TIMEZONE_LENGTH,
+                description: "An IANA timezone, such as Europe/Moscow, or UTC. Buckets of timestamps, date bounds on " +
+                    "timestamps and inPeriod's today follow it; without it, the timezone of the entity that " +
+                    "owns the dimension.",
+            },
             orderBy: {
                 type: "array",
                 maxItems: AGGREGATE_LIMITS.orderBy,
@@ -333,9 +363,14 @@ const AGGREGATE_DESCRIPTION = "Numbers about the model: measures from one or sev
     '"values": ["2026-09-01", "2026-09-30"]}]}\n' +
     '- September units sold beside units in stock, by status: {"measures": ["sales.units", ' +
     '"stock.on_hand"], "dimensions": ["product.status"], "filters": [{"dimension": ' +
-    '"sales.order_date", "operator": "between", "values": ["2026-09-01", "2026-09-30"]}]}\n\n' +
-    "Partitioned warehouse entities require a between filter on their date property; the error " +
-    "names it. Currency measures need a single-currency filter. " +
+    '"sales.order_date", "operator": "between", "values": ["2026-09-01", "2026-09-30"]}]}\n' +
+    '- Won orders in the last 4 weeks by week: {"measures": ["sales.won_orders"], "dimensions": ' +
+    '["sales.order_date"], "granularity": "week", "granularityOf": "sales.order_date", "filters": ' +
+    '[{"dimension": "sales.order_date", "operator": "inPeriod", "value": "last 4 weeks"}]}\n\n' +
+    "Partitioned warehouse entities require a between or inPeriod filter on their date property; " +
+    "the error names it. Currency measures need a single-currency filter, unless the measure is " +
+    "pinned to one currency. Use inPeriod for relative dates; the answer's execution.periods says " +
+    "which dates were used. " +
     "Answers come from the warehouse, and stored records from its replica: execution.sources says " +
     "how fresh each is, and execution.warnings says when a filter did not apply to a measure. " +
     "Requires reading every entity the request reads, path intermediates included. Call describe " +