@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/storage/tables.d.ts

@@ -0,0 +1,54 @@
+/** Storage metadata lives in the ontology database and is migrated by its SDK. */
+export declare const BLOB_TABLES_DDL: ReadonlyArray<string>;
+/** The agent's temporary attachments, beside the blob tables whose storage they share. */
+export declare const ATTACHMENTS_TABLE = "_agent_attachments";
+/**
+ * Where an attachment comes from: a chat message, or a file the agent produced in its sandbox and
+ * stores so that an action can keep it.
+ */
+export declare const ATTACHMENT_SOURCES: readonly ["telegram", "sandbox"];
+/** The check that limits `source` to {@link ATTACHMENT_SOURCES}; its name is PostgreSQL's default. */
+export declare const ATTACHMENT_SOURCE_CHECK = "_agent_attachments_source_check";
+/**
+ * A file a member sent the app's agent: platform metadata, never an ontology record. The bytes are
+ * a `_blobs` revision in the same storage as uploads; the row binds them to their owner, the chat
+ * and, for private chats, the first agent session that reads them. Group access follows the chat
+ * registry's current members. Attachments expire 24 hours after receipt unless promoted.
+ */
+export declare const ATTACHMENT_TABLES_DDL: ReadonlyArray<string>;
+/** The pending and started workflow starts of action triggers, beside the blob action results. */
+export declare const WORKFLOW_STARTS_TABLE = "_workflow_starts";
+/**
+ * The nil uuid: `record_id` is null when a trigger fires once for the action, for the record its
+ * input names, and the uniqueness index reads null as this value.
+ */
+export declare const NIL_RECORD_ID = "00000000-0000-0000-0000-000000000000";
+/**
+ * One row per start an action trigger decided in an action's transaction: the durable decision to
+ * start `workflow` with `input`, in its wire form as the cron route receives it. `run_id` is set
+ * once the Workflow SDK accepted the run; a row without one is pending, and the sweep starts it.
+ *
+ * A primary key cannot hold the null `record_id` of a trigger that fires once for the action, so
+ * uniqueness per trigger, action and record is a unique index that reads null as the nil uuid.
+ */
+export declare const WORKFLOW_STARTS_DDL: ReadonlyArray<string>;
+/** The prompts workflows hand the app's agent with `agentTask`, beside the workflow starts. */
+export declare const AGENT_TASKS_TABLE = "_agent_tasks";
+/**
+ * One row per `agentTask` call, keyed by its Workflow SDK hook token. A task is `pending` until the
+ * agent accepts it, then `started`, and ends `completed`, `needs_input`, `failed` or `timed_out`;
+ * the first terminal outcome wins. Only the SHA-256 of the task's secret is stored. `result` holds
+ * the terminal outcome's fields: the agent's text and whether it was cut, or the failure's reason.
+ */
+export declare const AGENT_TASKS_DDL: ReadonlyArray<string>;
+/** The sign-in links actions asked to send with `User.sendSignInLink`, beside the agent tasks. */
+export declare const SIGN_IN_EMAILS_TABLE = "_sign_in_emails";
+/**
+ * One row per `User.sendSignInLink` call, written in the action's transaction. After the commit the
+ * ontology service asks the app's Neon Auth for a sign-in link to `return_to`, naming the row in
+ * the link's callback; Neon Auth posts the link to the platform's email webhook, which reads the
+ * row to send the workspace's `template` with `values`, or the platform's own email when `template`
+ * is null. `status` is `pending` until the request is made, then `requested`, or `failed` with the
+ * reason in `failure`. `sender_id` is the principal whose action asked, to whom replies go.
+ */
+export declare const SIGN_IN_EMAILS_DDL: ReadonlyArray<string>;

package/dist/storage/tables.js

