@segmentstream-cloud/ontology 0.15.0 → 0.17.0

package/dist/service/agent/attachments.js

@@ -0,0 +1,225 @@
+import { Cause, Effect, Layer, Redacted, Result, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { ATTACHMENT_SOURCES, } from "../../storage/attachments.js";
+import { schemaIssues } from "../../runtime/validation.js";
+import { CurrentPrincipal } from "../authentication.js";
+import { RequestId, errorBodyForWire, failureResponse, forbidden, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+import { identityToken, makeOperations } from "../operations.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { ACT_AS_HEADER, logRuntimeRejection, } from "../runtime-identity.js";
+import { AGENT_PATH } from "./server.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 const ATTACHMENTS_PATH = `${AGENT_PATH}/attachments`;
+/** The chat an attachment belongs to, such as `telegram:12345`. */
+export const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
+/** The agent session the request comes from. */
+export const SESSION_HEADER = "x-segmentstream-agent-session";
+const CONVERSATION = /^[a-z][a-z0-9_-]{0,31}:[A-Za-z0-9:_-]{1,200}$/;
+const SESSION = /^[A-Za-z0-9:_.-]{1,200}$/;
+const NO_STORE = { "cache-control": "no-store" };
+const Received = Schema.Struct({
+    source: Schema.Literals(ATTACHMENT_SOURCES),
+    source_ref: Schema.String,
+    filename: Schema.String,
+    content_type: Schema.String,
+    size: Schema.Int,
+    sha256: Schema.String,
+});
+const Promotion = Schema.Struct({
+    entity: Schema.String,
+    action: Schema.String,
+    input: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+    field: Schema.optionalKey(Schema.String),
+    record_id: Schema.optionalKey(Schema.String),
+});
+function json(body, status = 200) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: NO_STORE });
+}
+function attachmentForWire(attachment) {
+    return {
+        id: attachment.id,
+        filename: attachment.filename,
+        content_type: attachment.contentType,
+        size: attachment.size,
+        sha256: attachment.sha256,
+        state: attachment.state,
+        created_at: attachment.createdAt,
+        expires_at: attachment.expiresAt,
+        promotion: attachment.promotion,
+    };
+}
+function grantForWire(grant) {
+    return {
+        url: grant.url,
+        method: grant.method,
+        headers: grant.headers,
+        expires_at: grant.expiresAt,
+    };
+}
+function decodeBody(schema, request) {
+    return Effect.gen(function* () {
+        const text = yield* Effect.orDie(request.text);
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = undefined;
+        }
+        const decoded = yield* Effect.result(Schema.decodeUnknownEffect(schema)(body, { errors: "all", onExcessProperty: "error" }));
+        return Result.isFailure(decoded)
+            ? { ok: false, issues: schemaIssues(decoded.failure) }
+            : { ok: true, value: decoded.success };
+    });
+}
+function invalidBody(requestId, issues) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "invalid_request",
+        detail: "The request body is invalid.",
+        requestId,
+        issues: issues,
+    }), { status: 400 });
+}
+/** Answers a failure the way every other route does: expected ones by status, the rest as 500. */
+function answered(effect) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        return yield* effect.pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+            ? Effect.failCause(cause)
+            : failureResponse(cause, requestId)));
+    });
+}
+/**
+ * The attachment routes. Without file storage or the agent tables, or while runtime authentication
+ * is disabled, it serves nothing.
+ */
+export function attachmentsLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const attachments = backend.attachments;
+        const agents = backend.agents;
+        const verifyRuntime = options.verifyRuntime;
+        if (attachments === undefined || agents === undefined || verifyRuntime === undefined) {
+            return;
+        }
+        const operations = makeOperations(backend, options.plan, options.hooks, options.connections, options.replicate, options.agentChannel);
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        /** Authenticates the runtime, then the member it acts for, the chat and the session. */
+        const asAgent = (answer) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+            const token = Redacted.value(bearer);
+            const verified = token === "" ? undefined : yield* Effect.promise(() => verifyRuntime(token));
+            switch (verified?.status) {
+                case "valid":
+                    break;
+                case "invalid":
+                    yield* logRuntimeRejection(verified.reason);
+                    return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
+                case "unavailable":
+                    return toServerResponse(unavailable(requestId));
+                default:
+                    return toServerResponse(forbidden(requestId, "Only the app's agent calls this route."));
+            }
+            const actAs = request.headers[ACT_AS_HEADER]?.trim() ?? "";
+            const conversation = request.headers[CONVERSATION_HEADER]?.trim() ?? "";
+            const session = request.headers[SESSION_HEADER]?.trim() ?? "";
+            const member = actAs === "" ? undefined : yield* agents.actingMember(actAs);
+            if (member === undefined) {
+                return toServerResponse(forbidden(requestId, "The member is inactive or has not paired with the agent."));
+            }
+            if (!CONVERSATION.test(conversation) || (session !== "" && !SESSION.test(session))) {
+                return toServerResponse(forbidden(requestId, "The agent names the chat and session of every request."));
+            }
+            return yield* answer(request, {
+                principal: member,
+                conversation,
+                ...(session === "" ? {} : { sessionId: session }),
+            }, attachments);
+        });
+        const idOf = Effect.map(HttpRouter.params, (params) => params.id ?? "");
+        yield* router.add("POST", ATTACHMENTS_PATH, asAgent((request, caller, runtime) => answered(Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const body = yield* decodeBody(Received, request);
+            if (!body.ok) {
+                return invalidBody(requestId, body.issues);
+            }
+            const received = yield* runtime.receive({
+                source: body.value.source,
+                sourceRef: body.value.source_ref,
+                filename: body.value.filename,
+                contentType: body.value.content_type,
+                size: body.value.size,
+                sha256: body.value.sha256,
+            }, caller);
+            return json({
+                attachment: attachmentForWire(received.attachment),
+                ...(received.upload ? { upload: grantForWire(received.upload) } : {}),
+            }, 201);
+        }))));
+        yield* router.add("POST", `${ATTACHMENTS_PATH}/:id/complete`, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const attachment = yield* runtime.complete(yield* idOf, caller);
+            return json({ attachment: attachmentForWire(attachment) });
+        }))));
+        yield* router.add("GET", ATTACHMENTS_PATH, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const listed = yield* runtime.list(caller);
+            return json({ attachments: listed.map(attachmentForWire) });
+        }))));
+        yield* router.add("GET", `${ATTACHMENTS_PATH}/:id`, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const { attachment, download } = yield* runtime.read(yield* idOf, caller);
+            return json({
+                attachment: attachmentForWire(attachment),
+                download: grantForWire(download),
+            });
+        }))));
+        yield* router.add("POST", `${ATTACHMENTS_PATH}/:id/discard`, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const attachment = yield* runtime.discard(yield* idOf, caller);
+            return json({ attachment: attachmentForWire(attachment) });
+        }))));
+        yield* router.add("POST", `${ATTACHMENTS_PATH}/:id/promote`, asAgent((request, caller, runtime) => answered(Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const body = yield* decodeBody(Promotion, request);
+            if (!body.ok) {
+                return invalidBody(requestId, body.issues);
+            }
+            const promotion = body.value;
+            const promoted = yield* runtime.promote(yield* idOf, {
+                entity: promotion.entity,
+                action: promotion.action,
+                input: promotion.input ?? {},
+                ...(promotion.field === undefined ? {} : { field: promotion.field }),
+                ...(promotion.record_id === undefined ? {} : { recordId: promotion.record_id }),
+            }, caller, (call) => Effect.gen(function* () {
+                const planned = options.plan.entities.find((entity) => entity.name === call.entity);
+                const action = planned?.actions.find((item) => item.name === call.action);
+                if (planned === undefined || action === undefined) {
+                    return yield* Effect.die(new Error("The promotion's action was not planned."));
+                }
+                // The action runs as the member, with the after-commit hooks and connections
+                // of any other call.
+                const answer = yield* operations
+                    .runAction(planned, action, {
+                    input: call.input,
+                    validateOnly: false,
+                    options: call.options,
+                    identityToken: identityToken(request),
+                })
+                    .pipe(Effect.provideService(CurrentPrincipal, caller.principal), Effect.provideService(RequestId, requestId));
+                return { result: answer.result, edits: answer.edits };
+            }));
+            return json({
+                attachment: attachmentForWire(promoted.attachment),
+                deduplicated: promoted.deduplicated,
+                result: promoted.result,
+            });
+        }))));
+    }));
+}

