@segmentstream-cloud/ontology 0.15.0 → 0.17.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/apply.js

@@ -6,6 +6,7 @@ import { isNoopMigration } from "./model.js";
 import { planMigration } from "./plan.js";
 import { REPLICATION_DDL, REPLICATION_SCHEMA_VERSION, replicationEntityDdl, } from "../replication/schema.js";
 import { createReplicationBaseline } from "../replication/baseline.js";
+import { ATTACHMENTS_TABLE } from "../storage/tables.js";
 import { resolveReplicationSelection } from "../replication/model.js";
 import { AGENT_TABLES, API_KEYS_TABLE, CATALOG_TABLE, OAUTH_TABLES, USER_ROLES_TABLE, quoteIdentifier, quoteLiteral, } from "./storage.js";
 const CATALOG = quoteIdentifier(CATALOG_TABLE);
@@ -172,6 +173,7 @@ export const RUNTIME_TABLES = [
     API_KEYS_TABLE,
     ...OAUTH_TABLES,
     ...AGENT_TABLES,
+    ATTACHMENTS_TABLE,
 ];
 /**
  * The runtime tables the database has, for `planMigration`'s `existingTables`: a database that an

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/migrate/plan.js

@@ -1,5 +1,5 @@
 import { isValueMatched, } from "../manifest.js";
-import { BLOB_TABLES_DDL } from "../storage/tables.js";
+import { ATTACHMENTS_TABLE, ATTACHMENT_TABLES_DDL, BLOB_TABLES_DDL } from "../storage/tables.js";
 import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
 import { AGENT_TABLES, AGENT_TABLES_DDL, CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, OAUTH_TABLES, OAUTH_TABLES_DDL, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, blobForeignKey, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
 const GLOBAL_KINDS = new Set(["table", "type", "index"]);
@@ -94,13 +94,23 @@ export function planMigration(input) {
             }));
         }
     }
-    if (storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob")) &&
+    const storesFiles = storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob"));
+    if (storesFiles &&
         !current?.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))) {
         draft.runtimeTables.push(step({
             kind: "createCatalog",
             classification: "additive",
-            description: "Create the ontology's file revision and upload tables.",
-            sql: BLOB_TABLES_DDL,
+            description: "Create the ontology's file revision, upload and agent attachment tables.",
+            sql: [...BLOB_TABLES_DDL, ...ATTACHMENT_TABLES_DDL],
+        }));
+    }
+    else if (storesFiles && input.existingTables?.has(ATTACHMENTS_TABLE) === false) {
+        // File storage an earlier SDK created lacks the agent's attachments, added since.
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the agent's temporary attachment table beside the file tables.",
+            sql: ATTACHMENT_TABLES_DDL,
         }));
     }
     planDrops({ pairs, removedEntities, addedEntities, allowDrops, draft });

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/runtime/service-binding.js

@@ -3,6 +3,7 @@ import { Effect, Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import { neonBlobProvider } from "../storage/neon.js";
 import { maintainBlobStorage } from "../storage/maintenance.js";
+import { attachmentRuntime } from "../storage/attachments.js";
 import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
@@ -33,8 +34,10 @@ export function backendLayer(ontology, blobStorage) {
             ? yield* Effect.acquireRelease(Effect.sync(() => neonBlobProvider(binding)), (provider) => Effect.sync(() => provider.close?.()))
             : undefined;
         const blobs = provider ? blobRuntime(ontology, sql, provider) : undefined;
+        const attachments = provider ? attachmentRuntime(ontology, sql, provider) : undefined;
         return OntologyBackend.of({
             ...(blobs ? { blobs } : {}),
+            ...(attachments ? { attachments } : {}),
             ...(provider ? { maintainBlobs: maintainBlobStorage(sql, provider) } : {}),
             runAction: (input) => withSql(runAction(ontology, {
                 entity: input.entity,

package/dist/service/agent/attachments.d.ts

@@ -0,0 +1,37 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type TokenVerifier } from "../authentication.js";
+import type { AfterCommitHook } from "../config.js";
+import type { ConnectionTransportFactory } from "../connections.js";
+import { RequestId } from "../errors.js";
+import type { ApiPlan } from "../plan.js";
+import type { ReplicationKick } from "../replication.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+import type { AgentChannelFactory } from "./channel.js";
+/**
+ * The agent's temporary attachments over HTTP (`docs/agent.md`, "Attachments"). Only the
+ * deployment's runtime token reaches these routes, acting as the member in `X-SegmentStream-Act-As`
+ * while they are active and paired. The chat and the agent session come from the agent's runtime in
+ * `X-SegmentStream-Agent-Conversation` and `X-SegmentStream-Agent-Session`, never from the model's
+ * tool arguments; every operation is confined to that member, chat and session.
+ */
+export declare const ATTACHMENTS_PATH = "/api/ontology/agent/attachments";
+/** The chat an attachment belongs to, such as `telegram:12345`. */
+export declare const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
+/** The agent session the request comes from. */
+export declare const SESSION_HEADER = "x-segmentstream-agent-session";
+export interface AttachmentRoutesOptions {
+    readonly plan: ApiPlan;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
+    readonly agentChannel?: AgentChannelFactory | undefined;
+    readonly verifyToken: TokenVerifier;
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+}
+/**
+ * The attachment routes. Without file storage or the agent tables, or while runtime authentication
+ * is disabled, it serves nothing.
+ */
+export declare function attachmentsLayer(options: AttachmentRoutesOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;