@@ -0,0 +1,205 @@
+/** Storage metadata lives in the ontology database and is migrated by its SDK. */
+export const BLOB_TABLES_DDL = [
+    `CREATE TABLE IF NOT EXISTS "_blobs" (
+    "id" uuid PRIMARY KEY,
+    "branch_id" text NOT NULL,
+    "key" text NOT NULL UNIQUE,
+    "filename" text NOT NULL,
+    "content_type" text NOT NULL,
+    "size" bigint NOT NULL CHECK ("size" > 0),
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "state" text NOT NULL CHECK ("state" IN ('ready', 'retained', 'deleting', 'deleted')),
+    "entity_id" text,
+    "property_id" text,
+    "record_id" uuid
+  )`,
+    `CREATE TABLE IF NOT EXISTS "_blob_uploads" (
+    "id" uuid PRIMARY KEY,
+    "blob_id" uuid NOT NULL UNIQUE REFERENCES "_blobs" ("id"),
+    "principal_id" uuid NOT NULL REFERENCES "user" ("id"),
+    "branch_id" text NOT NULL,
+    "manifest_hash" text NOT NULL,
+    "action" text NOT NULL,
+    "entity_id" text NOT NULL,
+    "property_id" text NOT NULL,
+    "record_id" uuid,
+    "create_intent" uuid,
+    "filename" text NOT NULL,
+    "content_type" text NOT NULL,
+    "size" bigint NOT NULL CHECK ("size" > 0),
+    "provider_upload_id" text,
+    "state" text NOT NULL CHECK ("state" IN
+      ('initializing', 'uploading', 'completing', 'ready', 'consumed', 'canceled', 'deleting', 'deleted')),
+    "claim" uuid,
+    "claimed_at" timestamptz,
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "expires_at" timestamptz NOT NULL DEFAULT now() + interval '1 hour',
+    CHECK (("record_id" IS NULL) <> ("create_intent" IS NULL))
+  )`,
+    `CREATE INDEX IF NOT EXISTS "_blob_uploads_expiry_idx" ON "_blob_uploads" ("state", "expires_at")`,
+    `CREATE TABLE IF NOT EXISTS "_blob_references" (
+    "blob_id" uuid NOT NULL REFERENCES "_blobs" ("id"),
+    "entity_id" text NOT NULL,
+    "property_id" text NOT NULL,
+    "record_id" uuid NOT NULL,
+    "action_id" uuid NOT NULL,
+    PRIMARY KEY ("blob_id", "entity_id", "property_id", "record_id")
+  )`,
+    `CREATE TABLE IF NOT EXISTS "_blob_action_results" (
+    "principal_id" uuid NOT NULL REFERENCES "user" ("id"),
+    "key" text NOT NULL,
+    "fingerprint" text NOT NULL,
+    "outcome" jsonb,
+    PRIMARY KEY ("principal_id", "key")
+  )`,
+];
+/** The agent's temporary attachments, beside the blob tables whose storage they share. */
+export const ATTACHMENTS_TABLE = "_agent_attachments";
+/**
+ * Where an attachment comes from: a chat message, or a file the agent produced in its sandbox and
+ * stores so that an action can keep it.
+ */
+export const ATTACHMENT_SOURCES = ["telegram", "sandbox"];
+/** The check that limits `source` to {@link ATTACHMENT_SOURCES}; its name is PostgreSQL's default. */
+export const ATTACHMENT_SOURCE_CHECK = `${ATTACHMENTS_TABLE}_source_check`;
+const SOURCE_CHECK = `CHECK ("source" IN (${ATTACHMENT_SOURCES.map((source) => `'${source}'`).join(", ")}))`;
+/**
+ * A file a member sent the app's agent: platform metadata, never an ontology record. The bytes are
+ * a `_blobs` revision in the same storage as uploads; the row binds them to their owner, the chat
+ * and, for private chats, the first agent session that reads them. Group access follows the chat
+ * registry's current members. Attachments expire 24 hours after receipt unless promoted.
+ */
+export const ATTACHMENT_TABLES_DDL = [
+    `CREATE TABLE IF NOT EXISTS "${ATTACHMENTS_TABLE}" (
+    "id" uuid PRIMARY KEY,
+    "blob_id" uuid NOT NULL UNIQUE REFERENCES "_blobs" ("id"),
+    "branch_id" text NOT NULL,
+    "owner_id" uuid NOT NULL REFERENCES "user" ("id"),
+    "conversation" text NOT NULL,
+    "session_id" text,
+    "source" text NOT NULL CONSTRAINT "${ATTACHMENT_SOURCE_CHECK}" ${SOURCE_CHECK},
+    "source_ref" text NOT NULL,
+    "filename" text NOT NULL,
+    "content_type" text NOT NULL,
+    "size" bigint NOT NULL CHECK ("size" > 0),
+    "sha256" text NOT NULL CHECK ("sha256" ~ '^[0-9a-f]{64}$'),
+    "state" text NOT NULL CHECK ("state" IN ('received', 'ready', 'promoted', 'discarded', 'expired')),
+    "provider_upload_id" text,
+    "promotion" jsonb,
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "expires_at" timestamptz NOT NULL DEFAULT now() + interval '24 hours',
+    "removed_at" timestamptz,
+    UNIQUE ("owner_id", "conversation", "source_ref")
+  )`,
+    `CREATE INDEX IF NOT EXISTS "${ATTACHMENTS_TABLE}_expiry_idx" ON "${ATTACHMENTS_TABLE}" ("state", "expires_at")`,
+    `CREATE INDEX IF NOT EXISTS "${ATTACHMENTS_TABLE}_sha256_idx" ON "${ATTACHMENTS_TABLE}" ("sha256")`,
+    // @legacy ontology.pre-upgrade-database-tolerance
+    // A table an earlier SDK created accepts fewer sources; widen its check in place.
+    `ALTER TABLE "${ATTACHMENTS_TABLE}" DROP CONSTRAINT IF EXISTS "${ATTACHMENT_SOURCE_CHECK}", ` +
+        `ADD CONSTRAINT "${ATTACHMENT_SOURCE_CHECK}" ${SOURCE_CHECK}`,
+];
+/** The pending and started workflow starts of action triggers, beside the blob action results. */
+export const WORKFLOW_STARTS_TABLE = "_workflow_starts";
+/**
+ * The nil uuid: `record_id` is null when a trigger fires once for the action, for the record its
+ * input names, and the uniqueness index reads null as this value.
+ */
+export const NIL_RECORD_ID = "00000000-0000-0000-0000-000000000000";
+/**
+ * One row per start an action trigger decided in an action's transaction: the durable decision to
+ * start `workflow` with `input`, in its wire form as the cron route receives it. `run_id` is set
+ * once the Workflow SDK accepted the run; a row without one is pending, and the sweep starts it.
+ *
+ * A primary key cannot hold the null `record_id` of a trigger that fires once for the action, so
+ * uniqueness per trigger, action and record is a unique index that reads null as the nil uuid.
+ */
+export const WORKFLOW_STARTS_DDL = [
+    `CREATE TABLE IF NOT EXISTS "${WORKFLOW_STARTS_TABLE}" (
+    "trigger" text NOT NULL,
+    "action_id" uuid NOT NULL,
+    "record_id" uuid,
+    "workflow" text NOT NULL,
+    "input" jsonb NOT NULL,
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "run_id" text,
+    "started_at" timestamptz,
+    "attempts" integer NOT NULL DEFAULT 0
+  )`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS "${WORKFLOW_STARTS_TABLE}_key" ON "${WORKFLOW_STARTS_TABLE}" ` +
+        `("trigger", "action_id", COALESCE("record_id", '${NIL_RECORD_ID}'::uuid))`,
+    `CREATE INDEX IF NOT EXISTS "${WORKFLOW_STARTS_TABLE}_pending" ON "${WORKFLOW_STARTS_TABLE}" ` +
+        `("created_at") WHERE "run_id" IS NULL`,
+    `CREATE INDEX IF NOT EXISTS "${WORKFLOW_STARTS_TABLE}_workflow" ON "${WORKFLOW_STARTS_TABLE}" ` +
+        `("workflow", "created_at")`,
+    // @legacy ontology.workflow-cutover-artifacts
+    // Ontology SDKs 0.86.0 to 0.88.0 write this column and read `terminal_at` and the journal below.
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS admission_generation bigint`,
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS admission_deployment_id text`,
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS reservation jsonb`,
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS arguments jsonb`,
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS admission_attributes jsonb`,
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS provider_workflow_id text`,
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS terminal_at timestamptz`,
+    `ALTER TABLE "${WORKFLOW_STARTS_TABLE}" ADD COLUMN IF NOT EXISTS submission_lease_until timestamptz`,
+    // @legacy ontology.workflow-cutover-artifacts
+    `CREATE TABLE IF NOT EXISTS _workflow_admission (
+    id boolean PRIMARY KEY DEFAULT true CHECK(id),
+    generation bigint NOT NULL DEFAULT 1,
+    phase text NOT NULL DEFAULT 'open' CHECK(phase IN ('open','fenced','migrated','recovery')),
+    contract_hash text NOT NULL,catalog_hash text NOT NULL,
+    owner text,target_hash text,deadline timestamptz,drained_generation bigint,resume_phase text
+  )`,
+];
+/** The prompts workflows hand the app's agent with `agentTask`, beside the workflow starts. */
+export const AGENT_TASKS_TABLE = "_agent_tasks";
+/**
+ * One row per `agentTask` call, keyed by its Workflow SDK hook token. A task is `pending` until the
+ * agent accepts it, then `started`, and ends `completed`, `needs_input`, `failed` or `timed_out`;
+ * the first terminal outcome wins. Only the SHA-256 of the task's secret is stored. `result` holds
+ * the terminal outcome's fields: the agent's text and whether it was cut, or the failure's reason.
+ */
+export const AGENT_TASKS_DDL = [
+    `CREATE TABLE IF NOT EXISTS "${AGENT_TASKS_TABLE}" (
+    "id" uuid PRIMARY KEY,
+    "workflow" text NOT NULL,
+    "run_id" text NOT NULL,
+    "hook_token" text NOT NULL UNIQUE,
+    "secret_sha256" text NOT NULL UNIQUE CHECK ("secret_sha256" ~ '^[0-9a-f]{64}$'),
+    "prompt" text NOT NULL,
+    "status" text NOT NULL CHECK ("status" IN
+      ('pending', 'started', 'completed', 'needs_input', 'failed', 'timed_out')),
+    "result" jsonb,
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "started_at" timestamptz,
+    "finished_at" timestamptz,
+    "deadline_at" timestamptz NOT NULL
+  )`,
+    `CREATE INDEX IF NOT EXISTS "${AGENT_TASKS_TABLE}_deadline" ON "${AGENT_TASKS_TABLE}" ("deadline_at")`,
+];
+/** The sign-in links actions asked to send with `User.sendSignInLink`, beside the agent tasks. */
+export const SIGN_IN_EMAILS_TABLE = "_sign_in_emails";
+/**
+ * One row per `User.sendSignInLink` call, written in the action's transaction. After the commit the
+ * ontology service asks the app's Neon Auth for a sign-in link to `return_to`, naming the row in
+ * the link's callback; Neon Auth posts the link to the platform's email webhook, which reads the
+ * row to send the workspace's `template` with `values`, or the platform's own email when `template`
+ * is null. `status` is `pending` until the request is made, then `requested`, or `failed` with the
+ * reason in `failure`. `sender_id` is the principal whose action asked, to whom replies go.
+ */
+export const SIGN_IN_EMAILS_DDL = [
+    `CREATE TABLE IF NOT EXISTS "${SIGN_IN_EMAILS_TABLE}" (
+    "id" uuid PRIMARY KEY,
+    "user_id" uuid NOT NULL REFERENCES "user" ("id") ON DELETE CASCADE,
+    "email" text NOT NULL,
+    "template" text,
+    "values" jsonb NOT NULL,
+    "return_to" text NOT NULL,
+    "action_id" uuid NOT NULL,
+    "sender_id" uuid,
+    "status" text NOT NULL CHECK ("status" IN ('pending', 'requested', 'failed')),
+    "failure" text,
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "requested_at" timestamptz
+  )`,
+    `CREATE INDEX IF NOT EXISTS "${SIGN_IN_EMAILS_TABLE}_created" ON "${SIGN_IN_EMAILS_TABLE}" ("created_at")`,
+];

