@segmentstream-cloud/ontology 0.21.0 → 0.23.0

package/dist/render.js

@@ -1,4 +1,4 @@
-import { shortestRoutesFrom } from "./aggregate-routes.js";
+import { inputEntities, shortestRoutesFrom } from "./aggregate-routes.js";
 import { isAllowed, permissionOf, READ_VERB, rolesGranting } from "./permissions.js";
 import { REFERENCE_ANNOTATION } from "./property.js";
 /** What an action of the manifest requires; version 1 manifests leave it implicit. */
@@ -389,6 +389,51 @@ export function measuresFor(manifest, permissions) {
         measure,
     })));
 }
+/**
+ * The measures of the model whose every input entity the reader may read, in declaration order.
+ * Reading a model measure is reading its inputs. Without permissions, every one.
+ */
+export function modelMeasuresFor(manifest, permissions) {
+    return (manifest.measures ?? []).filter((measure) => inputEntities(measure).every((entity) => readable(entity, permissions)));
+}
+/** `a`, `a and b`, `a, b and c`. */
+function listed(values) {
+    return values.length < 2
+        ? values.join("")
+        : `${values.slice(0, -1).join(", ")} and ${values[values.length - 1]}`;
+}
+/**
+ * How one alignment group reads: `sales.order_date aligns with plans.month`, and for an entity
+ * without a counterpart `listings has no counterpart for sales.order_date`. Members follow the
+ * measure's input entities, whatever order the document keeps them in.
+ */
+function alignmentClauses(measure, group) {
+    const order = inputEntities(measure);
+    const members = Object.entries(group).sort(([left], [right]) => order.indexOf(left) - order.indexOf(right));
+    const present = members.flatMap(([entity, property]) => property === null ? [] : [`${entity}.${property}`]);
+    const absent = members.flatMap(([entity, property]) => (property === null ? [entity] : []));
+    const [first, ...rest] = present;
+    if (first === undefined) {
+        return [];
+    }
+    return [
+        ...(rest.length > 0 ? [`${first} aligns with ${listed(rest)}`] : []),
+        ...absent.map((entity) => `${entity} has no counterpart for ${first}`),
+    ];
+}
+/**
+ * A measure of the model as `describe`, the MCP tool and the instructions show it: its description,
+ * the entity measures it reads and how their properties align. `Ordered over planned units. Reads
+ * sales.ordered and plans.planned_units; sales.order_date aligns with plans.month.`
+ */
+export function modelMeasureDescription(measure) {
+    const clauses = [
+        `Reads ${listed(measure.inputs)}`,
+        ...measure.align.flatMap((group) => alignmentClauses(measure, group)),
+    ];
+    const described = measure.description === "" ? [] : [sentence(measure.description)];
+    return [...described, `${clauses.join("; ")}.`].join(" ");
+}
 /**
  * The entities one entity reaches, with the shortest routes to each: exactly the routes aggregate
  * resolution weighs ({@link shortestRoutesFrom}). Only then is the reader applied: a target they may
@@ -416,8 +461,9 @@ function reachLine(entity, reaches) {
     return `${entity} reaches ${targets.join(", ")}.`;
 }
 /**
- * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, and
- * per measure entity the entities it reaches. Empty when the reader may read no measure.
+ * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, the
+ * measures of the model whose every input they may read, and per measure entity the entities it
+ * reaches. Empty when the reader may read no measure.
  */
 export function renderAggregates(manifest, permissions) {
     const measures = measuresFor(manifest, permissions);
@@ -430,10 +476,17 @@ export function renderAggregates(manifest, permissions) {
         return reaches.length === 0 ? [] : [reachLine(owner, reaches)];
     });
     const measureLines = measures.map(({ name, entity, measure }) => `${name} (${measure.unit}): ${sentence(measureDescription(entity, measure))}`);
