@segmentstream-cloud/ontology 0.22.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/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.22.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",