package/dist/storage/transfers.d.ts

@@ -0,0 +1,16 @@
+import { Effect, Stream, type Scope } from "effect";
+import { type ActionError } from "../errors.js";
+import type { TransferGrant } from "./provider.js";
+/** The storage grant owns the destination; the source is streamed with bounded backpressure. */
+export declare function uploadFile<E, R>(input: {
+    readonly grant: TransferGrant;
+    readonly size: number;
+    readonly source: Stream.Stream<Uint8Array, E, R>;
+    readonly fetch: typeof fetch;
+}): Effect.Effect<void, E | ActionError, R>;
+/** Opens a signed immutable revision; scope closure cancels unread or interrupted downloads. */
+export declare function openFile(input: {
+    readonly grant: TransferGrant;
+    readonly size: number;
+    readonly fetch: typeof fetch;
+}): Effect.Effect<Stream.Stream<Uint8Array, ActionError>, ActionError, Scope.Scope>;

package/dist/storage/transfers.js

@@ -0,0 +1,153 @@
+import { Deferred, Effect, Option, Stream } from "effect";
+import { ActionRejected } from "../errors.js";
+const TRANSFER_TIMEOUT_MS = 4 * 60 * 1000;
+/** Keep storage's explanation in diagnostics, redacting the signed grant's credential values. */
+function transferFailure(response, grant) {
+    return Effect.gen(function* () {
+        let detail = "";
+        let readCause;
+        const stream = response.body;
+        if (stream) {
+            yield* Effect.acquireUseRelease(Effect.sync(() => stream.getReader()), (reader) => Effect.tryPromise({
+                try: async () => {
+                    const chunks = [];
+                    let remaining = 65_536;
+                    while (remaining > 0) {
+                        const next = await reader.read();
+                        if (next.done) {
+                            break;
+                        }
+                        chunks.push(next.value.subarray(0, remaining));
+                        remaining -= next.value.length;
+                    }
+                    detail = Buffer.concat(chunks).toString("utf8");
+                },
+                catch: (cause) => cause,
+            }).pipe(Effect.timeout("5 seconds"), Effect.catch((cause) => Effect.sync(() => {
+                readCause = cause;
+            }))), (reader) => Effect.tryPromise({ try: () => reader.cancel(), catch: (cause) => cause }).pipe(Effect.timeout("1 second"), Effect.catch((cause) => Effect.logError("ontology.storage.response_cleanup_failed", cause)), Effect.ensuring(Effect.sync(() => reader.releaseLock()))));
+        }
+        const protectedValues = [grant.url, ...Object.values(grant.headers)];
+        for (const [name, value] of new URL(grant.url).searchParams) {
+            if (/signature|credential|token|key/i.test(name)) {
+                protectedValues.push(value);
+            }
+        }
+        for (const value of protectedValues.filter(Boolean)) {
+            detail = detail
+                .replaceAll(value, "[REDACTED]")
+                .replaceAll(encodeURIComponent(value), "[REDACTED]");
+        }
+        return new ActionRejected({
+            message: "file_transfer_failed",
+            cause: { status: response.status, detail, ...(readCause === undefined ? {} : { readCause }) },
+        });
+    });
+}
+/** The storage grant owns the destination; the source is streamed with bounded backpressure. */
+export function uploadFile(input) {
+    return Effect.scoped(Effect.gen(function* () {
+        let size = 0;
+        let ended = false;
+        let sourceFailure = Option.none();
+        const checked = input.source.pipe(Stream.tap((chunk) => Effect.suspend(() => {
+            size += chunk.byteLength;
+            return size <= input.size
+                ? Effect.void
+                : Effect.fail(new ActionRejected({ message: "file_size_mismatch" }));
+        })), Stream.concat(Stream.fromEffect(Effect.suspend(() => {
+            if (size !== input.size) {
+                return Effect.fail(new ActionRejected({ message: "file_size_mismatch" }));
+            }
+            ended = true;
+            return Effect.void;
+        })).pipe(Stream.drain)), Stream.tapError((error) => Effect.sync(() => {
+            sourceFailure = Option.some(error);
+        })));
+        const stopped = yield* Deferred.make();
+        const finished = yield* Deferred.make();
+        const body = yield* Stream.toReadableStreamEffect(checked.pipe(Stream.interruptWhen(Deferred.await(stopped)), Stream.ensuring(Deferred.succeed(finished, undefined))), {
+            strategy: { highWaterMark: 1 },
+        });
+        yield* Effect.addFinalizer(() => Effect.gen(function* () {
+            yield* Deferred.succeed(stopped, undefined);
+            yield* Deferred.await(finished).pipe(Effect.timeout("1 second"), Effect.catch((cause) => Effect.logError("ontology.storage.source_cleanup_failed", cause)));
+        }));
+        const controller = yield* Effect.acquireRelease(Effect.sync(() => new AbortController()), (controller) => Effect.sync(() => controller.abort()));
+        const response = yield* Effect.tryPromise({
+            try: (signal) => input.fetch(input.grant.url, {
+                method: "PUT",
+                headers: { ...input.grant.headers, "content-length": String(input.size) },
+                body,
+                duplex: "half",
+                redirect: "error",
+                signal: AbortSignal.any([
+                    signal,
+                    controller.signal,
+                    AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
+                ]),
+            }),
+            catch: (cause) => new ActionRejected({ message: "file_transfer_failed", cause }),
+        }).pipe(Effect.catch((error) => Option.isSome(sourceFailure) ? Effect.fail(sourceFailure.value) : Effect.fail(error)));
+        if (!response.ok) {
+            const error = yield* transferFailure(response, input.grant);
+            return yield* error;
+        }
+        yield* Effect.tryPromise({
+            try: () => response.body?.cancel() ?? Promise.resolve(),
+            catch: (cause) => cause,
+        }).pipe(Effect.catch((cause) => Effect.logError("ontology.storage.response_cleanup_failed", cause)));
+        if (!ended) {
+            return yield* new ActionRejected({
+                message: "file_transfer_failed",
+                cause: { status: response.status, ended },
+            });
+        }
+    }));
+}
+/** Opens a signed immutable revision; scope closure cancels unread or interrupted downloads. */
+export function openFile(input) {
+    return Effect.gen(function* () {
+        const controller = yield* Effect.acquireRelease(Effect.sync(() => new AbortController()), (controller) => Effect.sync(() => controller.abort()));
+        const response = yield* Effect.tryPromise({
+            try: (signal) => input.fetch(input.grant.url, {
+                method: "GET",
+                headers: input.grant.headers,
+                redirect: "error",
+                signal: AbortSignal.any([
+                    signal,
+                    controller.signal,
+                    AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
+                ]),
+            }),
+            catch: (cause) => new ActionRejected({ message: "file_transfer_failed", cause }),
+        });
+        const stream = response.body;
+        if (!response.ok) {
+            const error = yield* transferFailure(response, input.grant);
+            return yield* error;
+        }
+        if (!stream) {
+            return yield* new ActionRejected({
+                message: "file_transfer_failed",
+                cause: { status: response.status },
+            });
+        }
+        yield* Effect.addFinalizer(() => Effect.tryPromise({
+            try: () => (stream.locked ? Promise.resolve() : stream.cancel()),
+            catch: (cause) => cause,
+        }).pipe(Effect.catch((cause) => Effect.logError("ontology.storage.response_cleanup_failed", cause))));
+        let size = 0;
+        return Stream.fromReadableStream({
+            evaluate: () => stream,
+            onError: (cause) => new ActionRejected({ message: "file_transfer_failed", cause }),
+        }).pipe(Stream.tap((chunk) => Effect.suspend(() => {
+            size += chunk.byteLength;
+            return size <= input.size
+                ? Effect.void
+                : Effect.fail(new ActionRejected({ message: "file_size_mismatch" }));
+        })), Stream.concat(Stream.fromEffect(Effect.suspend(() => size === input.size
+            ? Effect.void
+            : Effect.fail(new ActionRejected({ message: "file_size_mismatch" })))).pipe(Stream.drain)));
+    });
+}