+    const modelLines = modelMeasuresFor(manifest, permissions).map((measure) => `${measure.name} (${measure.unit}): ${modelMeasureDescription(measure)}`);
     return [
         `Aggregates: ${RECORDS_OR_AGGREGATES} (POST /api/ontology/aggregate, or the aggregate tool).`,
         `${INDENT}Measures, as <entity>.<measure>:`,
         ...measureLines.map((line) => `${INDENT}${INDENT}${line}`),
+        ...(modelLines.length === 0
+            ? []
+            : [
+                `${INDENT}Measures of the model, by name:`,
+                ...modelLines.map((line) => `${INDENT}${INDENT}${line}`),
+            ]),
         ...(reachLines.length === 0
             ? []
             : [

package/dist/replication/baseline.d.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
 import type { OntologyManifest } from "../manifest.js";
 import { type ReplicationSelection, type ReplicationExclusion } from "./model.js";
@@ -9,6 +9,13 @@ export interface ReplicationTarget {
     readonly manifest: OntologyManifest;
     readonly selection: ReadonlyArray<ReplicationSelection>;
 }
+declare const ReplicationBaselineFailed_base: Schema.Class<ReplicationBaselineFailed, Schema.TaggedStruct<"ReplicationBaselineFailed", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/** An initial snapshot cannot be created with the requested state or record projection. */
+export declare class ReplicationBaselineFailed extends ReplicationBaselineFailed_base {
+}
 /** All baseline rows are committed with capture enablement; interrupted setup can safely resume. */
 export declare const createReplicationBaseline: (sql: SqlClient.SqlClient, input: {
     readonly generation: string;
@@ -16,4 +23,5 @@ export declare const createReplicationBaseline: (sql: SqlClient.SqlClient, input
     readonly exclusions?: ReadonlyArray<ReplicationExclusion>;
     readonly selection: ReadonlyArray<ReplicationSelection>;
     readonly newSource?: boolean;
-}) => Effect.Effect<ReplicationTarget, import("effect/unstable/sql/SqlError").SqlError, never>;
+}) => Effect.Effect<ReplicationTarget, ReplicationBaselineFailed | import("effect/unstable/sql/SqlError").SqlError, never>;
+export {};

package/dist/replication/baseline.js

@@ -1,26 +1,35 @@
 import { randomUUID } from "node:crypto";
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import { joinColumnNames, joinTableName, quoteIdentifier as qi, quoteLiteral as ql, tableName, } from "../migrate/storage.js";
 import { REPLICATION_RECORD_BYTES, validateReplicationSelection, } from "./model.js";
 import { snapshotExpression } from "./schema.js";
-const MAX_BASELINE_RECORDS = 50_000;
+/** An initial snapshot cannot be created with the requested state or record projection. */
+export class ReplicationBaselineFailed extends Schema.TaggedError()("ReplicationBaselineFailed", { message: Schema.String, cause: Schema.optionalKey(Schema.Unknown) }) {
+}
 /** All baseline rows are committed with capture enablement; interrupted setup can safely resume. */
 export const createReplicationBaseline = (sql, input) => sql.withTransaction(Effect.gen(function* () {
     yield* sql.unsafe("SET LOCAL statement_timeout = '30s'");
     yield* sql.unsafe("SET LOCAL lock_timeout = '5s'");
     const [state] = yield* sql.unsafe("SELECT source_id::text, revision::text, enabled FROM _ontology_replication WHERE id FOR UPDATE");
     if (!state) {
-        return yield* Effect.die(new Error("Run the ontology SDK migration before enabling replication."));
+        return yield* new ReplicationBaselineFailed({
+            message: "Run the ontology SDK migration before enabling replication.",
+        });
     }
     const existing = yield* sql.unsafe("SELECT * FROM _ontology_replication_targets WHERE generation = $1::uuid", [input.generation]);
     if (existing[0]) {
         return existing[0];
     }
     if (state.enabled) {
-        return yield* Effect.die(new Error("Pause replication before starting a new generation."));
+        return yield* new ReplicationBaselineFailed({
+            message: "Pause replication before starting a new generation.",
+        });
     }
     const manifest = input.manifest;
-    yield* Effect.sync(() => validateReplicationSelection(manifest, input.selection));
+    yield* Effect.try({
+        try: () => validateReplicationSelection(manifest, input.selection),
+        catch: (cause) => new ReplicationBaselineFailed({ message: "Invalid replication projection.", cause }),
+    });
     // Drain older SDK transactions that started before the compatibility fence was enabled.
     const tables = manifest.entities
         .filter((e) => e.source === undefined && !e.builtIn)
@@ -57,17 +66,17 @@ export const createReplicationBaseline = (sql, input) => sql.withTransaction(Eff
         JSON.stringify(manifest),
         JSON.stringify(input.selection),
     ]);
-    let total = 0;
     const baseline = (entityId, kind, records) => Effect.gen(function* () {
         // Keep the snapshot in PostgreSQL; large baselines must not fill a serverless process's heap.
-        const [size] = yield* sql.unsafe(`SELECT count(*)::int AS count, max(octet_length(payload::text)) AS largest
-          FROM (${records} LIMIT ${MAX_BASELINE_RECORDS + 1}) snapshot`);
-        total += size.count;
-        if (total > MAX_BASELINE_RECORDS) {
-            return yield* Effect.die(new Error("The replication baseline exceeds 50,000 records; use a bulk bootstrap."));
-        }
-        if ((size.largest ?? 0) > REPLICATION_RECORD_BYTES) {
-            return yield* Effect.die(new Error("A projected baseline record exceeds the replication size limit."));
+        const [size] = yield* sql.unsafe(`SELECT EXISTS (
+              SELECT 1 FROM (${records}) snapshot
+              WHERE octet_length(payload::text) > ${REPLICATION_RECORD_BYTES}
+            ) AS oversized`);
+        if (size.oversized) {
+            return yield* new ReplicationBaselineFailed({
+                message: `A projected baseline record exceeds ${REPLICATION_RECORD_BYTES} bytes; ` +
+                    "exclude large fields before enabling replication.",
+            });
         }
         yield* sql.unsafe(`INSERT INTO _ontology_replication_baselines (generation, event)
       SELECT $1::uuid, jsonb_build_object('source_id', $2::text, 'entity_id', $3::text,

package/dist/replication/migrate.d.ts

@@ -0,0 +1,6 @@
+import type { OntologyManifest } from "../manifest.js";
+import type { MigrationRefusal } from "../migrate/model.js";
+import type { ReplicationTarget } from "./baseline.js";
+import type { ReplicationSelection } from "./model.js";
+/** A live stream can change its projection only when retained JSON still describes current rows. */
+export declare function replicationMigrationRefusals(current: ReplicationTarget, manifest: OntologyManifest, selection: ReadonlyArray<ReplicationSelection>): ReadonlyArray<MigrationRefusal>;

package/dist/replication/migrate.js

@@ -0,0 +1,64 @@
+import { toSnakeCase } from "../names.js";
+import { queryFields } from "../query.js";
+/** A live stream can change its projection only when retained JSON still describes current rows. */
+export function replicationMigrationRefusals(current, manifest, selection) {
+    const refusals = [];
+    const refuse = (path, reason) => {
+        refusals.push({
+            code: "replication-rebuild-required",
+            path,
+            message: `${reason} Pause replication, apply the migration, then explicitly rebuild replication.`,
+        });
+    };
+    for (const previous of current.selection) {
+        const entity = current.manifest.entities.find((item) => item.id === previous.entityId);
+        const next = selection.find((item) => item.entityId === entity.id);
+        if (!next) {
+            refuse(entity.name, "Removing a replicated entity would discard its pending history.");
+            continue;
+        }
+        for (const field of previous.fields) {
+            if (!next.fields.includes(field)) {
+                refuse(`${entity.name}.${field}`, "Removing or renaming a replicated field would leave retained JSON under its old name.");
+            }
+        }
+        for (const relationship of previous.relationships ?? []) {
+            if (!next.relationships?.includes(relationship)) {
+                refuse(`${entity.name}.${relationship}`, "Removing a replicated relationship would leave its old edges in retained JSON.");
+            }
+        }
+    }
+    for (const next of selection) {
+        const entity = manifest.entities.find((item) => item.id === next.entityId);
+        const previousEntity = current.manifest.entities.find((item) => item.id === entity.id);
+        // A newly created table starts empty and all subsequent writes are captured normally.
+        if (!previousEntity) {
+            continue;
+        }
+        const previous = current.selection.find((item) => item.entityId === entity.id);
+        if (!previous) {
+            refuse(entity.name, "Previously excluded records are absent from retained JSON.");
+            continue;
+        }
+        const previousFields = new Set(queryFields(previousEntity).map((field) => field.name));
+        for (const field of next.fields.filter((name) => !previous.fields.includes(name))) {
+            const property = entity.properties.find((item) => item.name === field);
+            const renamed = property?.renamedFrom;
+            if (previousFields.has(field) ||
+                (renamed !== undefined &&
+                    (previousFields.has(renamed) || previousFields.has(toSnakeCase(renamed))))) {
+                refuse(`${entity.name}.${field}`, "Existing values are absent from this JSON field.");
+            }
+            else if (property?.default !== undefined && property.default !== null) {
+                refuse(`${entity.name}.${field}`, "Adding a field with a non-null default changes existing rows without captured writes.");
+            }
+        }
+        for (const relationship of next.relationships ?? []) {
+            if (!previous.relationships?.includes(relationship) &&
+                previousEntity.relationships.some((item) => item.name === relationship)) {
+                refuse(`${entity.name}.${relationship}`, "Previously excluded relationship edges are absent from retained JSON.");
+            }
+        }
+    }
+    return refusals;
+}

package/dist/replication/model.d.ts

@@ -1,5 +1,5 @@
 import { type OntologyManifest } from "../manifest.js";
-/** The resolved projection for one immutable generation. `id` is always included. */
+/** The current projection of a continuous replication stream. `id` is always included. */
 export interface ReplicationSelection {
     readonly entityId: string;
     readonly fields: ReadonlyArray<string>;

package/dist/replication/store.d.ts

@@ -1,14 +1,14 @@
 import { Effect } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
 import { type ReplicationEvent, type ReplicationSelection, type ReplicationExclusion } from "./model.js";
-import { type ReplicationTarget } from "./baseline.js";
+import { ReplicationBaselineFailed, type ReplicationTarget } from "./baseline.js";
 export type { ReplicationTarget } from "./baseline.js";
 export declare const startReplication: (sql: SqlClient.SqlClient, input: {
     readonly generation: string;
     readonly exclusions?: ReadonlyArray<ReplicationExclusion>;
     readonly selection?: ReadonlyArray<ReplicationSelection>;
     readonly newSource?: boolean;
-}) => Effect.Effect<ReplicationTarget, import("../index.js").CatalogInvalid | import("effect/unstable/sql/SqlError").SqlError, never>;
+}) => Effect.Effect<ReplicationTarget, import("../index.js").CatalogInvalid | ReplicationBaselineFailed | import("effect/unstable/sql/SqlError").SqlError, never>;
 export declare const activeReplicationTarget: (sql: SqlClient.SqlClient) => Effect.Effect<ReplicationTarget, import("effect/unstable/sql/SqlError").SqlError, never>;
 export declare const pauseReplication: (sql: SqlClient.SqlClient) => import("effect/unstable/sql/Statement").Statement<object>;
 export declare const replicationTarget: (sql: SqlClient.SqlClient, generation: string) => Effect.Effect<ReplicationTarget, import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/replication/store.js

@@ -2,17 +2,22 @@ import { Effect } from "effect";
 import { readCatalog } from "../migrate/apply.js";
 import { historyTableName, quoteIdentifier as qi } from "../migrate/storage.js";
 import { REPLICATION_BATCH_BYTES, REPLICATION_BATCH_SIZE, publishMessage, replicationEventId, resolveReplicationSelection, } from "./model.js";
-import { createReplicationBaseline } from "./baseline.js";
+import { createReplicationBaseline, ReplicationBaselineFailed, } from "./baseline.js";
 export const startReplication = (sql, input) => sql.withTransaction(Effect.gen(function* () {
     yield* sql.unsafe("SET LOCAL statement_timeout = '30s'");
     yield* sql.unsafe("SET LOCAL lock_timeout = '5s'");
     yield* sql.unsafe("SELECT id FROM _ontology_replication WHERE id FOR UPDATE");
     const manifest = yield* readCatalog({ sql });
     if (!manifest) {
-        return yield* Effect.die(new Error("The ontology has not been migrated."));
+        return yield* new ReplicationBaselineFailed({
+            message: "The ontology has not been migrated.",
+        });
     }
     const selection = input.selection ??
-        (yield* Effect.sync(() => resolveReplicationSelection(manifest, input.exclusions)));
+        (yield* Effect.try({
+            try: () => resolveReplicationSelection(manifest, input.exclusions),
+            catch: (cause) => new ReplicationBaselineFailed({ message: "Invalid replication exclusions.", cause }),
+        }));
     return yield* createReplicationBaseline(sql, { ...input, manifest, selection });
 }));
 export const activeReplicationTarget = (sql) => sql

package/dist/service/catalog.d.ts

@@ -1,7 +1,8 @@
 import { type OntologyManifest } from "../manifest.js";
 /**
  * The catalog for a reader: the manifest, with each entity's actions narrowed to the ones the given
- * permissions may run. Without permissions it is the manifest itself.
+ * permissions may run, and only the measures of the model whose every input entity they may read.
+ * Without permissions it is the manifest itself.
  */
 export declare function catalogFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): OntologyManifest;
 export interface GraphRelationship {

package/dist/service/catalog.js

@@ -1,16 +1,20 @@
 import { isValueMatched } from "../manifest.js";
 import { isAllowed } from "../permissions.js";
-import { actionPermission } from "../render.js";
+import { actionPermission, modelMeasuresFor } from "../render.js";
 /**
  * The catalog for a reader: the manifest, with each entity's actions narrowed to the ones the given
- * permissions may run. Without permissions it is the manifest itself.
+ * permissions may run, and only the measures of the model whose every input entity they may read.
+ * Without permissions it is the manifest itself.
  */
 export function catalogFor(manifest, permissions) {
     if (permissions === undefined) {
         return manifest;
     }
+    const { measures: declared, ...rest } = manifest;
+    const measures = declared === undefined ? [] : modelMeasuresFor(manifest, permissions);
     return {
-        ...manifest,
+        ...rest,
+        ...(measures.length === 0 ? {} : { measures }),
         entities: manifest.entities
             .filter((entity) => entity.source === undefined ||
             isAllowed(entity.permissions?.read ?? `${entity.name}:read`, { permissions }))

package/dist/service/mcp/server.js

@@ -7,7 +7,7 @@ import { SCOPE_MISMATCH } from "../aggregate-platform.js";
 import { CurrentPrincipal, withPrincipal } from "../authentication.js";
 import { catalogFor } from "../catalog.js";
 import { ConversationSearch } from "../agent/conversations.js";
-import { describeCatalog, measureDescription, measuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
+import { describeCatalog, measureDescription, measuresFor, modelMeasureDescription, modelMeasuresFor, 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";
@@ -313,7 +313,10 @@ 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, entity, measure }) => `- ${name}: ${measureDescription(entity, measure)}`);
+    const measures = [
+        ...measuresFor(manifest, permissions).map(({ name, entity, measure }) => `- ${name}: ${measureDescription(entity, measure)}`),
+        ...modelMeasuresFor(manifest, permissions).map((measure) => `- ${measure.name}: ${modelMeasureDescription(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

@@ -1,11 +1,11 @@
 import { Schema } from "effect";
 import { AGGREGATE_NAME_PATTERN } from "../../aggregate-routes.js";
 import { InvalidOntology } from "../../diagnostics.js";
-import { isValueMatched } from "../../manifest.js";
+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 { measureDescription, measuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
+import { measureDescription, measuresFor, modelMeasureDescription, modelMeasuresFor, 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";
@@ -281,8 +281,15 @@ function measureChoice({ name, entity, measure }) {
             measureDescription(entity, measure),
     };
 }
+/** A measure of the model, by its bare name, read only by a caller who may read every input. */
+function modelMeasureChoice(measure) {
+    return {
+        const: measure.name,
+        description: `Model · ${measure.label} (${measure.unit}): ` + modelMeasureDescription(measure),
+    };
+}
 /** The aggregate tool's input for a caller: the request of `POST /api/ontology/aggregate`. */
-function aggregateInput(measures) {
+function aggregateInput({ measures, model }) {
     return {
         type: "object",
         properties: {
@@ -291,9 +298,11 @@ function aggregateInput(measures) {
                 minItems: 1,
                 maxItems: AGGREGATE_LIMITS.measures,
                 uniqueItems: true,
-                items: { anyOf: measures.map(measureChoice) },
-                description: "What to compute, as <entity>.<measure>. Measures of several entities are each " +
-                    "computed over their own entity's rows, then combined on the dimensions.",
+                items: { anyOf: [...measures.map(measureChoice), ...model.map(modelMeasureChoice)] },
+                description: "What to compute, as <entity>.<measure>, or a measure of the model by its name. " +
+                    "Measures of several entities are each computed over their own entity's rows, then " +
+                    "combined on the dimensions; a measure of the model is computed on the combined rows " +
+                    "from the entity measures it reads.",
             },
             dimensions: {
                 type: "array",
@@ -385,17 +394,23 @@ const AGGREGATE_DESCRIPTION = "Numbers about the model: measures from one or sev
     "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 " +
-    "for the model's measures and relationships.";
+    "Requires reading every entity the request reads, path intermediates included, and every " +
+    "entity a measure of the model reads. A measure of the model is named without an entity; a " +
+    "filter must reach every entity it reads or none of them, unless its alignment gives an entity " +
+    "no counterpart. Call describe for the model's measures and relationships.";
 function aggregateTool(manifest) {
     return {
         name: "aggregate",
         title: "Aggregate measures",
         description: AGGREGATE_DESCRIPTION,
-        inputSchema: aggregateInput(measuresFor(manifest)),
+        inputSchema: aggregateInput({
+            measures: measuresFor(manifest),
+            model: modelMeasuresFor(manifest),
+        }),
         inputSchemaFor: (caller) => {
             const measures = measuresFor(manifest, caller.permissions);
-            return measures.length === 0 ? undefined : aggregateInput(measures);
+            const model = modelMeasuresFor(manifest, caller.permissions);
+            return measures.length === 0 ? undefined : aggregateInput({ measures, model });
         },
         annotations: READ,
         permissions: [],

package/dist/service/schemas.d.ts

@@ -268,6 +268,16 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
         readonly key: Schema.String;
         readonly description: 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 inputs: Schema.$Array<Schema.String>;
+        readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+    }>>>;
 }>, Schema.Struct<{
     readonly entities: Schema.toEncoded<Schema.$Array<Schema.encodeKeys<Schema.Struct<{
         readonly measures: Schema.optionalKey<Schema.$Array<Schema.encodeKeys<Schema.Struct<{
@@ -387,6 +397,16 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
         readonly key: Schema.String;
         readonly description: Schema.String;
     }>>>>;
+    readonly measures: Schema.toEncoded<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 inputs: Schema.$Array<Schema.String>;
+        readonly align: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>;
+    }>>>>;
 }>, never, never>;
 export declare const Graph: Schema.Struct<{
     readonly hash: Schema.String;
@@ -505,6 +525,7 @@ export declare const AggregateResult: Schema.Struct<{
         readonly additive: Schema.optionalKey<Schema.Boolean>;
         readonly filters: Schema.optionalKey<Schema.$Array<Schema.String>>;
         readonly balanceOver: Schema.optionalKey<Schema.String>;
+        readonly inputs: Schema.optionalKey<Schema.$Array<Schema.String>>;
     }>>;
     readonly rows: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Boolean]>>>>;
     readonly truncated: Schema.Boolean;

package/dist/service/schemas.js

@@ -366,7 +366,10 @@ const aggregateFields = {
 export const AggregateRequest = closedStruct({
     measures: Schema.Array(Schema.String)
         .check(Schema.isMaxLength(AGGREGATE_LIMITS.measures))
-        .annotate({ description: "<entity>.<measure>, at least one." }),
+        .annotate({
+        description: "<entity>.<measure>, or a measure of the model by its name, such as plan_attainment; " +
+            "at least one, at most 30 of both together.",
+    }),
     dimensions: Schema.optionalKey(Schema.Array(Schema.String).check(Schema.isMaxLength(AGGREGATE_LIMITS.dimensions))).annotate({
         description: "<entity>.<property>, or a route from a measure's entity: " +
             "<entity>.<relationship>[.<relationship>].<property>.",
@@ -408,7 +411,9 @@ export const EntityAggregateRequest = closedStruct({
 /** SegmentStream's answer to an aggregate, which the service forwards unchanged. */
 export const AggregateResult = Schema.Struct({
     fields: Schema.Array(Schema.Struct({
-        name: Schema.String.annotate({ description: "A dimension identity or <entity>.<measure>." }),
+        name: Schema.String.annotate({
+            description: "A dimension identity, <entity>.<measure>, or the name of a measure of the model.",
+        }),
         label: Schema.String,
         type: Schema.String,
         unit: Schema.optionalKey(Schema.String),
@@ -425,6 +430,10 @@ export const AggregateResult = Schema.Struct({
             description: "The date or timestamp dimension a balance measure was grouped by or filtered to one " +
                 "day of.",
         }),
+        inputs: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+            description: "The entity measures a measure of the model reads, <entity>.<measure>, in declaration " +
+                "order; present only on such a measure.",
+        }),
     })),
     rows: Schema.Array(Schema.Record(Schema.String, Schema.NullOr(Schema.Union([Schema.String, Schema.Boolean])))),
     truncated: Schema.Boolean,

package/dist/warehouse-backed.js

@@ -253,6 +253,10 @@ function checkMeasures(input) {
             !["decimal", "currency", "percent"].includes(measure.format)) {
             report("invalid-measure", field, "Invalid measure format.");
         }
+        if (measure.align !== undefined) {
+            report("invalid-measure", field, "Entity measures take no align; a measure that aligns the properties of several " +
+                "entities belongs in defineOntology({ measures }).");
+        }
         let remaining = 10_000;
         /** The balance properties of the measure's aggregates and of the measures it references. */
         const balances = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",