@segmentstream-cloud/ontology 0.15.0 → 0.17.0

package/dist/service/schemas.js

@@ -1,10 +1,12 @@
 import { BlobValue } from "../blob.js";
 import { Schema, SchemaTransformation } from "effect";
 import { wireStruct } from "../wire.js";
+import { AGGREGATE_FILTER_OPERATORS, ENTITY_AGGREGATE_FILTER_OPERATORS, filterValuesIssue, MAXIMUM_FILTER_VALUES, } from "../aggregate-filters.js";
 import { isValueMatched, OntologyManifestWire } from "../manifest.js";
 import { entityQuerySchemas, queryLinks } from "../query.js";
 import { ValidationIssue as RuntimeValidationIssue } from "../runtime/errors.js";
 import { Edit, HistoryEntry as RuntimeHistoryEntry } from "../runtime/history.js";
+export { AGGREGATE_FILTER_OPERATORS, AGGREGATE_PERIOD_UNITS, AGGREGATE_PERIODS, ENTITY_AGGREGATE_FILTER_OPERATORS, } from "../aggregate-filters.js";
 /** `lead` → `Lead`, `pilot_request` → `PilotRequest`: component names in the OpenAPI document. */
 function pascalCase(name) {
     return name
@@ -312,54 +314,29 @@ export const AGGREGATE_LIMITS = {
     measures: 30,
     dimensions: 20,
     filters: 50,
-    values: 100,
+    values: MAXIMUM_FILTER_VALUES,
     orderBy: 50,
     rows: 1000,
 };
-export const AGGREGATE_FILTER_OPERATORS = [
-    "equals",
-    "in",
-    "isNull",
-    "isNotNull",
-    "between",
-];
-/** The operators of the per-entity shorthand, which bounds dates with `dateRange` instead. */
-export const ENTITY_AGGREGATE_FILTER_OPERATORS = ["equals", "in", "isNull", "isNotNull"];
-export const AGGREGATE_GRANULARITIES = ["day", "week", "month"];
+/**
+ * The granularities a date or timestamp dimension buckets by; `hour` applies to timestamps only.
+ */
+export const AGGREGATE_GRANULARITIES = ["hour", "day", "week", "month", "quarter", "year"];
+/** The longest `timezone` a request names. */
+export const MAXIMUM_TIMEZONE_LENGTH = 64;
 const AggregateValue = Schema.Union([Schema.String, Schema.Number, Schema.Boolean]);
-/** Which values each operator takes, with SegmentStream's own messages (`planner.ts`). */
-function filterValuesIssue(filter) {
-    const { operator, value, values } = filter;
-    switch (operator) {
-        case "equals":
-            return value === undefined || values !== undefined
-                ? "Equality filters require one value."
-                : undefined;
-        case "in":
-            return values === undefined ||
-                values.length === 0 ||
-                values.length > AGGREGATE_LIMITS.values ||
-                value !== undefined
-                ? "Membership filters require between 1 and 100 values."
-                : undefined;
-        case "between":
-            return value !== undefined || values?.length !== 2
-                ? "between needs two values in order."
-                : undefined;
-        default:
-            return value !== undefined || values !== undefined
-                ? "Null filters do not accept values."
-                : undefined;
-    }
-}
-function aggregateFilter(operators) {
+/**
+ * A filter of either request. Which values each operator takes is checked with SegmentStream's own
+ * messages (`filterValuesIssue`); whether they suit the dimension's type is SegmentStream's to check.
+ */
+function aggregateFilter(operators, descriptions) {
     const filter = closedStruct({
         dimension: Schema.String.annotate({
             description: "A property, or a path of to-one relationships ending in one.",
         }),
         operator: Schema.Literals(operators),
-        value: Schema.optionalKey(AggregateValue).annotate({ description: "The value of equals." }),
-        values: Schema.optionalKey(Schema.Array(AggregateValue).check(Schema.isMaxLength(AGGREGATE_LIMITS.values))).annotate({ description: "The values of in, or the two inclusive bounds of between." }),
+        value: Schema.optionalKey(AggregateValue).annotate({ description: descriptions.value }),
+        values: Schema.optionalKey(Schema.Array(AggregateValue).check(Schema.isMaxLength(AGGREGATE_LIMITS.values))).annotate({ description: descriptions.values }),
     }, "Unknown key; use dimension, operator, value and values");
     return filter.check(Schema.makeFilter((candidate) => filterValuesIssue(candidate) ?? true));
 }
@@ -374,6 +351,11 @@ const aggregateFields = {
     granularityOf: Schema.optionalKey(Schema.String).annotate({
         description: "The requested date or timestamp dimension that granularity buckets.",
     }),
+    timezone: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(MAXIMUM_TIMEZONE_LENGTH))).annotate({
+        description: "An IANA timezone, such as Europe/Moscow, or UTC. Buckets of timestamps, date bounds on " +
+            "timestamps and inPeriod's today follow it instead of each entity's timezone; measure " +
+            "conditions never do.",
+    }),
     orderBy: Schema.optionalKey(Schema.Array(AggregateOrder).check(Schema.isMaxLength(AGGREGATE_LIMITS.orderBy))),
     limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: AGGREGATE_LIMITS.rows }))).annotate({ description: "At most 1000 rows; 100 by default." }),
 };