package/dist/storage/writes.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+import { Conflict } from "../errors.js";
+import type { StoredValues } from "../runtime.js";
+import type { EntityModel } from "../runtime/model.js";
+import type { WriteContext } from "../runtime/writes.js";
+/** Resolves tickets in the action's transaction. There is no provider I/O here. */
+export declare function resolveBlobWrites(context: WriteContext, entity: EntityModel, recordId: string, values: StoredValues, creating: boolean): Effect.Effect<Record<string, unknown>, Conflict | import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/storage/writes.js

@@ -0,0 +1,88 @@
+import { Effect } from "effect";
+import { authorizeBlobOperation } from "./authorization.js";
+import { generatedActionPermissions } from "../permissions.js";
+import { Conflict } from "../errors.js";
+import { isRecordId } from "../runtime/records.js";
+import { Params } from "../runtime/statement.js";
+/** Resolves tickets in the action's transaction. There is no provider I/O here. */
+export function resolveBlobWrites(context, entity, recordId, values, creating) {
+    return Effect.gen(function* () {
+        const resolved = { ...values };
+        for (const property of entity.manifest.properties.filter((field) => field.type === "blob")) {
+            const value = values[property.name];
+            if (value === undefined || value === null) {
+                continue;
+            }
+            const reject = () => new Conflict({
+                entity: entity.name,
+                property: property.name,
+                message: "This upload cannot be attached to this record.",
+            });
+            const uploadId = typeof value === "object" && "uploadId" in value ? value.uploadId : undefined;
+            if (typeof uploadId !== "string" ||
+                !isRecordId(uploadId) ||
+                !context.scope.branchId ||
+                !context.scope.principalId ||
+                !context.scope.blobActionKey) {
+                return yield* reject();
+            }
+            const [actionEntity, actionName] = context.scope.action.split(".");
+            const authored = context.model.ontology.entities
+                .find((item) => item.name === actionEntity)
+                ?.actions.find((item) => item.name === actionName);
+            yield* authorizeBlobOperation(context.model.ontology, {
+                unsafe: (statement, args) => {
+                    const params = new Params();
+                    // The authorization statements use positional parameters and no dynamic identifiers.
+                    for (const value of args) {
+                        params.add(value, "text");
+                    }
+                    return context.run(statement, params);
+                },
+            }, context.scope.principalId, authored ? [authored.permission] : generatedActionPermissions(actionEntity, actionName), context.scope.execution, context.scope.workflow).pipe(Effect.catchTag("PermissionDenied", () => Effect.fail(reject())));
+            const params = new Params();
+            const rows = yield* context.run(`SELECT u.*, b.id::text AS blob_id, b.filename, b.content_type, b.size::text AS size,
+          to_char(b.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at
+         FROM "_blob_uploads" u JOIN "_blobs" b ON b.id = u.blob_id
+         JOIN "user" p ON p.id = u.principal_id AND p.active = true
+         WHERE u.id = ${params.add(uploadId, "uuid")}
+           AND u.principal_id = ${params.add(context.scope.principalId, "uuid")}
+           AND u.branch_id = ${params.add(context.scope.branchId, "text")}
+           AND u.manifest_hash = ${params.add(context.model.ontology.manifest.hash, "text")}
+           AND u.action = ${params.add(context.scope.action, "text")}
+           AND u.entity_id = ${params.add(entity.manifest.id, "text")}
+           AND u.property_id = ${params.add(property.name, "text")}
+           AND u.state = 'ready' AND u.expires_at > now() AND b.state = 'ready'
+         FOR UPDATE OF u, b FOR SHARE OF p`, params);
+            const row = rows[0];
+            if (!row ||
+                (creating
+                    ? row.create_intent !== context.scope.createIntent
+                    : row.record_id !== recordId.toLowerCase())) {
+                return yield* reject();
+            }
+            const consume = new Params();
+            yield* context.run(`UPDATE "_blob_uploads" SET state = 'consumed'
+        WHERE id = ${consume.add(uploadId, "uuid")}`, consume);
+            const retain = new Params();
+            yield* context.run(`UPDATE "_blobs" SET state = 'retained',
+        entity_id = ${retain.add(entity.manifest.id, "text")},
+        property_id = ${retain.add(property.name, "text")}, record_id = ${retain.add(recordId, "uuid")}
+        WHERE id = ${retain.add(row.blob_id, "uuid")}`, retain);
+            const reference = new Params();
+            yield* context.run(`INSERT INTO "_blob_references"
+        (blob_id, entity_id, property_id, record_id, action_id) VALUES
+        (${reference.add(row.blob_id, "uuid")}, ${reference.add(entity.manifest.id, "text")},
+        ${reference.add(property.name, "text")}, ${reference.add(recordId, "uuid")},
+        ${reference.add(context.scope.actionId, "uuid")})`, reference);
+            resolved[property.name] = {
+                id: row.blob_id,
+                filename: row.filename,
+                contentType: row.content_type,
+                size: Number(row.size),
+                createdAt: row.created_at,
+            };
+        }
+        return resolved;
+    });
+}