package/dist/service/mcp/server.js

@@ -1,4 +1,4 @@
-import { Cause, Data, Effect, Layer, Option, Schema } from "effect";
+import { Cause, Data, Effect, Layer, Option, Schema, SchemaTransformation } from "effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
 import { encodeManifest } from "../../manifest.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";
@@ -14,7 +14,8 @@ import { identityToken, makeOperations, toQuery } from "../operations.js";
 import { OntologyBackend } from "../runtime-contract.js";
 import { runtimeCredential } from "../runtime-identity.js";
 import { ActionResponse, HistoryPage, HistoryParams, IdParam, Me, } from "../schemas.js";
-import { mcpTools, visibleTools } from "./tools.js";
+import { uploadFields } from "../../storage/attachments.js";
+import { ACTION_OPTIONS_ARGUMENT, mcpTools, visibleTools } from "./tools.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
 export const MCP_PATH = "/mcp";
 /** The MCP revisions the server speaks, newest first. */
@@ -66,6 +67,23 @@ function decodeArguments(schema, args) {
         onExcessProperty: "error",
     }).pipe(Effect.mapError((error) => new InvalidArguments({ issues: schemaIssues(error.issue) })));
 }
+/** The `_options` argument of an action tool that consumes an upload. */
+const McpActionOptions = Schema.Struct({
+    idempotency_key: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128))),
+    create_intent: Schema.optionalKey(Schema.String.check(Schema.isUUID())),
+}).pipe(Schema.decodeTo(Schema.Struct({
+    idempotencyKey: Schema.optionalKey(Schema.String),
+    createIntent: Schema.optionalKey(Schema.String),
+}), SchemaTransformation.transform({
+    decode: (value) => ({
+        ...(value.idempotency_key === undefined ? {} : { idempotencyKey: value.idempotency_key }),
+        ...(value.create_intent === undefined ? {} : { createIntent: value.create_intent }),
+    }),
+    encode: (value) => ({
+        ...(value.idempotencyKey === undefined ? {} : { idempotency_key: value.idempotencyKey }),
+        ...(value.createIntent === undefined ? {} : { create_intent: value.createIntent }),
+    }),
+})));
 /** What the service sends: a value encoded with the schema of the matching HTTP route. */
 function encoded(schema, value) {
     return Schema.encodeUnknownEffect(schema)(value).pipe(Effect.orDie);
@@ -178,9 +196,14 @@ function runTool({ built, operations, aggregate }, tool, args, request) {
                 return structured(yield* encoded(HistoryPage, yield* operations.history(target.planned, id, params)));
             }
             case "action": {
+                const { [ACTION_OPTIONS_ARGUMENT]: rawOptions, ...input } = args;
+                const options = rawOptions === undefined || uploadFields(target.action.action.input).length === 0
+                    ? undefined
+                    : yield* decodeArguments(McpActionOptions, rawOptions);
                 const answer = yield* operations.runAction(target.planned, target.action, {
-                    input: args,
+                    input: options === undefined ? args : input,
                     validateOnly: false,
+                    ...(options === undefined ? {} : { options }),
                     identityToken: identityToken(request),
                 });
                 return structured(yield* encoded(ActionResponse, answer));
@@ -264,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.d.ts

@@ -43,6 +43,12 @@ export interface McpTool {
     readonly inputSchemaFor?: (caller: PermissionHolder) => JsonSchemaObject | undefined;
     readonly target: McpToolTarget;
 }
+/**
+ * The argument an action that consumes an upload takes beside its input: the idempotency key the
+ * runtime requires of it, and the create intent the upload was begun with. The service removes it
+ * before the input is validated.
+ */
+export declare const ACTION_OPTIONS_ARGUMENT = "_options";
 /**
  * The MCP tools of an ontology: `describe` and `me`, `aggregate` when the ontology has measures,
  * then for every stored entity `find`, `get`,

package/dist/service/mcp/tools.js

@@ -5,10 +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
@@ -160,6 +161,37 @@ function readTools(planned, schemas, built) {
         },
     ];
 }
+/**
+ * The argument an action that consumes an upload takes beside its input: the idempotency key the
+ * runtime requires of it, and the create intent the upload was begun with. The service removes it
+ * before the input is validated.
+ */
+export const ACTION_OPTIONS_ARGUMENT = "_options";
+const ACTION_OPTIONS_SCHEMA = {
+    type: "object",
+    description: "Options of an action that stores an uploaded file: idempotency_key, required with an upload, " +
+        "and create_intent, the one the upload was begun with when it creates a record.",
+    properties: {
+        idempotency_key: { type: "string", minLength: 1, maxLength: 128 },
+        create_intent: { type: "string", format: "uuid" },
+    },
+    additionalProperties: false,
+};
+/** The input schema of an action tool; one that consumes an upload also takes its options. */
+function actionToolInput(action) {
+    const schema = rootObject(actionInputJsonSchema(action.input));
+    const properties = schema.properties;
+    if (uploadFields(action.input).length === 0 ||
+        schema.type !== "object" ||
+        properties === undefined ||
+        ACTION_OPTIONS_ARGUMENT in properties) {
+        return schema;
+    }
+    return {
+        ...schema,
+        properties: { ...properties, [ACTION_OPTIONS_ARGUMENT]: ACTION_OPTIONS_SCHEMA },
+    };
+}
 function actionTool(planned, plannedAction) {
     const { name, action, permissions } = plannedAction;
     const hints = hintsOf(planned, plannedAction);
@@ -167,7 +199,7 @@ function actionTool(planned, plannedAction) {
         name: mcpToolName(planned.name, name),
         title: `${planned.resolved.entity.definition.label}: ${humanize(name).toLowerCase()}`,
         description: actionDescription(plannedAction),
-        inputSchema: rootObject(actionInputJsonSchema(action.input)),
+        inputSchema: actionToolInput(action),
         annotations: {
             readOnlyHint: false,
             destructiveHint: hints.destructive,
@@ -211,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`. */
@@ -248,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"],
@@ -265,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,
@@ -301,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 " +

package/dist/service/runtime-contract.d.ts

@@ -1,4 +1,5 @@
 import { Context, Schema, type Effect, type Layer, type Redacted } from "effect";
+import type { AttachmentRuntime } from "../storage/attachments.js";
 import type { BlobRuntime } from "../storage/sessions.js";
 import type { BlobStorageBinding } from "../storage/provider.js";
 import type { AnyAction } from "../action.js";
@@ -247,6 +248,8 @@ export interface AgentStore {
 }
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
     readonly blobs?: BlobRuntime;
+    /** The agent's temporary attachments, on deployments with file storage. */
+    readonly attachments?: AttachmentRuntime;
     readonly maintainBlobs?: Effect.Effect<{
         readonly removed: number;
     }, unknown>;

package/dist/service/schemas.d.ts

@@ -1,5 +1,7 @@
 import { Schema } from "effect";
+import { AGGREGATE_FILTER_OPERATORS, ENTITY_AGGREGATE_FILTER_OPERATORS, type AggregateValue } from "../aggregate-filters.js";
 import type { ApiPlan } from "./plan.js";
+export { AGGREGATE_FILTER_OPERATORS, AGGREGATE_PERIOD_UNITS, AGGREGATE_PERIODS, ENTITY_AGGREGATE_FILTER_OPERATORS, } from "../aggregate-filters.js";
 /** A record id in a path: a UUID. */
 export declare const IdParam: Schema.String;
 /** The schemas of one entity's records and queries. */
@@ -149,6 +151,17 @@ export declare const ActionResponse: Schema.Struct<{
 }>;
 export declare const Catalog: Schema.decodeTo<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>>;
@@ -201,14 +214,6 @@ export declare const Catalog: Schema.decodeTo<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;
@@ -264,6 +269,17 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
     }>>>;
 }>, Schema.Struct<{
     readonly entities: Schema.toEncoded<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>>;
@@ -316,14 +332,6 @@ export declare const Catalog: Schema.decodeTo<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;
@@ -430,11 +438,12 @@ export declare const AGGREGATE_LIMITS: {
     readonly orderBy: 50;
     readonly rows: 1000;
 };
-export declare const AGGREGATE_FILTER_OPERATORS: readonly ["equals", "in", "isNull", "isNotNull", "between"];
-/** The operators of the per-entity shorthand, which bounds dates with `dateRange` instead. */
-export declare const ENTITY_AGGREGATE_FILTER_OPERATORS: readonly ["equals", "in", "isNull", "isNotNull"];
-export declare const AGGREGATE_GRANULARITIES: readonly ["day", "week", "month"];
-type AggregateValue = string | number | boolean;
+/**
+ * The granularities a date or timestamp dimension buckets by; `hour` applies to timestamps only.
+ */
+export declare const AGGREGATE_GRANULARITIES: readonly ["hour", "day", "week", "month", "quarter", "year"];
+/** The longest `timezone` a request names. */
+export declare const MAXIMUM_TIMEZONE_LENGTH = 64;
 interface AggregateFilter<Operator extends string> {
     readonly dimension: string;
     readonly operator: Operator;
@@ -458,6 +467,7 @@ export interface AggregateRequest {
     readonly filters?: ReadonlyArray<AggregateFilter<(typeof AGGREGATE_FILTER_OPERATORS)[number]>>;
     readonly granularity?: (typeof AGGREGATE_GRANULARITIES)[number];
     readonly granularityOf?: string;
+    readonly timezone?: string;
     readonly orderBy?: ReadonlyArray<AggregateOrdering>;
     readonly limit?: number;
 }
@@ -476,6 +486,7 @@ export interface EntityAggregateRequest {
     readonly filters?: ReadonlyArray<AggregateFilter<(typeof ENTITY_AGGREGATE_FILTER_OPERATORS)[number]>>;
     readonly granularity?: (typeof AGGREGATE_GRANULARITIES)[number];
     readonly granularityOf?: string;
+    readonly timezone?: string;
     readonly orderBy?: ReadonlyArray<AggregateOrdering>;
     readonly limit?: number;
 }
@@ -491,6 +502,7 @@ export declare const AggregateResult: Schema.Struct<{
         readonly implicit: Schema.optionalKey<Schema.Boolean>;
         readonly additive: Schema.optionalKey<Schema.Boolean>;
         readonly filters: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly balanceOver: Schema.optionalKey<Schema.String>;
     }>>;
     readonly rows: Schema.$Array<Schema.$Record<Schema.String, Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Boolean]>>>>;
     readonly truncated: Schema.Boolean;
@@ -503,6 +515,13 @@ export declare const AggregateResult: Schema.Struct<{
             readonly entity: Schema.String;
             readonly asOf: Schema.String;
         }>>>;
+        readonly periods: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly dimension: Schema.String;
+            readonly value: Schema.String;
+            readonly from: Schema.String;
+            readonly to: Schema.String;
+            readonly timezone: Schema.String;
+        }>>>;
     }>;
     readonly deploymentId: Schema.NullOr<Schema.String>;
     readonly definitionDigest: Schema.String;
@@ -549,4 +568,3 @@ export declare const ErrorSchemas: {
     connectionResponseInvalid: Schema.Top;
     connectionUnavailable: Schema.Top;
 };
-export {};