@@ -389,9 +371,15 @@ export const AggregateRequest = closedStruct({
         description: "<entity>.<property>, or a route from a measure's entity: " +
             "<entity>.<relationship>[.<relationship>].<property>.",
     }),
-    filters: Schema.optionalKey(Schema.Array(aggregateFilter(AGGREGATE_FILTER_OPERATORS)).check(Schema.isMaxLength(AGGREGATE_LIMITS.filters))).annotate({ description: "All must hold." }),
+    filters: Schema.optionalKey(Schema.Array(aggregateFilter(AGGREGATE_FILTER_OPERATORS, {
+        value: "The value of equals and notEquals; the bound of gt, gte, lt and lte; a non-empty " +
+            "string for contains, startsWith and endsWith; the period of inPeriod, such as " +
+            "last 7 days.",
+        values: "The values of in and notIn, or the two inclusive bounds of between.",
+    })).check(Schema.isMaxLength(AGGREGATE_LIMITS.filters))).annotate({ description: "All must hold." }),
     ...aggregateFields,
-}, "Unknown key; use measures, dimensions, filters, granularity, granularityOf, orderBy and limit").annotate({ identifier: "AggregateRequest" });
+}, "Unknown key; use measures, dimensions, filters, granularity, granularityOf, timezone, orderBy " +
+    "and limit").annotate({ identifier: "AggregateRequest" });
 /**
  * `POST /api/ontology/<entity>/aggregate`: SegmentStream's per-entity request, unchanged. Names are
  * relative to the entity (`revenue`, `product.brand`), and `dateRange` bounds a partitioned entity.
@@ -409,10 +397,14 @@ export const EntityAggregateRequest = closedStruct({
         from: Schema.String.annotate({ format: "date" }),
         to: Schema.String.annotate({ format: "date" }),
     }, "Unknown key; use from and to")).annotate({ description: "Inclusive days of the entity's partition property." }),
-    filters: Schema.optionalKey(Schema.Array(aggregateFilter(ENTITY_AGGREGATE_FILTER_OPERATORS)).check(Schema.isMaxLength(AGGREGATE_LIMITS.filters))).annotate({ description: "All must hold." }),
+    filters: Schema.optionalKey(Schema.Array(aggregateFilter(ENTITY_AGGREGATE_FILTER_OPERATORS, {
+        value: "The value of equals and notEquals; the bound of gt, gte, lt and lte; a non-empty " +
+            "string for contains, startsWith and endsWith.",
+        values: "The values of in and notIn.",
+    })).check(Schema.isMaxLength(AGGREGATE_LIMITS.filters))).annotate({ description: "All must hold." }),
     ...aggregateFields,
 }, "Unknown key; use dimensions, measures, dateRange, filters, granularity, granularityOf, " +
-    "orderBy and limit").annotate({ identifier: "EntityAggregateRequest" });
+    "timezone, orderBy and limit").annotate({ identifier: "EntityAggregateRequest" });
 /** SegmentStream's answer to an aggregate, which the service forwards unchanged. */
 export const AggregateResult = Schema.Struct({
     fields: Schema.Array(Schema.Struct({
@@ -429,6 +421,10 @@ export const AggregateResult = Schema.Struct({
         filters: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
             description: "The filters the measure applied.",
         }),
+        balanceOver: Schema.optionalKey(Schema.String).annotate({
+            description: "The date or timestamp dimension a balance measure was grouped by or filtered to one " +
+                "day of.",
+        }),
     })),
     rows: Schema.Array(Schema.Record(Schema.String, Schema.NullOr(Schema.Union([Schema.String, Schema.Boolean])))),
     truncated: Schema.Boolean,
@@ -440,6 +436,13 @@ export const AggregateResult = Schema.Struct({
             description: "For example, a filter that did not apply to some measure's entity.",
         }),
         sources: Schema.optionalKey(Schema.Array(Schema.Struct({ entity: Schema.String, asOf: Schema.String }))).annotate({ description: "How fresh the replica of each stored entity read is." }),
+        periods: Schema.optionalKey(Schema.Array(Schema.Struct({
+            dimension: Schema.String,
+            value: Schema.String,
+            from: Schema.String.annotate({ format: "date" }),
+            to: Schema.String.annotate({ format: "date" }),
+            timezone: Schema.String,
+        }))).annotate({ description: "The inclusive dates each inPeriod filter used, in request order." }),
     }),
     deploymentId: Schema.NullOr(Schema.String),
     definitionDigest: Schema.String,