package/dist/telegram.d.ts

@@ -0,0 +1,35 @@
+export declare const TELEGRAM_LINK_PREVIEWS: readonly ["external", "none", "all"];
+export type TelegramLinkPreviews = (typeof TELEGRAM_LINK_PREVIEWS)[number];
+/** Settings belong to the destination connection, independently of the source channel. */
+export interface TelegramPreviewSettings {
+    readonly connection: string;
+    readonly linkPreviews?: TelegramLinkPreviews;
+    readonly additionalOwnOrigins?: readonly string[];
+}
+export interface TelegramPreviewContext {
+    readonly settings?: TelegramPreviewSettings;
+    readonly ownOrigins?: readonly string[];
+}
+export interface TelegramLinkEntity {
+    readonly type: string;
+    readonly offset: number;
+    readonly length: number;
+    readonly url?: string;
+}
+/** Normalize HTTP(S) origins only; credential-bearing and non-web destinations are ineligible. */
+export declare function httpOrigin(value: string): string | undefined;
+export declare function isHttpOrigin(value: unknown): value is string;
+/** Also validates programmatic standalone service configuration. */
+export declare function validateTelegramPreviews(settings: TelegramPreviewSettings): void;
+/** Public, non-secret deployment metadata; no request headers or cross-tenant suffix matching. */
+export declare function telegramPreviewEnvironment(environment: Readonly<Record<string, string | undefined>>): {
+    readonly channels?: {
+        readonly telegram?: TelegramPreviewSettings;
+    };
+    readonly appOrigins: string[];
+};
+export declare function telegramMarkdownLinks(markdown: string): readonly string[];
+/** Visible URLs and hidden destinations, excluding formatted code and linked-label lookalikes. */
+export declare function telegramTextLinks(text: string, entities?: readonly TelegramLinkEntity[]): readonly string[];
+/** Explicit modern > explicit legacy > channel mode > external default. Never merge caller options. */
+export declare function telegramPreviewOptions(caller: Readonly<Record<string, unknown>>, links: readonly string[], context?: TelegramPreviewContext): Record<string, unknown>;