@segmentstream-cloud/ontology 0.15.0 → 0.16.0

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>;

package/dist/storage/attachments.js

@@ -0,0 +1,536 @@
+import { createHash, randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES } from "../blob.js";
+import { ActionRejected, Conflict, NotFound } from "../errors.js";
+import { canonicalJson } from "../manifest.js";
+import { actionInputJsonSchema } from "../runtime/generated-actions.js";
+import { resolveAction } from "../runtime/pipeline.js";
+import { authorizeBlobOperation } from "./authorization.js";
+import { ATTACHMENTS_TABLE } from "./tables.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 const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+/** How long an attachment stays readable after it arrives; reads never extend it. */
+export const ATTACHMENT_TTL_HOURS = 24;
+/** Live attachments one member may hold at once, so a busy chat cannot fill the storage. */
+export const MAX_LIVE_ATTACHMENTS = 50;
+export const ATTACHMENT_SOURCES = ["telegram"];
+const SHA256 = /^[0-9a-f]{64}$/;
+const SELECT = `SELECT a.id::text, a.blob_id::text, b.key, a.owner_id::text, a.conversation,
+  a.session_id, a.filename, a.content_type, a.size::text, a.sha256, a.state, a.provider_upload_id,
+  a.promotion,
+  to_char(a.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at,
+  to_char(a.expires_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS expires_at,
+  a.expires_at <= now() AS expired
+  FROM "${ATTACHMENTS_TABLE}" a JOIN "_blobs" b ON b.id = a.blob_id`;
+const READABLE = new Set(["ready", "promoted"]);
+/** The fields of an action's input that take an upload, with the property each one writes. */
+export function uploadFields(input) {
+    const schema = actionInputJsonSchema(input);
+    const definitions = (schema.$defs ?? {});
+    const resolve = (value, depth = 0) => {
+        if (typeof value !== "object" || value === null || depth > 8) {
+            return undefined;
+        }
+        const object = value;
+        const reference = object.$ref;
+        return typeof reference === "string" && reference.startsWith("#/$defs/")
+            ? resolve(definitions[reference.slice("#/$defs/".length)], depth + 1)
+            : object;
+    };
+    const binding = (value, depth = 0) => {
+        const object = resolve(value);
+        if (object === undefined || depth > 8) {
+            return undefined;
+        }
+        const annotation = object[BLOB_UPLOAD_ANNOTATION];
+        if (typeof annotation?.entity === "string" && typeof annotation.property === "string") {
+            return { entity: annotation.entity, property: annotation.property };
+        }
+        for (const key of ["anyOf", "oneOf", "allOf"]) {
+            const options = object[key];
+            if (Array.isArray(options)) {
+                for (const option of options) {
+                    const found = binding(option, depth + 1);
+                    if (found !== undefined) {
+                        return found;
+                    }
+                }
+            }
+        }
+        return undefined;
+    };
+    const root = resolve(schema);
+    const properties = (root?.properties ?? {});
+    return Object.entries(properties).flatMap(([field, value]) => {
+        const found = binding(value);
+        return found === undefined ? [] : [{ field, ...found }];
+    });
+}
+/** Whether the action's input has a top-level `sha256` field the bridge may fill in. */
+function takesSha256(input) {
+    const schema = actionInputJsonSchema(input);
+    const reference = schema.$ref;
+    const root = typeof reference === "string" && reference.startsWith("#/$defs/")
+        ? schema.$defs?.[reference.slice("#/$defs/".length)]
+        : schema;
+    const properties = root?.properties;
+    return properties !== undefined && "sha256" in properties;
+}
+function view(row) {
+    return {
+        id: row.id,
+        filename: row.filename,
+        contentType: row.content_type,
+        size: Number(row.size),
+        sha256: row.sha256,
+        state: row.expired && (row.state === "ready" || row.state === "received") ? "expired" : row.state,
+        createdAt: row.created_at,
+        expiresAt: row.expires_at,
+        promotion: row.promotion ?? null,
+    };
+}
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export function attachmentRuntime(ontology, sql, provider) {
+    const binding = provider.binding;
+    const missing = (id) => new NotFound({ entity: "attachment", id, message: "Attachment not found." });
+    const unavailable = (message) => new Conflict({ entity: "attachment", message });
+    /**
+     * The caller's attachment, locked. Another member's, another chat's or another session's is not
+     * found: it does not exist for this caller. The first session that loads it owns it.
+     */
+    const load = (id, caller, 
+    /** `source`: the webhook redelivering the file it stored, before or after a session read it. */
+    scope = "session") => Effect.gen(function* () {
+        if (!/^[0-9a-f-]{36}$/i.test(id)) {
+            return yield* missing(id);
+        }
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.id = $1::uuid AND a.owner_id = $2::uuid AND a.conversation = $3
+          AND a.branch_id = $4 FOR UPDATE OF a, b`, [id, caller.principal.id, caller.conversation, binding.branchId]);
+        const row = rows[0];
+        if (!row) {
+            return yield* missing(id);
+        }
+        if (scope === "session" && row.session_id !== null && row.session_id !== caller.sessionId) {
+            return yield* missing(id);
+        }
+        if (scope === "session" && row.session_id === null && caller.sessionId !== undefined) {
+            yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET session_id = $1 WHERE id = $2::uuid`, [
+                caller.sessionId,
+                row.id,
+            ]);
+        }
+        // The member must still be active; a deactivated member's agent reads nothing.
+        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+        return row;
+    });
+    /**
+     * Reserves the attachment and its revision, and answers where to put the bytes. A retry of the
+     * same source file answers the same attachment.
+     */
+    const receive = (input, caller) => Effect.gen(function* () {
+        if (!ATTACHMENT_SOURCES.includes(input.source) ||
+            input.sourceRef === "" ||
+            input.sourceRef.length > 200 ||
+            input.filename === "" ||
+            input.filename.length > 255 ||
+            /[\x00-\x1f\x7f/\\]/.test(input.filename) ||
+            !/^[\w.+-]+\/[\w.+-]+$/.test(input.contentType) ||
+            !Number.isInteger(input.size) ||
+            input.size <= 0 ||
+            !SHA256.test(input.sha256)) {
+            return yield* new ActionRejected({ message: "The attachment's metadata is invalid." });
+        }
+        if (input.size > MAX_ATTACHMENT_BYTES) {
+            return yield* new ActionRejected({
+                message: `The file is larger than the ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB the agent accepts.`,
+            });
+        }
+        const reserved = yield* sql.withTransaction(Effect.gen(function* () {
+            yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+            yield* sql.unsafe(`SELECT pg_advisory_xact_lock(818724)`);
+            const [existing] = yield* sql.unsafe(`SELECT id::text FROM "${ATTACHMENTS_TABLE}"
+             WHERE owner_id = $1::uuid AND conversation = $2 AND source_ref = $3`, [caller.principal.id, caller.conversation, input.sourceRef]);
+            if (existing) {
+                const row = yield* load(existing.id, caller, "source");
+                if (row.sha256 !== input.sha256 || Number(row.size) !== input.size) {
+                    return yield* unavailable("Another file was already received for this message.");
+                }
+                return row;
+            }
+            const [usage] = yield* sql.unsafe(`SELECT (SELECT coalesce(sum(size), 0)::text FROM "_blobs" WHERE state <> 'deleted') AS bytes,
+              (SELECT count(*)::text FROM "${ATTACHMENTS_TABLE}" WHERE owner_id = $1::uuid
+                AND state IN ('received', 'ready') AND expires_at > now()) AS live`, [caller.principal.id]);
+            if (Number(usage.bytes) + input.size > binding.quotaBytes ||
+                Number(usage.live) >= MAX_LIVE_ATTACHMENTS) {
+                return yield* new ActionRejected({
+                    message: "File storage capacity or the member's attachment limit is reached.",
+                });
+            }
+            const id = randomUUID();
+            const blobId = randomUUID();
+            yield* sql.unsafe(`INSERT INTO "_blobs" (id, branch_id, key, filename, content_type, size, state)
+             VALUES ($1::uuid, $2, $3, $4, $5, $6::bigint, 'ready')`, [
+                blobId,
+                binding.branchId,
+                `revisions/${blobId}`,
+                input.filename,
+                input.contentType,
+                input.size,
+            ]);
+            yield* sql.unsafe(`INSERT INTO "${ATTACHMENTS_TABLE}"
+             (id, blob_id, branch_id, owner_id, conversation, session_id, source, source_ref,
+               filename, content_type, size, sha256, state, expires_at)
+             VALUES ($1::uuid, $2::uuid, $3, $4::uuid, $5, $6, $7, $8, $9, $10, $11::bigint, $12,
+               'received', now() + make_interval(hours => ${ATTACHMENT_TTL_HOURS}))`, [
+                id,
+                blobId,
+                binding.branchId,
+                caller.principal.id,
+                caller.conversation,
+                caller.sessionId ?? null,
+                input.source,
+                input.sourceRef,
+                input.filename,
+                input.contentType,
+                input.size,
+                input.sha256,
+            ]);
+            return yield* load(id, caller);
+        }));
+        if (reserved.state !== "received" || reserved.expired) {
+            return { attachment: view(reserved) };
+        }
+        const pending = reserved.provider_upload_id
+            ? [reserved.provider_upload_id]
+            : yield* provider.pending(reserved.key);
+        const uploadId = pending[0] ??
+            (yield* provider.initiate({
+                key: reserved.key,
+                filename: reserved.filename,
+                contentType: reserved.content_type,
+                sessionId: reserved.id,
+            }));
+        if (reserved.provider_upload_id !== uploadId) {
+            yield* sql.withTransaction(sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET provider_upload_id = $1
+             WHERE id = $2::uuid AND state = 'received'`, [uploadId, reserved.id]));
+        }
+        const upload = yield* provider.signPart({
+            key: reserved.key,
+            uploadId,
+            partNumber: 1,
+            size: Number(reserved.size),
+        });
+        return { attachment: view(reserved), upload };
+    });
+    /** Completes the transfer, then verifies the stored bytes against the declared size and digest. */
+    const complete = (id, caller) => Effect.gen(function* () {
+        const row = yield* sql.withTransaction(load(id, caller));
+        if (row.state !== "received") {
+            return READABLE.has(row.state) && !row.expired
+                ? view(row)
+                : yield* unavailable("The attachment is no longer available.");
+        }
+        if (row.expired || !row.provider_upload_id) {
+            return yield* unavailable("The attachment's transfer did not start or has expired.");
+        }
+        let stored = yield* provider.inspect(row.key);
+        if (!stored) {
+            const parts = yield* provider.parts({ key: row.key, uploadId: row.provider_upload_id });
+            if (parts.length !== 1 || parts[0]?.number !== 1 || parts[0].size !== Number(row.size)) {
+                return yield* new ActionRejected({
+                    message: "The transferred file does not match its declared size.",
+                });
+            }
+            yield* provider.complete({ key: row.key, uploadId: row.provider_upload_id, parts });
+            stored = yield* provider.inspect(row.key);
+        }
+        const bytes = stored ? yield* provider.read(row.key, MAX_ATTACHMENT_BYTES) : undefined;
+        const digest = bytes ? createHash("sha256").update(bytes).digest("hex") : undefined;
+        if (!stored ||
+            stored.size !== Number(row.size) ||
+            stored.sessionId !== row.id ||
+            digest !== row.sha256) {
+            yield* sql.withTransaction(sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'discarded', expires_at = now()
+             WHERE id = $1::uuid AND state = 'received'`, [row.id]));
+            return yield* new ActionRejected({
+                message: "The transferred file does not match its declared size or digest.",
+            });
+        }
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'ready'
+             WHERE id = $1::uuid AND state = 'received'`, [row.id]);
+            return view(yield* load(row.id, caller));
+        }));
+    });
+    /** The caller's attachments in this chat and session that are still readable, newest first. */
+    const list = (caller) => sql.withTransaction(Effect.gen(function* () {
+        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.owner_id = $1::uuid AND a.conversation = $2 AND a.branch_id = $3
+             AND a.state IN ('ready', 'promoted') AND a.expires_at > now()
+             AND (a.session_id IS NULL OR a.session_id = $4)
+           ORDER BY a.created_at DESC LIMIT ${MAX_LIVE_ATTACHMENTS}`, [caller.principal.id, caller.conversation, binding.branchId, caller.sessionId ?? null]);
+        return rows.map(view);
+    }));
+    /**
+     * A one-minute grant to read the attachment's bytes, for the agent's runtime only. An expired,
+     * discarded or unfinished attachment cannot be read.
+     */
+    const read = (id, caller) => Effect.gen(function* () {
+        const row = yield* sql.withTransaction(load(id, caller));
+        if (!READABLE.has(row.state) || row.expired) {
+            return yield* unavailable("The attachment expired or was discarded.");
+        }
+        const download = yield* provider.download({
+            key: row.key,
+            filename: row.filename,
+            contentType: row.content_type,
+            inline: false,
+        });
+        return { attachment: view(row), download };
+    });
+    /** Revokes the caller's access at once; maintenance removes the bytes. */
+    const discard = (id, caller) => sql.withTransaction(Effect.gen(function* () {
+        const row = yield* load(id, caller);
+        if (row.state === "promoted") {
+            return yield* unavailable("The attachment was promoted; its file belongs to the record.");
+        }
+        if (row.state === "received" || row.state === "ready") {
+            yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'discarded', expires_at = now()
+             WHERE id = $1::uuid`, [row.id]);
+            // A ticket a failed promotion left behind goes with it.
+            yield* sql.unsafe(`UPDATE "_blob_uploads" SET state = 'canceled', expires_at = now(), claim = NULL
+             WHERE blob_id = $1::uuid AND state = 'ready'`, [row.blob_id]);
+        }
+        return view(yield* load(row.id, caller));
+    }));
+    /**
+     * Adopts the attachment's stored object into a record through an action, as the caller and with
+     * their permissions: a completed upload ticket is minted on the existing revision, and the action
+     * consumes it in its own transaction. Nothing is copied or uploaded again. A file whose SHA-256
+     * an earlier attachment already promoted through the same action is not promoted twice: the
+     * earlier promotion is the answer. A retry with the same target replays the action's outcome.
+     */
+    const promote = (id, target, caller, run) => Effect.gen(function* () {
+        const found = resolveAction(ontology, target.entity, target.action);
+        if (!found) {
+            return yield* new ActionRejected({
+                message: `${target.entity}.${target.action} is not an action of the ontology.`,
+            });
+        }
+        const fields = uploadFields(found.action.input).filter((candidate) => target.field === undefined || candidate.field === target.field);
+        if (fields.length !== 1) {
+            const where = target.field === undefined ? "" : ` in ${target.field}`;
+            return yield* new ActionRejected({
+                message: fields.length === 0
+                    ? `${target.entity}.${target.action} takes no file${where}.`
+                    : `${target.entity}.${target.action} takes several files; name the field.`,
+            });
+        }
+        const field = fields[0];
+        const fileEntity = ontology.manifest.entities.find((item) => item.name === field.entity);
+        const property = fileEntity?.properties.find((item) => item.name === field.property && item.type === "blob");
+        if (!fileEntity || fileEntity.source || !property) {
+            return yield* new ActionRejected({ message: "The action's file field is invalid." });
+        }
+        if (target.recordId !== undefined && !/^[0-9a-f-]{36}$/i.test(target.recordId)) {
+            return yield* new ActionRejected({ message: "The record id is invalid." });
+        }
+        if (field.field in target.input) {
+            return yield* new ActionRejected({
+                message: `Leave ${field.field} out of the input; the attachment fills it.`,
+            });
+        }
+        const qualified = `${target.entity}.${target.action}`;
+        const prepared = yield* sql.withTransaction(Effect.gen(function* () {
+            const row = yield* load(id, caller);
+            if (row.state === "promoted") {
+                return { kind: "done", row };
+            }
+            if (row.state !== "ready" || row.expired) {
+                return yield* unavailable("The attachment expired or was discarded.");
+            }
+            if (!property.accept?.includes(row.content_type) ||
+                Number(row.size) > (property.maxBytes ?? MAX_BLOB_BYTES)) {
+                return yield* new ActionRejected({
+                    message: `${field.entity}.${field.property} accepts ${(property.accept ?? []).join(", ")} ` +
+                        `up to ${property.maxBytes ?? MAX_BLOB_BYTES} bytes; this file is ` +
+                        `${row.content_type}, ${row.size} bytes.`,
+                });
+            }
+            yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions);
+            const [earlier] = yield* sql.unsafe(`SELECT id::text, promotion FROM "${ATTACHMENTS_TABLE}"
+             WHERE sha256 = $1 AND branch_id = $2 AND state = 'promoted' AND id <> $3::uuid
+               AND promotion->>'action' = $4 AND promotion->>'deduplicated_from' IS NULL
+             ORDER BY created_at LIMIT 1`, [row.sha256, binding.branchId, row.id, qualified]);
+            if (earlier) {
+                const promotion = {
+                    ...earlier.promotion,
+                    deduplicated_from: earlier.id,
+                };
+                yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'promoted', promotion = $1::jsonb
+               WHERE id = $2::uuid`, [JSON.stringify(promotion), row.id]);
+                return { kind: "done", row: yield* load(row.id, caller) };
+            }
+            const [existing] = yield* sql.unsafe(`SELECT id::text, state, record_id::text, create_intent::text FROM "_blob_uploads"
+             WHERE blob_id = $1::uuid FOR UPDATE`, [row.blob_id]);
+            if (existing && existing.state === "consumed") {
+                // An earlier promotion committed but its answer was lost; the action replays it.
+                return { kind: "run", row, upload: existing };
+            }
+            if (existing && existing.state !== "ready") {
+                return yield* unavailable("The attachment's file is being removed.");
+            }
+            const upload = {
+                id: existing?.id ?? randomUUID(),
+                state: "ready",
+                record_id: target.recordId?.toLowerCase() ?? null,
+                create_intent: target.recordId === undefined ? randomUUID() : null,
+            };
+            const values = [
+                upload.id,
+                row.blob_id,
+                caller.principal.id,
+                binding.branchId,
+                ontology.manifest.hash,
+                qualified,
+                fileEntity.id,
+                property.name,
+                upload.record_id,
+                upload.create_intent,
+                row.filename,
+                row.content_type,
+                row.size,
+                row.id,
+            ];
+            if (existing) {
+                yield* sql.unsafe(`UPDATE "_blob_uploads" SET blob_id = $2::uuid, principal_id = $3::uuid,
+                 branch_id = $4, manifest_hash = $5, action = $6, entity_id = $7, property_id = $8,
+                 record_id = $9::uuid, create_intent = $10::uuid, filename = $11,
+                 content_type = $12, size = $13::bigint,
+                 expires_at = (SELECT expires_at FROM "${ATTACHMENTS_TABLE}" WHERE id = $14::uuid)
+               WHERE id = $1::uuid`, values);
+            }
+            else {
+                yield* sql.unsafe(`INSERT INTO "_blob_uploads"
+               (id, blob_id, principal_id, branch_id, manifest_hash, action, entity_id, property_id,
+                 record_id, create_intent, filename, content_type, size, state, expires_at)
+               VALUES ($1::uuid, $2::uuid, $3::uuid, $4, $5, $6, $7, $8, $9::uuid, $10::uuid, $11,
+                 $12, $13::bigint, 'ready',
+                 (SELECT expires_at FROM "${ATTACHMENTS_TABLE}" WHERE id = $14::uuid))`, values);
+            }
+            return { kind: "run", row, upload };
+        }));
+        if (prepared.kind === "done") {
+            return {
+                attachment: view(prepared.row),
+                deduplicated: Boolean(prepared.row.promotion?.deduplicated_from),
+                result: prepared.row.promotion?.result ?? null,
+            };
+        }
+        const { row, upload } = prepared;
+        const input = {
+            ...target.input,
+            [field.field]: { upload_id: upload.id },
+        };
+        if (!("sha256" in input) && takesSha256(found.action.input)) {
+            input.sha256 = row.sha256;
+        }
+        // The same attachment, target and input always run under the same key, so a retry replays.
+        const idempotencyKey = createHash("sha256")
+            .update(canonicalJson({ attachment: row.id, qualified, input }))
+            .digest("hex");
+        const outcome = yield* run({
+            entity: target.entity,
+            action: target.action,
+            input,
+            options: {
+                idempotencyKey,
+                ...(upload.create_intent === null ? {} : { createIntent: upload.create_intent }),
+            },
+        });
+        const promotion = {
+            action: qualified,
+            result: outcome.result ?? null,
+            promoted_at: new Date().toISOString(),
+        };
+        const promoted = yield* sql.withTransaction(Effect.gen(function* () {
+            yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'promoted', promotion = $1::jsonb
+             WHERE id = $2::uuid AND state = 'ready'`, [JSON.stringify(promotion), row.id]);
+            return yield* load(row.id, caller);
+        }));
+        return { attachment: view(promoted), deduplicated: false, result: outcome.result ?? null };
+    });
+    return { receive, complete, list, read, discard, promote };
+}
+/**
+ * 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 function maintainAttachments(sql, provider, limit = 100) {
+    return Effect.gen(function* () {
+        const [table] = yield* sql `
+      SELECT to_regclass(${`public.${ATTACHMENTS_TABLE}`})::text AS present
+    `;
+        if (!table?.present) {
+            return { expired: 0, removed: 0 };
+        }
+        const expired = yield* sql.withTransaction(Effect.gen(function* () {
+            const rows = yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET state = 'expired'
+           WHERE state IN ('received', 'ready') AND expires_at <= now() RETURNING id`);
+            yield* sql.unsafe(`UPDATE "_blob_uploads" u SET state = 'canceled', expires_at = now(), claim = NULL
+           FROM "${ATTACHMENTS_TABLE}" a
+           WHERE u.blob_id = a.blob_id AND u.state = 'ready'
+             AND (a.state IN ('discarded', 'expired') OR a.expires_at <= now())`);
+            return rows.length;
+        }));
+        let removed = 0;
+        for (let count = 0; count < limit; count += 1) {
+            const candidate = yield* sql.withTransaction(Effect.gen(function* () {
+                const [row] = yield* sql.unsafe(`SELECT a.id::text, a.blob_id::text, b.key, a.provider_upload_id
+             FROM "${ATTACHMENTS_TABLE}" a JOIN "_blobs" b ON b.id = a.blob_id
+             WHERE a.removed_at IS NULL AND b.state IN ('ready', 'deleting')
+               AND (a.state IN ('discarded', 'expired') OR a.expires_at <= now()
+                 OR a.branch_id <> $1)
+               AND NOT EXISTS (SELECT 1 FROM "_blob_references" r WHERE r.blob_id = b.id)
+               AND NOT EXISTS (SELECT 1 FROM "_blob_uploads" u WHERE u.blob_id = b.id)
+             ORDER BY a.created_at LIMIT 1 FOR UPDATE OF a, b SKIP LOCKED`, [provider.binding.branchId]);
+                if (!row) {
+                    return undefined;
+                }
+                yield* sql.unsafe(`UPDATE "_blobs" SET state = 'deleting' WHERE id = $1::uuid`, [
+                    row.blob_id,
+                ]);
+                return row;
+            }));
+            if (!candidate) {
+                break;
+            }
+            const handles = new Set([
+                ...(candidate.provider_upload_id ? [candidate.provider_upload_id] : []),
+                ...(yield* provider.pending(candidate.key)),
+            ]);
+            for (const uploadId of handles) {
+                yield* provider.abort({ key: candidate.key, uploadId });
+            }
+            yield* provider.remove(candidate.key);
+            yield* sql.withTransaction(Effect.gen(function* () {
+                yield* sql.unsafe(`UPDATE "_blobs" SET state = 'deleted' WHERE id = $1::uuid AND state = 'deleting'`, [candidate.blob_id]);
+                yield* sql.unsafe(`UPDATE "${ATTACHMENTS_TABLE}" SET removed_at = now(),
+               state = CASE WHEN state IN ('received', 'ready') THEN 'expired' ELSE state END
+             WHERE id = $1::uuid`, [candidate.id]);
+            }));
+            removed += 1;
+        }
+        return { expired, removed };
+    });
+}

package/dist/storage/maintenance.d.ts

@@ -1,7 +1,10 @@
 import { Effect } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
 import type { BlobProvider } from "./provider.js";
-/** A scheduler-owned capability: lifecycle operations only, with persisted deletion fencing. */
+/**
+ * A scheduler-owned capability: lifecycle operations only, with persisted deletion fencing. The
+ * agent's attachments expire first, so that their files are removed in the same run.
+ */
 export declare function maintainBlobStorage(sql: SqlClient.SqlClient, provider: BlobProvider["Service"], limit?: number): Effect.Effect<{
     removed: number;
 }, import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;