package/dist/service/service.js

@@ -4,6 +4,7 @@ import { HttpApiBuilder } from "effect/unstable/httpapi";
 import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-auth.js";
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
+import { attachmentsLayer } from "./agent/attachments.js";
 import { deployedAgentChannel } from "./agent/channel.js";
 import { agentLayer } from "./agent/server.js";
 import { makeAggregates } from "./aggregate.js";
@@ -116,7 +117,16 @@ export function createOntologyService(ontology, config) {
             agentChannel,
         }), oauthLayer({ verifyToken }));
     const agent = agentLayer({ verifyToken, verifyRuntime, exchangeSession });
-    const application = Layer.mergeAll(routes, mcp, agent, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
+    const attachments = attachmentsLayer({
+        plan: built.plan,
+        hooks,
+        connections,
+        replicate,
+        agentChannel,
+        verifyToken,
+        verifyRuntime,
+    });
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;
     return {

package/dist/storage/attachments.d.ts

@@ -0,0 +1,117 @@
+import { Effect, Schema } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { ActionRejected, Conflict, NotFound, type PermissionDenied } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import type { Principal } from "../runtime.js";
+import type { BlobProvider, TransferGrant } from "./provider.js";
+/**
+ * The agent's temporary attachments: a file a member sends the app's agent is stored once, as a
+ * `_blobs` revision in the ontology's private file storage, and belongs to that member, the chat it
+ * arrived in and the agent session that first reads it. Nothing about it is an ontology record. It
+ * expires 24 hours after receipt; within that time the member's agent may read it, discard it, or
+ * promote it into a record through an action, which adopts the same stored object without copying
+ * it. Every operation re-derives the owner, chat and session from the caller, never from input.
+ */
+/** The largest file the agent takes: what Telegram's Bot API lets a bot download. */
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** How long an attachment stays readable after it arrives; reads never extend it. */
+export declare const ATTACHMENT_TTL_HOURS = 24;
+/** Live attachments one member may hold at once, so a busy chat cannot fill the storage. */
+export declare const MAX_LIVE_ATTACHMENTS = 50;
+export declare const ATTACHMENT_SOURCES: readonly ["telegram"];
+/** Who asks, as the agent's runtime knows it: the member, their chat and the agent session. */
+export interface AttachmentCaller {
+    readonly principal: Principal;
+    /** The chat the attachment arrived in, such as `telegram:12345`. */
+    readonly conversation: string;
+    /**
+     * The agent session the request comes from. The first session that reads an attachment owns it;
+     * other sessions of the same chat, such as one after a reset, never see it.
+     */
+    readonly sessionId?: string;
+}
+export interface ReceiveAttachment {
+    readonly source: (typeof ATTACHMENT_SOURCES)[number];
+    /** Identifies the file at its source, such as the message and attachment index; retries reuse it. */
+    readonly sourceRef: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface AttachmentView {
+    readonly id: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly state: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly promotion: unknown;
+}
+export interface PromotionTarget {
+    /** The entity whose action adopts the file, such as `document`. */
+    readonly entity: string;
+    /** The action, such as `upload` or `create`. */
+    readonly action: string;
+    /** The action's input without the file; the field that takes the upload is filled in. */
+    readonly input: Readonly<Record<string, unknown>>;
+    /** The input field that takes the upload, when the action has more than one. */
+    readonly field?: string;
+    /** The record the action updates, for an action that sets the file on an existing record. */
+    readonly recordId?: string;
+}
+/** Runs the promotion's action as the caller, with the upload's options. */
+export type PromotionRunner = (input: {
+    readonly entity: string;
+    readonly action: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly options: {
+        readonly idempotencyKey: string;
+        readonly createIntent?: string;
+    };
+}) => Effect.Effect<{
+    readonly result: unknown;
+    readonly edits: ReadonlyArray<unknown>;
+}, unknown>;
+/** The fields of an action's input that take an upload, with the property each one writes. */
+export declare function uploadFields(input: Schema.Top): ReadonlyArray<{
+    readonly field: string;
+    readonly entity: string;
+    readonly property: string;
+}>;
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export declare function attachmentRuntime(ontology: Ontology, sql: SqlClient.SqlClient, provider: BlobProvider["Service"]): {
+    receive: (input: ReceiveAttachment, caller: AttachmentCaller) => Effect.Effect<{
+        attachment: AttachmentView;
+        upload?: undefined;
+    } | {
+        attachment: AttachmentView;
+        upload: TransferGrant;
+    }, ActionRejected | PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    complete: (id: string, caller: AttachmentCaller) => Effect.Effect<AttachmentView, ActionRejected | PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    list: (caller: AttachmentCaller) => Effect.Effect<AttachmentView[], PermissionDenied | import("effect/unstable/sql/SqlError").SqlError, never>;
+    read: (id: string, caller: AttachmentCaller) => Effect.Effect<{
+        attachment: AttachmentView;
+        download: TransferGrant;
+    }, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    discard: (id: string, caller: AttachmentCaller) => Effect.Effect<AttachmentView, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    promote: (id: string, target: PromotionTarget, caller: AttachmentCaller, run: PromotionRunner) => Effect.Effect<{
+        attachment: AttachmentView;
+        deduplicated: boolean;
+        result: {} | null;
+    }, unknown, never>;
+};
+export type AttachmentRuntime = ReturnType<typeof attachmentRuntime>;
+export type AttachmentFailure = ActionRejected | Conflict | NotFound | PermissionDenied;
+/**
+ * Expires attachments past their deadline and removes the bytes of every expired or discarded one
+ * that no record adopted. A revision a promotion ticket still points at is left to the upload
+ * maintenance, once the ticket is canceled. Runs from the storage maintenance schedule, so files
+ * expire while the agent is idle.
+ */
+export declare function maintainAttachments(sql: SqlClient.SqlClient, provider: BlobProvider["Service"], limit?: number): Effect.Effect<{
+    expired: number;
+    removed: number;
+}, import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;