@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/storage/sessions.js

@@ -0,0 +1,688 @@
+import { createHash, randomUUID } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { isSqlError } from "effect/unstable/sql/SqlError";
+import { acceptsBlobContentType, uploadInput, BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES, } from "../blob.js";
+import { wireStruct } from "../wire.js";
+import { ActionRejected, Conflict, NotFound } from "../errors.js";
+import { Files } from "../files.js";
+import { uploadFile, openFile } from "./transfers.js";
+import { canonicalJson } from "../manifest.js";
+import { effectiveScope } from "../permissions.js";
+import { isRecordId } from "../runtime/records.js";
+import { authorizeBlobOperation } from "./authorization.js";
+import { MAX_PENDING_UPLOADS, storageQuotaRejection } from "./limits.js";
+import { resolveAction } from "../runtime/pipeline.js";
+import { makeOntologyRuntime } from "../runtime/sql-runtime.js";
+import { BlobStorageError } from "./provider.js";
+const Id = Schema.String.check(Schema.isUUID());
+export const BeginUpload = wireStruct({
+    entity: Schema.String,
+    property: Schema.String,
+    action: Schema.String,
+    recordId: Schema.optionalKey(Id),
+    createIntent: Schema.optionalKey(Id),
+    idempotencyKey: Schema.optionalKey(Id),
+    filename: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(255)),
+    contentType: Schema.String,
+    size: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(MAX_BLOB_BYTES)),
+}, {
+    recordId: "record_id",
+    createIntent: "create_intent",
+    idempotencyKey: "idempotency_key",
+    contentType: "content_type",
+});
+export const UploadView = wireStruct({
+    id: Id,
+    state: Schema.String,
+    expiresAt: Schema.String,
+    ticket: Schema.optionalKey(uploadInput()),
+}, { expiresAt: "expires_at" });
+export const OpenUpload = wireStruct({
+    id: Id,
+    state: Schema.String,
+    filename: Schema.String,
+    contentType: Schema.String,
+    size: Schema.Int,
+    entity: Schema.String,
+    property: Schema.String,
+    action: Schema.String,
+    recordId: Schema.NullOr(Id),
+    createIntent: Schema.NullOr(Id),
+    createdAt: Schema.String,
+    expiresAt: Schema.String,
+    awaitingAction: Schema.Boolean,
+}, {
+    contentType: "content_type",
+    recordId: "record_id",
+    createIntent: "create_intent",
+    createdAt: "created_at",
+    expiresAt: "expires_at",
+    awaitingAction: "awaiting_action",
+});
+export const OpenUploads = Schema.Struct({
+    uploads: Schema.Array(OpenUpload),
+    pending: Schema.Int,
+    max: Schema.Int,
+});
+export const TransferGrant = wireStruct({
+    url: Schema.String,
+    method: Schema.Literals(["GET", "PUT"]),
+    headers: Schema.Record(Schema.String, Schema.String),
+    expiresAt: Schema.String,
+}, { expiresAt: "expires_at" });
+export const DownloadRequest = wireStruct({
+    revisionId: Schema.optionalKey(Id),
+    inline: Schema.optionalKey(Schema.Boolean),
+}, { revisionId: "revision_id" });
+function allowsUpload(schema, entity, property) {
+    if (typeof schema !== "object" || schema === null) {
+        return false;
+    }
+    const object = schema;
+    const binding = object[BLOB_UPLOAD_ANNOTATION];
+    return ((binding?.entity === entity && binding.property === property) ||
+        Object.values(object).some((child) => allowsUpload(child, entity, property)));
+}
+function sniff(bytes, contentType) {
+    const starts = (magic) => magic.every((byte, index) => bytes[index] === byte);
+    switch (contentType.toLowerCase()) {
+        case "application/pdf":
+            return starts([37, 80, 68, 70, 45]);
+        case "image/png":
+            return starts([137, 80, 78, 71, 13, 10, 26, 10]);
+        case "image/jpeg":
+            return starts([255, 216, 255]);
+        case "text/plain":
+            try {
+                // Streaming decoding allows the prefix to end in the middle of a UTF-8 character.
+                new TextDecoder("utf-8", { fatal: true }).decode(bytes, { stream: true });
+                return bytes.every((byte) => byte >= 32 || [9, 10, 13].includes(byte));
+            }
+            catch {
+                return false;
+            }
+        default:
+            // Other MIME types describe opaque bytes; storage does not parse their formats.
+            return true;
+    }
+}
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export function blobRuntime(ontology, sql, provider, fetchImpl = fetch) {
+    const binding = provider.binding;
+    const conflict = () => new Conflict({ entity: "upload", message: "The upload is unavailable or busy." });
+    // An uncertain storage outcome keeps its claim; the same request recovers once it is stale.
+    const busy = (row) => new Conflict({
+        entity: "upload",
+        message: "Another attempt holds the upload.",
+        retryAfter: row.claim_wait ?? 300,
+    });
+    const view = (row) => ({
+        id: row.id,
+        state: row.state,
+        expiresAt: row.expires_at,
+        ...(row.state === "ready" && !row.expired ? { ticket: { uploadId: row.id } } : {}),
+    });
+    const load = (id, principal) => Effect.gen(function* () {
+        const rows = yield* sql.unsafe(`SELECT u.*, b.key,
+      to_char(u.expires_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS expires_at,
+      u.expires_at <= now() AS expired,
+      u.claimed_at < now() - interval '5 minutes' AS claim_stale,
+      GREATEST(1, CEIL(EXTRACT(EPOCH FROM u.claimed_at + interval '5 minutes' - now())))::int
+        AS claim_wait
+      FROM "_blob_uploads" u JOIN "_blobs" b ON b.id = u.blob_id
+      WHERE u.id = $1::uuid AND u.principal_id = $2::uuid AND u.branch_id = $3
+      FOR UPDATE OF u, b`, [id, principal.id, binding.branchId]);
+        const row = rows[0];
+        if (!row) {
+            return yield* new NotFound({ entity: "upload", id, message: "Upload not found." });
+        }
+        const [entity, action] = row.action.split(".");
+        const found = resolveAction(ontology, entity, action);
+        if (!found || row.manifest_hash !== ontology.manifest.hash) {
+            return yield* conflict();
+        }
+        yield* authorizeBlobOperation(ontology, sql, principal.id, found.permissions, principal.execution, principal.workflow);
+        return row;
+    });
+    const beginUpload = (given, principal, preparedAction) => Effect.gen(function* () {
+        // UUIDs in either case name one record; uuid columns answer in lower case.
+        const input = {
+            ...given,
+            ...(given.recordId === undefined ? {} : { recordId: given.recordId.toLowerCase() }),
+            ...(given.createIntent === undefined
+                ? {}
+                : { createIntent: given.createIntent.toLowerCase() }),
+        };
+        const entity = ontology.manifest.entities.find((item) => item.name === input.entity);
+        const property = entity?.properties.find((item) => item.name === input.property && item.type === "blob");
+        const qualified = preparedAction ?? `${input.entity}.${input.action}`;
+        const [actionEntity, actionName] = qualified.split(".");
+        const found = resolveAction(ontology, actionEntity, actionName);
+        if (!entity ||
+            entity.source ||
+            !property ||
+            !found ||
+            !Number.isSafeInteger(input.size) ||
+            input.size <= 0 ||
+            input.size > MAX_BLOB_BYTES ||
+            !input.filename ||
+            input.filename.length > 255 ||
+            (input.recordId !== undefined && !isRecordId(input.recordId)) ||
+            (input.createIntent !== undefined && !isRecordId(input.createIntent)) ||
+            !acceptsBlobContentType(property.accept, input.contentType) ||
+            input.size > (property.maxBytes ?? MAX_BLOB_BYTES) ||
+            Boolean(input.recordId) === Boolean(input.createIntent) ||
+            /[\x00-\x1f\x7f/\\]/.test(input.filename)) {
+            return yield* new ActionRejected({ message: "The file or upload target is invalid." });
+        }
+        const schema = Schema.toJsonSchemaDocument(found.action.input, {
+            includeAnnotationKey: (key) => key === BLOB_UPLOAD_ANNOTATION,
+        });
+        const declared = preparedAction !== undefined &&
+            found.action.files?.some((target) => target.entity === input.entity && target.property === input.property);
+        if (!declared && !allowsUpload(schema, input.entity, input.property)) {
+            return yield* new ActionRejected({
+                message: "This action does not accept an upload for that field.",
+            });
+        }
+        // A caller-generated UUID is also the session identity, without changing existing tables.
+        const id = input.idempotencyKey ?? randomUUID();
+        const blobId = randomUUID();
+        const claim = randomUUID();
+        const key = `revisions/${blobId}`;
+        const reservation = yield* sql.withTransaction(Effect.gen(function* () {
+            yield* authorizeBlobOperation(ontology, sql, principal.id, found.permissions, principal.execution, principal.workflow);
+            yield* sql.unsafe(`SELECT pg_advisory_xact_lock(818723)`);
+            const existing = yield* sql.unsafe(`SELECT id FROM "_blob_uploads" WHERE id = $1::uuid`, [
+                id,
+            ]);
+            const row = existing.length ? yield* load(id, principal) : undefined;
+            if (row) {
+                const replay = preparedAction !== undefined && row.state === "consumed";
+                if ((!replay && row.expired) ||
+                    row.action !== qualified ||
+                    row.entity_id !== entity.id ||
+                    row.property_id !== property.name ||
+                    row.record_id !== (input.recordId ?? null) ||
+                    row.create_intent !== (input.createIntent ?? null) ||
+                    row.filename !== input.filename ||
+                    row.content_type !== input.contentType ||
+                    Number(row.size) !== input.size) {
+                    return yield* conflict();
+                }
+                // A retried workflow step needs the original ticket to replay its committed action.
+                // Attachment still requires a ready session, so this cannot consume it a second time.
+                if (replay) {
+                    return { row, recover: false };
+                }
+            }
+            if (input.recordId) {
+                yield* makeOntologyRuntime(ontology, sql).get({
+                    entity: input.entity,
+                    id: input.recordId,
+                });
+            }
+            if (row) {
+                if (["uploading", "completing", "ready"].includes(row.state)) {
+                    return { row, recover: false };
+                }
+                if (row.state !== "initializing") {
+                    return yield* conflict();
+                }
+                if (row.claim && !row.claim_stale) {
+                    return yield* busy(row);
+                }
+                yield* sql.unsafe(`UPDATE "_blob_uploads" SET claim = $1::uuid, claimed_at = now() WHERE id = $2::uuid`, [claim, row.id]);
+                return { row, recover: true };
+            }
+            const [usage] = yield* sql.unsafe(`SELECT (SELECT coalesce(sum(size), 0)::text FROM "_blobs" WHERE state <> 'deleted') AS bytes,
+          (SELECT count(*)::text FROM "_blob_uploads" WHERE principal_id = $1::uuid
+            AND branch_id = $2 AND manifest_hash = $3 AND expires_at > now()
+            AND state IN ('initializing', 'uploading', 'completing', 'ready', 'deleting')) AS pending`, [principal.id, binding.branchId, ontology.manifest.hash]);
+            const overQuota = storageQuotaRejection({
+                usedBytes: Number(usage.bytes),
+                requestedBytes: input.size,
+                quotaBytes: binding.quotaBytes,
+            });
+            if (overQuota) {
+                return yield* overQuota;
+            }
+            if (Number(usage.pending) >= MAX_PENDING_UPLOADS) {
+                // The caller is told which uploads hold its capacity, so it can store or cancel them.
+                const open = yield* sql.unsafe(`SELECT id::text, filename,
+                 to_char(expires_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS expires_at
+               FROM "_blob_uploads" WHERE principal_id = $1::uuid
+                 AND branch_id = $2 AND manifest_hash = $3 AND expires_at > now()
+                 AND state IN ('initializing', 'uploading', 'completing', 'ready', 'deleting')
+               ORDER BY created_at, id LIMIT $4::int`, [principal.id, binding.branchId, ontology.manifest.hash, MAX_PENDING_UPLOADS]);
+                return yield* new ActionRejected({
+                    message: `Pending upload limit reached: ${MAX_PENDING_UPLOADS} uploads are open. ` +
+                        "Store their files with their actions or cancel the uploads you will not use.",
+                    limit: {
+                        kind: "pending_uploads",
+                        pending: Number(usage.pending),
+                        max: MAX_PENDING_UPLOADS,
+                        uploads: open.map((upload) => ({
+                            id: upload.id,
+                            filename: upload.filename,
+                            expiresAt: upload.expires_at,
+                        })),
+                    },
+                });
+            }
+            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, key, input.filename, input.contentType, input.size]);
+            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, claim, claimed_at)
+        VALUES ($1::uuid, $2::uuid, $3::uuid, $4, $5, $6, $7, $8, $9::uuid, $10::uuid, $11, $12,
+          $13::bigint, 'initializing', $14::uuid, now())`, [
+                id,
+                blobId,
+                principal.id,
+                binding.branchId,
+                ontology.manifest.hash,
+                qualified,
+                entity.id,
+                property.name,
+                input.recordId ?? null,
+                input.createIntent ?? null,
+                input.filename,
+                input.contentType,
+                input.size,
+                claim,
+            ]);
+            return { row: yield* load(id, principal), recover: false };
+        }));
+        const { row } = reservation;
+        if (row.state !== "initializing") {
+            return preparedAction !== undefined && row.state === "consumed"
+                ? { ...view(row), ticket: { uploadId: row.id } }
+                : view(row);
+        }
+        const handles = reservation.recover ? yield* provider.pending(row.key) : [];
+        const uploadId = handles[0] ??
+            (yield* provider
+                .initiate({
+                key: row.key,
+                filename: row.filename,
+                contentType: row.content_type,
+                sessionId: row.id,
+            })
+                .pipe(Effect.catchTag("BlobStorageError", (error) => Effect.gen(function* () {
+                if (error.initiationRejected) {
+                    // A definitive refusal created no handle or bytes. Remove only our still-held
+                    // reservation so retrying the same idempotency key can start again immediately.
+                    yield* sql
+                        .withTransaction(Effect.gen(function* () {
+                        const removed = yield* sql.unsafe(`DELETE FROM "_blob_uploads"
+                           WHERE id = $1::uuid AND state = 'initializing' AND claim = $2::uuid
+                           RETURNING blob_id`, [row.id, claim]);
+                        if (removed.length) {
+                            yield* sql.unsafe(`DELETE FROM "_blobs" WHERE id = $1::uuid`, [
+                                removed[0].blob_id,
+                            ]);
+                        }
+                    }))
+                        .pipe(Effect.catch((cleanupError) => Effect.logError("ontology.storage.initialization_cleanup_failed", cleanupError)));
+                }
+                return yield* error;
+            }))));
+        const persisted = yield* sql.withTransaction(sql.unsafe(`UPDATE "_blob_uploads" SET
+      state = 'uploading', provider_upload_id = $1, claim = NULL, claimed_at = NULL
+      WHERE id = $2::uuid AND state = 'initializing' AND claim = $3::uuid RETURNING id`, [uploadId, row.id, claim]));
+        if (!persisted.length) {
+            const [latest] = yield* sql.withTransaction(sql.unsafe(`SELECT state, provider_upload_id FROM "_blob_uploads" WHERE id = $1::uuid`, [row.id]));
+            // A replacement claim may have adopted this handle after our response was delayed.
+            if (latest?.state !== "initializing" && latest?.provider_upload_id !== uploadId) {
+                yield* provider.abort({ key: row.key, uploadId });
+                yield* sql.withTransaction(sql.unsafe(`UPDATE "_blob_uploads" SET claim = NULL, claimed_at = NULL
+               WHERE id = $1::uuid AND state = 'canceled' AND claim = $2::uuid`, [row.id, claim]));
+            }
+            return yield* conflict();
+        }
+        return yield* sql.withTransaction(load(row.id, principal).pipe(Effect.map(view)));
+    });
+    const begin = (input, principal) => beginUpload(input, principal);
+    // This is the caller's own upload intent metadata, never another member's files or grants.
+    // Match the admission check exactly: expired sessions and earlier deployments hold no slots.
+    const list = (principal) => sql.withTransaction(Effect.gen(function* () {
+        const rows = yield* sql.unsafe(`SELECT u.*,
+             to_char(u.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at,
+             to_char(u.expires_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS expires_at
+           FROM "_blob_uploads" u WHERE u.principal_id = $1::uuid
+             AND u.branch_id = $2 AND u.manifest_hash = $3 AND u.expires_at > now()
+             AND u.state IN ('initializing', 'uploading', 'completing', 'ready', 'deleting')
+           ORDER BY u.created_at, u.id LIMIT $4::int`, [principal.id, binding.branchId, ontology.manifest.hash, MAX_PENDING_UPLOADS]);
+        return {
+            uploads: rows.map((row) => ({
+                id: row.id,
+                state: row.state,
+                filename: row.filename,
+                contentType: row.content_type,
+                size: Number(row.size),
+                entity: ontology.manifest.entities.find((entity) => entity.id === row.entity_id).name,
+                property: row.property_id,
+                action: row.action,
+                recordId: row.record_id,
+                createIntent: row.create_intent,
+                createdAt: row.created_at,
+                expiresAt: row.expires_at,
+                awaitingAction: row.state === "ready",
+            })),
+            pending: rows.length,
+            max: MAX_PENDING_UPLOADS,
+        };
+    }));
+    const status = (id, principal) => sql.withTransaction(load(id, principal).pipe(Effect.map(view)));
+    // Server extensions can recheck record-level policy before continuing a
+    // session. Resolve its persisted binding, never a target supplied by a caller.
+    const target = (id, principal) => sql.withTransaction(load(id, principal).pipe(Effect.map((row) => {
+        const [entity, action] = row.action.split(".");
+        return {
+            entity: entity,
+            action: action,
+            property: row.property_id,
+            recordId: row.record_id,
+            createIntent: row.create_intent,
+        };
+    })));
+    const part = (id, principal) => Effect.gen(function* () {
+        const row = yield* sql.withTransaction(load(id, principal).pipe(Effect.flatMap((row) => row.state === "uploading" && !row.expired && row.provider_upload_id && !row.claim
+            ? Effect.succeed(row)
+            : Effect.fail(conflict()))));
+        return yield* provider.signPart({
+            key: row.key,
+            uploadId: row.provider_upload_id,
+            partNumber: 1,
+            size: Number(row.size),
+        });
+    });
+    const completeUpload = (id, principal, heldClaim) => Effect.gen(function* () {
+        const claim = randomUUID();
+        const row = yield* sql.withTransaction(Effect.gen(function* () {
+            const row = yield* load(id, principal);
+            if (row.state === "ready" && !row.expired) {
+                return row;
+            }
+            if (heldClaim !== undefined && row.claim !== heldClaim) {
+                return yield* conflict();
+            }
+            if (row.claim && row.claim !== heldClaim && !row.claim_stale) {
+                return yield* busy(row);
+            }
+            if (row.state === "completing" &&
+                !row.claim_stale &&
+                !row.expired &&
+                row.provider_upload_id) {
+                return yield* busy(row);
+            }
+            if (row.expired ||
+                !row.provider_upload_id ||
+                !(row.state === "uploading" || (row.state === "completing" && row.claim_stale))) {
+                return yield* conflict();
+            }
+            yield* sql.unsafe(`UPDATE "_blob_uploads" SET state = 'completing', claim = $1::uuid, claimed_at = now()
+        WHERE id = $2::uuid`, [claim, id]);
+            return row;
+        }));
+        if (row.state === "ready") {
+            return view(row);
+        }
+        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 uploaded 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 prefix = yield* provider.readPrefix(row.key);
+        if (!stored ||
+            stored.size !== Number(row.size) ||
+            stored.sessionId !== id ||
+            stored.contentType !== row.content_type ||
+            !sniff(prefix, row.content_type)) {
+            yield* sql.withTransaction(sql.unsafe(`UPDATE "_blob_uploads" SET state = 'canceled', expires_at = now(),
+        claim = NULL WHERE id = $1::uuid AND claim = $2::uuid`, [id, claim]));
+            return yield* new ActionRejected({
+                message: "The file's contents do not match its declared type or size.",
+            });
+        }
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            const current = yield* load(id, principal);
+            if (current.state !== "completing" || current.claim !== claim || current.expired) {
+                return yield* conflict();
+            }
+            yield* sql.unsafe(`UPDATE "_blob_uploads" SET state = 'ready', expires_at = now() + interval '24 hours',
+        claim = NULL, claimed_at = NULL WHERE id = $1::uuid`, [id]);
+            return view(yield* load(id, principal));
+        }));
+    });
+    const cancel = (id, principal) => sql.withTransaction(Effect.gen(function* () {
+        const row = yield* load(id, principal);
+        if (row.state === "consumed" || row.state === "completing") {
+            return yield* conflict();
+        }
+        if (["deleted", "deleting", "canceled"].includes(row.state)) {
+            return view(row);
+        }
+        yield* sql.unsafe(
+        // An initializing provider request may still create a handle after cancellation.
+        // Keep its recovery window until a late response is aborted or the claim expires.
+        `UPDATE "_blob_uploads" SET state = 'canceled', expires_at = now(),
+          claim = CASE WHEN state = 'initializing' THEN claim ELSE NULL END,
+          claimed_at = CASE WHEN state = 'initializing' THEN claimed_at ELSE NULL END
+      WHERE id = $1::uuid`, [id]);
+        return view(yield* load(id, principal));
+    }));
+    const complete = (id, principal) => completeUpload(id, principal);
+    const prepareDownload = (entityName, recordId, propertyName, input, principal) => Effect.gen(function* () {
+        const entity = ontology.manifest.entities.find((item) => item.name === entityName);
+        const property = entity?.properties.find((item) => item.name === propertyName && item.type === "blob");
+        if (!entity || !property) {
+            return yield* new NotFound({
+                entity: entityName,
+                id: recordId,
+                message: "File not found.",
+            });
+        }
+        const blob = yield* sql.withTransaction(Effect.gen(function* () {
+            const reader = yield* authorizeBlobOperation(ontology, sql, principal.id, [`${entityName}:read`], principal.execution, principal.workflow);
+            let revisionId = input.revisionId;
+            if (!revisionId || effectiveScope(`${entityName}:read`, reader) !== undefined) {
+                const record = yield* makeOntologyRuntime(ontology, sql).get({
+                    entity: entityName,
+                    id: recordId,
+                    reader,
+                });
+                revisionId ??= record[propertyName]?.id;
+            }
+            const [blob] = yield* sql.unsafe(`SELECT b.id::text, b.key, b.filename, b.content_type, b.size::text,
+              to_char(b.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at
+           FROM "_blobs" b JOIN "_blob_references" r ON r.blob_id = b.id
+         WHERE b.id = $1::uuid AND b.state = 'retained' AND b.branch_id = $5 AND r.entity_id = $2
+           AND r.property_id = $3 AND r.record_id = $4::uuid FOR SHARE OF b`, [revisionId ?? null, entity.id, property.name, recordId, binding.branchId]);
+            if (!blob) {
+                return yield* new NotFound({
+                    entity: entityName,
+                    id: recordId,
+                    message: "File not found.",
+                });
+            }
+            return blob;
+        }));
+        return blob;
+    });
+    const download = (...args) => Effect.gen(function* () {
+        const blob = yield* prepareDownload(...args);
+        return yield* provider.download({
+            key: blob.key,
+            filename: blob.filename,
+            contentType: blob.content_type,
+            inline: args[3].inline === true &&
+                ["image/jpeg", "image/png"].includes(blob.content_type.toLowerCase()),
+        });
+    });
+    const downloadFile = (...args) => Effect.gen(function* () {
+        const blob = yield* prepareDownload(...args);
+        const sha256 = yield* provider.sha256(blob.key, Number(blob.size));
+        // Recheck live access after hashing; no provider I/O holds a database transaction.
+        yield* prepareDownload(args[0], args[1], args[2], { revisionId: blob.id }, args[4]);
+        const grant = yield* provider.download({
+            key: blob.key,
+            filename: blob.filename,
+            contentType: blob.content_type,
+            inline: false,
+        });
+        return {
+            file: {
+                id: args[1],
+                entity: args[0],
+                property: args[2],
+                revision_id: blob.id,
+                filename: blob.filename,
+                content_type: blob.content_type,
+                size: Number(blob.size),
+                sha256,
+            },
+            download: grant,
+        };
+    });
+    const files = (invocation) => {
+        const publicErrors = (effect) => effect.pipe(Effect.catch((cause) => {
+            if (isSqlError(cause)) {
+                return Effect.die(cause);
+            }
+            if (cause instanceof BlobStorageError) {
+                return Effect.fail(new ActionRejected({ message: "file_storage_failed", cause }));
+            }
+            // Caller stream errors retain their exact identity and retry policy.
+            return Effect.fail(cause);
+        }));
+        return Files.of({
+            stage: (input) => publicErrors(Effect.gen(function* () {
+                const action = invocation.action ?? input.action;
+                const actionKey = invocation.idempotencyKey;
+                if (!action ||
+                    !actionKey ||
+                    !input.key ||
+                    input.key.length > 512 ||
+                    (input.action !== undefined && input.action !== action)) {
+                    return yield* new ActionRejected({ message: "invalid_file_invocation" });
+                }
+                const [actionEntity, actionName, extra] = action.split(".");
+                const found = actionEntity && actionName && !extra
+                    ? resolveAction(ontology, actionEntity, actionName)
+                    : undefined;
+                const allowed = found?.action.files?.some((target) => target.entity === input.target.entity && target.property === input.target.property);
+                if (!found || (!allowed && invocation.action !== undefined)) {
+                    return yield* new ActionRejected({ message: "file_target_not_declared" });
+                }
+                const createIntent = (input.createIntent ??
+                    (input.recordId === undefined ? invocation.createIntent : undefined))?.toLowerCase();
+                const hash = createHash("sha256")
+                    .update(canonicalJson({
+                    principal: invocation.principal.id,
+                    branch: binding.branchId,
+                    manifest: ontology.manifest.hash,
+                    action,
+                    actionKey,
+                    source: input.key,
+                    target: input.target,
+                    record: input.recordId ?? null,
+                    createIntent: createIntent ?? null,
+                    filename: input.filename,
+                    contentType: input.contentType,
+                    size: input.size,
+                }))
+                    .digest();
+                hash[6] = (hash[6] & 15) | 80;
+                hash[8] = (hash[8] & 63) | 128;
+                const hex = hash.subarray(0, 16).toString("hex");
+                const id = [
+                    hex.slice(0, 8),
+                    hex.slice(8, 12),
+                    hex.slice(12, 16),
+                    hex.slice(16, 20),
+                    hex.slice(20),
+                ].join("-");
+                let upload = yield* beginUpload({
+                    entity: input.target.entity,
+                    property: input.target.property,
+                    action: actionName,
+                    ...(input.recordId ? { recordId: input.recordId } : {}),
+                    ...(createIntent ? { createIntent } : {}),
+                    idempotencyKey: id,
+                    filename: input.filename,
+                    contentType: input.contentType,
+                    size: input.size,
+                }, invocation.principal, action);
+                if (upload.ticket) {
+                    return upload.ticket;
+                }
+                if (upload.state === "completing") {
+                    upload = yield* complete(id, invocation.principal);
+                }
+                else {
+                    const claim = randomUUID();
+                    const transfer = yield* sql.withTransaction(Effect.gen(function* () {
+                        const row = yield* load(id, invocation.principal);
+                        if (row.state !== "uploading" || row.expired || !row.provider_upload_id) {
+                            return yield* conflict();
+                        }
+                        if (row.claim && !row.claim_stale) {
+                            return yield* busy(row);
+                        }
+                        yield* sql.unsafe(`UPDATE "_blob_uploads" SET claim = $1::uuid, claimed_at = now() WHERE id = $2::uuid`, [claim, id]);
+                        return row;
+                    }));
+                    const grant = yield* provider.signPart({
+                        key: transfer.key,
+                        uploadId: transfer.provider_upload_id,
+                        partNumber: 1,
+                        size: input.size,
+                    });
+                    const source = yield* input.open();
+                    yield* uploadFile({ grant, size: input.size, source, fetch: fetchImpl });
+                    upload = yield* completeUpload(id, invocation.principal, claim);
+                }
+                if (!upload.ticket) {
+                    return yield* conflict();
+                }
+                return upload.ticket;
+            })),
+            open: (input) => publicErrors(Effect.gen(function* () {
+                const args = [
+                    input.entity,
+                    input.id,
+                    input.property,
+                    { revisionId: input.revisionId },
+                    invocation.principal,
+                ];
+                const blob = yield* prepareDownload(...args);
+                const grant = yield* provider.download({
+                    key: blob.key,
+                    filename: blob.filename,
+                    contentType: blob.content_type,
+                    inline: false,
+                });
+                return {
+                    file: {
+                        id: blob.id,
+                        filename: blob.filename,
+                        contentType: blob.content_type,
+                        size: Number(blob.size),
+                        createdAt: blob.created_at,
+                    },
+                    body: yield* openFile({ grant, size: Number(blob.size), fetch: fetchImpl }),
+                };
+            })),
+        });
+    };
+    return { begin, list, status, target, part, complete, cancel, download, downloadFile, files };
+}