@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/storage/attachments.js

@@ -0,0 +1,733 @@
+import { createHash, randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { acceptsBlobContentType, isBlobContentType, 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 { storageQuotaRejection } from "./limits.js";
+import { ATTACHMENT_SOURCES, 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. Group files belong to the chat's current
+ * members; private files belong to their sender and the agent session that first reads them.
+ * Nothing about it is an ontology record. It expires 24 hours after receipt; the 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 derives chat access from the caller and registry, never from
+ * tool 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 { ATTACHMENT_SOURCES };
+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,
+        conversation: row.conversation,
+        senderId: row.owner_id,
+    };
+}
+/** 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 registry contains groups only. Neither a tool argument nor a caller's roles name a group. */
+    const accessScope = (caller) => Effect.gen(function* () {
+        const [member] = yield* sql.unsafe(`SELECT kind::text, active FROM "user" WHERE id = $1::uuid FOR SHARE`, [caller.principal.id]);
+        if (member?.kind !== "member" || !member.active) {
+            return "denied";
+        }
+        yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+        if (caller.access === "member") {
+            const admin = yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [
+                "agent_chat:update",
+            ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+            if (admin) {
+                return "administrator";
+            }
+        }
+        const separator = caller.conversation.indexOf(":");
+        const [chat] = yield* sql.unsafe(`SELECT id::text FROM "agent_chat"
+         WHERE provider = $1 AND external_id = $2 FOR SHARE`, [caller.conversation.slice(0, separator), caller.conversation.slice(separator + 1)]);
+        if (chat === undefined) {
+            return "private";
+        }
+        const [participant] = yield* sql.unsafe(`SELECT 1 FROM "agent_chat_members"
+         WHERE agent_chat_id = $1::uuid AND user_id = $2::uuid FOR SHARE`, [chat.id, caller.principal.id]);
+        if (participant !== undefined) {
+            return "group";
+        }
+        // App roles are authored by the workspace. Chat management grants its administrator access;
+        // re-read the roles here rather than trusting permissions cached on the principal.
+        const administrator = yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [
+            "agent_chat:update",
+        ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+        return administrator ? "group" : "denied";
+    });
+    /**
+     * The caller's attachment, locked. Group access follows current chat membership. Private access
+     * requires the sender and their session. Source transfers always require the original sender.
+     */
+    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 access = yield* accessScope(caller);
+        if (access === "denied") {
+            return yield* missing(id);
+        }
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.id = $1::uuid AND (a.owner_id = $2::uuid OR $5) AND a.conversation = $3
+          AND a.branch_id = $4 FOR UPDATE OF a, b`, [
+            id,
+            caller.principal.id,
+            caller.conversation,
+            binding.branchId,
+            (access === "group" || access === "administrator") && scope === "session",
+        ]);
+        const row = rows[0];
+        if (!row) {
+            return yield* missing(id);
+        }
+        if (access === "private" &&
+            caller.access !== "member" &&
+            scope === "session" &&
+            row.session_id !== null &&
+            row.session_id !== caller.sessionId) {
+            return yield* missing(id);
+        }
+        if (access === "private" &&
+            caller.access !== "member" &&
+            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,
+            ]);
+        }
+        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) ||
+            !isBlobContentType(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, [], caller.principal.execution);
+            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]);
+            const overQuota = storageQuotaRejection({
+                usedBytes: Number(usage.bytes),
+                requestedBytes: input.size,
+                quotaBytes: binding.quotaBytes,
+            });
+            if (overQuota) {
+                return yield* overQuota;
+            }
+            if (Number(usage.live) >= MAX_LIVE_ATTACHMENTS) {
+                return yield* new ActionRejected({
+                    message: `The member's attachment limit is reached: ${MAX_LIVE_ATTACHMENTS} are live.`,
+                    limit: {
+                        kind: "member_attachments",
+                        live: Number(usage.live),
+                        max: MAX_LIVE_ATTACHMENTS,
+                    },
+                });
+            }
+            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, "source");
+        }));
+        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, "source"));
+        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, "source"));
+        }));
+    });
+    /** Accessible attachments in this chat that are still readable, newest first. */
+    const list = (caller) => sql.withTransaction(Effect.gen(function* () {
+        const access = yield* accessScope(caller);
+        if (access === "denied") {
+            return [];
+        }
+        const rows = yield* sql.unsafe(`${SELECT} WHERE (a.owner_id = $1::uuid OR $5) AND a.conversation = $2 AND a.branch_id = $3
+             AND a.state IN ('ready', 'promoted') AND a.expires_at > now()
+             AND ($5 OR 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,
+            access === "group",
+        ]);
+        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);
+            yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions, caller.principal.execution);
+            if (caller.access === "member" && row.expired) {
+                return yield* unavailable("The attachment expired or was purged.");
+            }
+            if (row.state === "promoted") {
+                return { kind: "done", row };
+            }
+            if (row.state !== "ready" || row.expired) {
+                return yield* unavailable("The attachment expired or was discarded.");
+            }
+            if (!acceptsBlobContentType(property.accept, 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.`,
+                });
+            }
+            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
+               AND conversation = $5 AND (owner_id = $6::uuid OR $7)
+               AND ($7 OR $9 OR session_id IS NULL OR session_id = $8)
+             ORDER BY created_at LIMIT 1`, [
+                row.sha256,
+                binding.branchId,
+                row.id,
+                qualified,
+                caller.conversation,
+                caller.principal.id,
+                ["group", "administrator"].includes(yield* accessScope(caller)),
+                caller.sessionId ?? null,
+                caller.access === "member",
+            ]);
+            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 };
+    });
+    /** Resolve the chat from storage, then authorize with the same locked loader. */
+    const memberCaller = (id, principal) => sql.withTransaction(Effect.gen(function* () {
+        if (!/^[0-9a-f-]{36}$/i.test(id)) {
+            return yield* missing(id);
+        }
+        const [row] = yield* sql.unsafe(`SELECT conversation FROM "${ATTACHMENTS_TABLE}" WHERE id = $1::uuid AND branch_id = $2`, [id, binding.branchId]);
+        if (!row) {
+            return yield* missing(id);
+        }
+        const caller = {
+            principal,
+            conversation: row.conversation,
+            access: "member",
+        };
+        yield* load(id, caller);
+        return caller;
+    }));
+    const getForMember = (id, principal) => Effect.gen(function* () {
+        const caller = yield* memberCaller(id, principal);
+        const row = yield* sql.withTransaction(load(id, caller));
+        if (!READABLE.has(row.state) || row.expired) {
+            return yield* unavailable("The attachment expired, was purged, or is not ready.");
+        }
+        return view(row);
+    });
+    const readForMember = (id, principal) => Effect.gen(function* () {
+        return yield* read(id, yield* memberCaller(id, principal));
+    });
+    const promoteForMember = (id, target, principal, run) => Effect.gen(function* () {
+        return yield* promote(id, target, yield* memberCaller(id, principal), run);
+    });
+    const listForMember = (filters, principal) => sql.withTransaction(Effect.gen(function* () {
+        const [member] = yield* sql.unsafe(`SELECT kind::text, active FROM "user" WHERE id = $1::uuid FOR SHARE`, [principal.id]);
+        if (member?.kind !== "member" || !member.active) {
+            return yield* missing("chat");
+        }
+        yield* authorizeBlobOperation(ontology, sql, principal.id, []);
+        const admin = yield* authorizeBlobOperation(ontology, sql, principal.id, [
+            "agent_chat:update",
+        ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+        if (filters.conversation !== undefined) {
+            const scope = yield* accessScope({
+                principal,
+                conversation: filters.conversation,
+                access: "member",
+            });
+            if (scope === "denied") {
+                return yield* missing("chat");
+            }
+            if (scope === "private") {
+                const [sent] = yield* sql.unsafe(`SELECT 1 FROM "${ATTACHMENTS_TABLE}" WHERE branch_id = $1 AND conversation = $2
+                AND owner_id = $3::uuid LIMIT 1`, [binding.branchId, filters.conversation, principal.id]);
+                if (sent === undefined) {
+                    return yield* missing("chat");
+                }
+            }
+        }
+        const limit = filters.limit ?? 50;
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.branch_id = $1
+          AND ($2 OR EXISTS (
+            SELECT 1 FROM "agent_chat" c JOIN "agent_chat_members" m ON m.agent_chat_id = c.id
+            WHERE c.provider || ':' || c.external_id = a.conversation AND m.user_id = $3::uuid
+          ) OR (a.owner_id = $3::uuid AND NOT EXISTS (
+            SELECT 1 FROM "agent_chat" c WHERE c.provider || ':' || c.external_id = a.conversation
+          )))
+          AND ($4::text IS NULL OR a.conversation = $4)
+          AND ($5::uuid IS NULL OR a.owner_id = $5::uuid)
+          AND ($6::timestamptz IS NULL OR a.created_at >= $6::timestamptz)
+          AND ($7::timestamptz IS NULL OR a.created_at <= $7::timestamptz)
+          AND ($8::uuid IS NULL OR (a.created_at, a.id) < (
+            SELECT created_at, id FROM "${ATTACHMENTS_TABLE}" WHERE id = $8::uuid AND branch_id = $1
+          ))
+        ORDER BY a.created_at DESC, a.id DESC LIMIT $9`, [
+            binding.branchId,
+            admin,
+            principal.id,
+            filters.conversation ?? null,
+            filters.senderId ?? null,
+            filters.from ?? null,
+            filters.to ?? null,
+            filters.before ?? null,
+            limit + 1,
+        ]);
+        return {
+            attachments: rows.slice(0, limit).map(view),
+            nextCursor: rows.length > limit ? rows[limit - 1].id : null,
+        };
+    }));
+    return {
+        receive,
+        complete,
+        list,
+        read,
+        discard,
+        promote,
+        listForMember,
+        getForMember,
+        readForMember,
+        promoteForMember,
+    };
+}
+/**
+ * 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, hasMore: false };
+        }
+        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;
+        }
+        // Include locked candidates: another pass must not postpone interrupted cleanup for hours.
+        const [backlog] = yield* sql.unsafe(`SELECT EXISTS (
+         SELECT 1 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)
+       ) AS remaining`, [provider.binding.branchId]);
+        return { expired, removed, hasMore: backlog.remaining || removed >= limit };
+    });
+}