@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/storage/authorization.d.ts

@@ -0,0 +1,38 @@
+import { Effect } from "effect";
+import type { Ontology } from "../ontology.js";
+import { PermissionDenied } from "../errors.js";
+import { type PrincipalRolesSql } from "../runtime/principals.js";
+/** Re-read user and roles in the same transaction that authorizes a storage operation. */
+export declare function authorizeBlobOperation(ontology: Ontology, sql: PrincipalRolesSql, principalId: string, required: ReadonlyArray<string>, execution?: import("../runtime/workload.js").WorkloadExecution, 
+/** The workflow a workflow user's principal acts for, with its subject in this workspace. */
+workflowPrincipal?: {
+    readonly name: string;
+    readonly subject: string;
+}): Effect.Effect<{
+    scopes?: ReadonlyArray<import("../permissions.js").ScopedPermission>;
+    id: string;
+    permissions: readonly string[];
+} | {
+    execution: {
+        readonly issuer: string;
+        readonly audience: string;
+        readonly organizationId: string;
+        readonly workspaceId: string;
+        readonly subject: string;
+        readonly deploymentId: string;
+        readonly ontologyDeploymentId: string;
+        readonly servingOntologyDeploymentId: string;
+        readonly ontologyOrigin: string;
+        readonly environment: "production" | "preview";
+        readonly jobName: string | null;
+        readonly runId: string;
+        readonly executionId: string | null;
+        readonly attemptId: string;
+        readonly generation: number;
+        readonly tokenId: string;
+        readonly issuedAt: number;
+        readonly expiresAt: number;
+    };
+    id: string;
+    permissions: readonly string[];
+}, PermissionDenied | import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/storage/authorization.js

@@ -0,0 +1,83 @@
+import { Effect } from "effect";
+import { missingPermission, permissionsOf, principalScopes } from "../permissions.js";
+import { PermissionDenied } from "../errors.js";
+import { MEMBER_ROLE, FEEDBACK_REPORTER_ROLE, toSnakeCase } from "../names.js";
+import { rolesOf } from "../runtime/principals.js";
+import { PIPELINE_WORKER_PROVIDER } from "../runtime/workload.js";
+import { WORKFLOW_USER_PROVIDER, workflowOfSubject } from "../runtime/workflow-users.js";
+/** Re-read user and roles in the same transaction that authorizes a storage operation. */
+export function authorizeBlobOperation(ontology, sql, principalId, required, execution, 
+/** The workflow a workflow user's principal acts for, with its subject in this workspace. */
+workflowPrincipal) {
+    return Effect.gen(function* () {
+        const [catalog] = yield* sql.unsafe(`SELECT hash FROM "_ontology" WHERE id = true FOR SHARE`, []);
+        if (catalog?.hash !== ontology.manifest.hash) {
+            yield* Effect.logWarning("ontology.storage.catalog_mismatch", {
+                servedHash: ontology.manifest.hash,
+                appliedHash: catalog?.hash ?? null,
+            });
+            return yield* new PermissionDenied({
+                message: "The deployed ontology no longer matches the database catalog.",
+                updating: true,
+            });
+        }
+        const users = yield* sql.unsafe(`SELECT kind::text, active, identity_provider, identity_subject FROM "user" WHERE id = $1::uuid FOR SHARE`, [principalId]);
+        const user = users[0];
+        const roles = yield* sql.unsafe(`SELECT role FROM "_user_roles" WHERE user_id = $1::uuid FOR SHARE`, [principalId]);
+        const held = roles
+            .map((row) => String(row.role))
+            .filter((name) => toSnakeCase(name) !== FEEDBACK_REPORTER_ROLE);
+        // Reuse human principal resolution rather than reconstructing implicit authority here. The
+        // result rechecks required permissions and is the reader for scoped file reads; the caller's
+        // consent-narrowed principal still governs the rest of the operation.
+        const member = user?.kind === "member"
+            ? yield* rolesOf(ontology, sql, {
+                id: principalId,
+                kind: "member",
+                active: user.active === true,
+            })
+            : undefined;
+        const worker = execution !== undefined &&
+            user?.kind === "service" &&
+            user.identity_provider === PIPELINE_WORKER_PROVIDER &&
+            user.identity_subject === `pipeline-workers:${execution.workspaceId}`;
+        // A workflow's runs hold what member and the declared workflow's role grant. The database
+        // must assign exactly that role: an extra or stale assignment widens nothing and is refused.
+        const workflowUser = user?.kind === "service" && user.identity_provider === WORKFLOW_USER_PROVIDER;
+        // The user's subject must be exactly the principal's, workspace id included.
+        const workflow = workflowUser &&
+            workflowPrincipal !== undefined &&
+            user.identity_subject === workflowPrincipal.subject &&
+            workflowOfSubject(user.identity_subject) === workflowPrincipal.name
+            ? ontology.workflows.find((candidate) => candidate.name === workflowPrincipal.name)
+            : undefined;
+        const declaredWorkflow = workflow !== undefined &&
+            execution === undefined &&
+            held.length === 1 &&
+            held[0] === workflow.role;
+        const liveHeld = workflowUser && workflow ? [MEMBER_ROLE, workflow.role] : (member?.roles ?? held);
+        const permissions = worker
+            ? ["*:*"]
+            : workflowUser && !declaredWorkflow
+                ? []
+                : permissionsOf(ontology.roles, liveHeld);
+        const missing = missingPermission(required, {
+            ...(worker ? { execution } : {}),
+            permissions,
+        });
+        if (!user?.active ||
+            missing ||
+            (execution !== undefined && !worker) ||
+            (workflowUser && !declaredWorkflow)) {
+            return yield* new PermissionDenied({
+                message: "The member cannot use this file operation.",
+                ...(missing ? { permission: missing } : {}),
+            });
+        }
+        return {
+            id: principalId,
+            permissions,
+            ...(worker ? { execution } : principalScopes(ontology.roles, liveHeld)),
+        };
+    });
+}

package/dist/storage/file-access.d.ts

@@ -0,0 +1,17 @@
+import { Context } from "effect";
+import type { Files } from "../files.js";
+import type { Principal } from "../runtime.js";
+/** Private factory; authoring code receives only the bound Files capability. */
+export interface FileInvocation {
+    readonly principal: Principal;
+    readonly action?: string;
+    readonly idempotencyKey?: string;
+    readonly createIntent?: string;
+}
+declare const FileAccess_base: Context.ServiceClass<FileAccess, "@segmentstream/ontology/FileAccess", {
+    readonly forInvocation: (input: FileInvocation) => Files["Service"];
+}>;
+export declare class FileAccess extends FileAccess_base {
+}
+export declare const unavailableFiles: Files["Service"];
+export {};

package/dist/storage/file-access.js

@@ -0,0 +1,8 @@
+import { Context, Effect } from "effect";
+import { ActionRejected } from "../errors.js";
+export class FileAccess extends Context.Service()("@segmentstream/ontology/FileAccess") {
+}
+export const unavailableFiles = {
+    stage: () => Effect.fail(new ActionRejected({ message: "file_storage_unavailable" })),
+    open: () => Effect.fail(new ActionRejected({ message: "file_storage_unavailable" })),
+};

package/dist/storage/limits.d.ts

@@ -0,0 +1,12 @@
+import { ActionRejected } from "../errors.js";
+/** Upload sessions one principal may hold open at once. */
+export declare const MAX_PENDING_UPLOADS = 8;
+/**
+ * Refuses a file that would take the workspace past its storage quota. `usedBytes` counts every
+ * file revision not yet deleted, including retained history, reserved uploads and attachments.
+ */
+export declare function storageQuotaRejection(input: {
+    readonly usedBytes: number;
+    readonly requestedBytes: number;
+    readonly quotaBytes: number;
+}): ActionRejected | undefined;

package/dist/storage/limits.js

@@ -0,0 +1,17 @@
+import { ActionRejected } from "../errors.js";
+/** Upload sessions one principal may hold open at once. */
+export const MAX_PENDING_UPLOADS = 8;
+/**
+ * Refuses a file that would take the workspace past its storage quota. `usedBytes` counts every
+ * file revision not yet deleted, including retained history, reserved uploads and attachments.
+ */
+export function storageQuotaRejection(input) {
+    if (input.usedBytes + input.requestedBytes <= input.quotaBytes) {
+        return undefined;
+    }
+    return new ActionRejected({
+        message: `File storage quota reached: ${input.usedBytes} of ${input.quotaBytes} bytes are used ` +
+            `and this file needs ${input.requestedBytes}.`,
+        limit: { kind: "storage_quota", ...input },
+    });
+}

package/dist/storage/maintenance-auth.d.ts

@@ -0,0 +1,20 @@
+import { Layer, Redacted } from "effect";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
+import { RequestId } from "../service/errors.js";
+declare const StorageMaintenanceAuthentication_base: HttpApiMiddleware.ServiceClass<StorageMaintenanceAuthentication, "@segmentstream/ontology/StorageMaintenanceAuthentication", {
+    requires: RequestId;
+    provides: never;
+    error: readonly [import("effect/Schema").Top];
+    clientError: never;
+    requiredForClient: false;
+    security: {
+        readonly maintenanceBearer: HttpApiSecurity.Http;
+    };
+}, HttpApiMiddleware.HttpApiMiddlewareSecurity<{
+    readonly maintenanceBearer: HttpApiSecurity.Http;
+}, never, readonly [import("effect/Schema").Top], RequestId>>;
+/** Deployment scheduler identity: this credential grants only orphan maintenance. */
+export declare class StorageMaintenanceAuthentication extends StorageMaintenanceAuthentication_base {
+}
+export declare function storageMaintenanceAuthenticationLayer(key?: Redacted.Redacted<string>): Layer.Layer<StorageMaintenanceAuthentication, never, never>;
+export {};

package/dist/storage/maintenance-auth.js

@@ -0,0 +1,24 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { Effect, Layer, Redacted } from "effect";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
+import { RequestId, toServerResponse, unauthorized } from "../service/errors.js";
+import { ErrorSchemas } from "../service/schemas.js";
+/** Deployment scheduler identity: this credential grants only orphan maintenance. */
+export class StorageMaintenanceAuthentication extends HttpApiMiddleware.Service()("@segmentstream/ontology/StorageMaintenanceAuthentication", {
+    security: { maintenanceBearer: HttpApiSecurity.bearer },
+    error: [ErrorSchemas.unauthorized],
+}) {
+}
+export function storageMaintenanceAuthenticationLayer(key) {
+    return Layer.succeed(StorageMaintenanceAuthentication)({
+        maintenanceBearer: (httpEffect, { credential }) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const digest = (value) => createHash("sha256").update(value).digest();
+            if (!key ||
+                !timingSafeEqual(digest(Redacted.value(credential)), digest(Redacted.value(key)))) {
+                return toServerResponse(unauthorized(requestId, "A deployment maintenance credential is required."));
+            }
+            return yield* httpEffect;
+        }),
+    });
+}

package/dist/storage/maintenance.d.ts

@@ -0,0 +1,11 @@
+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. 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;
+    hasMore: boolean;
+}, import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;

package/dist/storage/maintenance.js

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { maintainAttachments } from "./attachments.js";
+/**
+ * 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 function maintainBlobStorage(sql, provider, limit = 100) {
+    return Effect.gen(function* () {
+        const attachments = yield* maintainAttachments(sql, provider, limit);
+        let removed = attachments.removed;
+        let attempted = 0;
+        for (let count = 0; count < limit; count += 1) {
+            const claim = randomUUID();
+            const candidate = yield* sql.withTransaction(Effect.gen(function* () {
+                const [row] = yield* sql.unsafe(`SELECT u.id::text, u.blob_id::text, b.key, u.provider_upload_id
+           FROM "_blob_uploads" u JOIN "_blobs" b ON b.id = u.blob_id
+           WHERE u.state NOT IN ('consumed', 'deleted') AND b.state IN ('ready', 'deleting')
+             AND (u.branch_id <> $1 OR u.expires_at <= now() OR u.state IN ('canceled', 'deleting'))
+             AND (u.claim IS NULL OR u.claimed_at < now() - interval '5 minutes')
+             AND NOT EXISTS (SELECT 1 FROM "_blob_references" r WHERE r.blob_id = b.id)
+           ORDER BY u.created_at LIMIT 1 FOR UPDATE OF u, b SKIP LOCKED`, [provider.binding.branchId]);
+                if (!row) {
+                    return undefined;
+                }
+                yield* sql.unsafe(`UPDATE "_blob_uploads" SET state = 'deleting', claim = $1::uuid,
+          claimed_at = now() WHERE id = $2::uuid`, [claim, row.id]);
+                yield* sql.unsafe(`UPDATE "_blobs" SET state = 'deleting' WHERE id = $1::uuid`, [
+                    row.blob_id,
+                ]);
+                return row;
+            }));
+            if (!candidate) {
+                break;
+            }
+            attempted += 1;
+            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* () {
+                const done = yield* sql.unsafe(`UPDATE "_blob_uploads" SET state = 'deleted', claim = NULL,
+          claimed_at = NULL WHERE id = $1::uuid AND state = 'deleting' AND claim = $2::uuid
+          RETURNING blob_id`, [candidate.id, claim]);
+                if (done.length) {
+                    yield* sql.unsafe(`UPDATE "_blobs" SET state = 'deleted' WHERE id = $1::uuid AND state = 'deleting'`, [candidate.blob_id]);
+                    removed += 1;
+                }
+            }));
+        }
+        // Claims and row locks defer work; they do not make the backlog empty.
+        const [backlog] = yield* sql.unsafe(`SELECT EXISTS (
+         SELECT 1 FROM "_blob_uploads" u JOIN "_blobs" b ON b.id = u.blob_id
+         WHERE u.state NOT IN ('consumed', 'deleted') AND b.state IN ('ready', 'deleting')
+           AND (u.branch_id <> $1 OR u.expires_at <= now() OR u.state IN ('canceled', 'deleting'))
+           AND NOT EXISTS (SELECT 1 FROM "_blob_references" r WHERE r.blob_id = b.id)
+       ) AS remaining`, [provider.binding.branchId]);
+        return {
+            removed,
+            hasMore: attachments.hasMore || attempted >= limit || backlog.remaining,
+        };
+    });
+}

package/dist/storage/neon.d.ts

@@ -0,0 +1,4 @@
+import { type DeploymentObservation } from "../deployment.js";
+import { BlobProvider, type BlobStorageBinding } from "./provider.js";
+/** A branch-bound S3 adapter; never uses the ambient AWS credential chain. */
+export declare function neonBlobProvider(binding: BlobStorageBinding, deployment?: DeploymentObservation): BlobProvider["Service"];

package/dist/storage/neon.js

@@ -0,0 +1,318 @@
+import { createHash } from "node:crypto";
+import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListMultipartUploadsCommand, ListPartsCommand, S3Client, UploadPartCommand, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { Effect } from "effect";
+import { DeploymentAdmissionError, requireDeploymentCapability, } from "../deployment.js";
+import { BlobStorageError, validateDeploymentStorage, } from "./provider.js";
+function missing(error) {
+    return error instanceof Error && ["NotFound", "NoSuchKey", "NoSuchUpload"].includes(error.name);
+}
+function redactStorageFailure(cause, binding) {
+    const seen = new WeakSet();
+    const redact = (value) => {
+        if (typeof value === "string") {
+            return [binding.accessKeyId, binding.secretAccessKey]
+                .reduce((text, secret) => secret
+                ? text
+                    .replaceAll(secret, "[redacted]")
+                    .replaceAll(encodeURIComponent(secret), "[redacted]")
+                : text, value)
+                .replace(/https?:\/\/[^\s"'<>]*[?&]X-Amz-(?:Signature|Credential)=[^\s"'<>]*/gi, "[redacted storage grant]")
+                .replace(/(X-Amz-Signature=)[^&\s]+/gi, "$1[redacted]");
+        }
+        if (value === null || typeof value !== "object") {
+            return value;
+        }
+        if (seen.has(value)) {
+            return "[Circular]";
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            return value.map(redact);
+        }
+        const entries = value instanceof Error
+            ? Object.fromEntries([
+                ["name", value.name],
+                ["message", value.message],
+                ["stack", value.stack],
+                ["cause", value.cause],
+                ...(value instanceof AggregateError ? [["errors", value.errors]] : []),
+                ...Object.entries(value),
+            ])
+            : value;
+        return Object.fromEntries(Object.entries(entries).map(([key, child]) => [key, redact(child)]));
+    };
+    return redact(cause);
+}
+/** A branch-bound S3 adapter; never uses the ambient AWS credential chain. */
+export function neonBlobProvider(binding, deployment) {
+    validateDeploymentStorage(binding, deployment);
+    const endpoint = new URL(binding.endpoint);
+    if (endpoint.protocol !== "https:" ||
+        endpoint.username ||
+        endpoint.password ||
+        !endpoint.hostname.startsWith(`${binding.branchId}.storage.`) ||
+        !endpoint.hostname.endsWith(".aws.neon.tech") ||
+        endpoint.pathname !== "/" ||
+        endpoint.search ||
+        endpoint.hash ||
+        endpoint.port) {
+        throw new Error("The ontology storage endpoint does not match its verified branch.");
+    }
+    const client = new S3Client({
+        endpoint: binding.endpoint,
+        region: binding.region,
+        credentials: { accessKeyId: binding.accessKeyId, secretAccessKey: binding.secretAccessKey },
+        forcePathStyle: true,
+        requestChecksumCalculation: "WHEN_REQUIRED",
+        maxAttempts: 1,
+        requestHandler: { requestTimeout: 30000 },
+    });
+    let storageClockOffset;
+    // The SDK's normal skew correction tolerates four minutes, longer than a download grant.
+    // Calibrate every grant from an authenticated response instead of extending its lifetime.
+    client.middlewareStack.add((next) => async (args) => {
+        const result = await next(args);
+        const response = result.response;
+        const serverTime = Date.parse(response.headers?.date ?? "");
+        if (Number.isFinite(serverTime)) {
+            storageClockOffset = serverTime - Date.now();
+        }
+        return result;
+    }, { step: "deserialize", name: "ontologyStorageClock" });
+    const signingDate = () => {
+        if (storageClockOffset === undefined) {
+            throw new Error("Neon did not return a valid server time for the transfer grant.");
+        }
+        return new Date(Date.now() + storageClockOffset);
+    };
+    const object = (key) => ({ Bucket: binding.bucket, Key: key });
+    // SigV4 collapses sequential header spaces. Send that same value on the wire: Neon's
+    // multipart verifier rejects a quoted filename containing unnormalized double spaces.
+    // Only normalize the fallback; filename* preserves the original name and whitespace.
+    const disposition = (filename, inline = false) => {
+        const fallback = filename.replace(/[^a-zA-Z0-9_. -]/g, "_").replace(/ +/g, " ");
+        // encodeURIComponent leaves these characters unescaped, but RFC 5987 disallows them.
+        const encoded = encodeURIComponent(filename).replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+        return `${inline ? "inline" : "attachment"}; filename="${fallback}"; filename*=UTF-8''${encoded}`;
+    };
+    const attempt = (operation, run) => Effect.suspend(() => {
+        if (deployment) {
+            requireDeploymentCapability(deployment);
+        }
+        return Effect.tryPromise({
+            try: run,
+            catch: (cause) => {
+                if (cause instanceof DeploymentAdmissionError) {
+                    throw cause;
+                }
+                const status = cause?.$metadata
+                    ?.httpStatusCode;
+                return new BlobStorageError({
+                    operation,
+                    cause: redactStorageFailure(cause, binding),
+                    ...(operation === "blob.initiate" &&
+                        status !== undefined &&
+                        status >= 400 &&
+                        status < 500 &&
+                        status !== 408
+                        ? { initiationRejected: true }
+                        : {}),
+                });
+            },
+        });
+    });
+    const grantSeconds = (maximum, signedAt) => {
+        if (deployment?.target !== "preview") {
+            return maximum;
+        }
+        const remaining = Math.floor((Date.parse(deployment.expiresAt) - signedAt.getTime()) / 1000);
+        if (remaining <= 0) {
+            throw new DeploymentAdmissionError("preview_expired");
+        }
+        return Math.min(maximum, remaining);
+    };
+    const grant = (url, method, seconds, signedAt) => ({
+        url,
+        method,
+        headers: {},
+        expiresAt: new Date(signedAt.getTime() + seconds * 1000).toISOString(),
+    });
+    return {
+        binding,
+        close: () => client.destroy(),
+        initiate: ({ key, filename, contentType, sessionId }) => attempt("blob.initiate", async () => {
+            const response = await client.send(new CreateMultipartUploadCommand({
+                ...object(key),
+                ContentType: contentType,
+                ContentDisposition: disposition(filename),
+                CacheControl: "private, no-store",
+                Metadata: { session: sessionId },
+            }));
+            if (!response.UploadId) {
+                throw new Error("Neon did not return a multipart upload ID.");
+            }
+            return response.UploadId;
+        }),
+        signPart: ({ key, uploadId, partNumber, size }) => attempt("blob.sign_part", async () => {
+            await client.send(new ListPartsCommand({ ...object(key), UploadId: uploadId }));
+            const signedAt = signingDate();
+            const seconds = grantSeconds(300, signedAt);
+            const url = await getSignedUrl(client, new UploadPartCommand({
+                ...object(key),
+                UploadId: uploadId,
+                PartNumber: partNumber,
+                ContentLength: size,
+            }), {
+                expiresIn: seconds,
+                signingDate: signedAt,
+                signableHeaders: new Set(["content-length"]),
+            });
+            return grant(url, "PUT", seconds, signedAt);
+        }),
+        parts: ({ key, uploadId }) => attempt("blob.parts", async () => {
+            const response = await client.send(new ListPartsCommand({ ...object(key), UploadId: uploadId }));
+            if (response.IsTruncated) {
+                throw new Error("Unexpected truncated multipart session.");
+            }
+            return (response.Parts ?? []).map((part) => {
+                if (!part.PartNumber || part.Size === undefined || !part.ETag) {
+                    throw new Error("Neon returned incomplete part metadata.");
+                }
+                return { number: part.PartNumber, size: part.Size, etag: part.ETag };
+            });
+        }),
+        complete: ({ key, uploadId, parts }) => attempt("blob.complete", async () => {
+            await client.send(new CompleteMultipartUploadCommand({
+                ...object(key),
+                UploadId: uploadId,
+                MultipartUpload: {
+                    Parts: parts.map((part) => ({ PartNumber: part.number, ETag: part.etag })),
+                },
+            }));
+        }),
+        inspect: (key) => attempt("blob.inspect", async () => {
+            try {
+                const response = await client.send(new HeadObjectCommand(object(key)));
+                if (response.ContentLength === undefined ||
+                    !response.ContentType ||
+                    !response.Metadata?.session) {
+                    throw new Error("Neon returned incomplete object metadata.");
+                }
+                return {
+                    size: response.ContentLength,
+                    contentType: response.ContentType,
+                    sessionId: response.Metadata.session,
+                };
+            }
+            catch (error) {
+                if (missing(error)) {
+                    return undefined;
+                }
+                throw error;
+            }
+        }),
+        sha256: (key, size) => attempt("blob.sha256", async () => {
+            const response = await client.send(new GetObjectCommand(object(key)));
+            if (!response.Body) {
+                throw new Error("Neon returned no object body.");
+            }
+            const hash = createHash("sha256");
+            const reader = response.Body.transformToWebStream().getReader();
+            let received = 0;
+            let failure;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    received += value.byteLength;
+                    if (received > size) {
+                        throw new Error("The stored object exceeds its declared size.");
+                    }
+                    hash.update(value);
+                }
+                if (received !== size) {
+                    throw new Error("The stored object does not match its declared size.");
+                }
+                return hash.digest("hex");
+            }
+            catch (cause) {
+                failure = cause;
+                throw cause;
+            }
+            finally {
+                try {
+                    await reader.cancel();
+                }
+                catch (cleanup) {
+                    if (failure !== undefined) {
+                        throw new AggregateError([failure, cleanup], "Hashing and stream cleanup failed.", {
+                            cause: cleanup,
+                        });
+                    }
+                    throw cleanup;
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            }
+        }),
+        readPrefix: (key) => attempt("blob.read_prefix", async () => {
+            const response = await client.send(new GetObjectCommand({ ...object(key), Range: "bytes=0-511" }));
+            if (!response.Body) {
+                throw new Error("Neon returned no object body.");
+            }
+            return response.Body.transformToByteArray();
+        }),
+        read: (key, maxBytes) => attempt("blob.read", async () => {
+            const response = await client.send(new GetObjectCommand(object(key)));
+            if (!response.Body) {
+                throw new Error("Neon returned no object body.");
+            }
+            if (response.ContentLength !== undefined && response.ContentLength > maxBytes) {
+                throw new Error("The stored object exceeds the size it may have.");
+            }
+            const bytes = await response.Body.transformToByteArray();
+            if (bytes.byteLength > maxBytes) {
+                throw new Error("The stored object exceeds the size it may have.");
+            }
+            return bytes;
+        }),
+        download: ({ key, filename, contentType, inline }) => attempt("blob.download", async () => {
+            await client.send(new HeadObjectCommand(object(key)));
+            const signedAt = signingDate();
+            const seconds = grantSeconds(60, signedAt);
+            const url = await getSignedUrl(client, new GetObjectCommand({
+                ...object(key),
+                ResponseContentType: contentType,
+                ResponseContentDisposition: disposition(filename, inline),
+                ResponseCacheControl: "private, no-store",
+            }), { expiresIn: seconds, signingDate: signedAt });
+            return grant(url, "GET", seconds, signedAt);
+        }),
+        abort: ({ key, uploadId }) => attempt("blob.abort", async () => {
+            try {
+                await client.send(new AbortMultipartUploadCommand({ ...object(key), UploadId: uploadId }));
+            }
+            catch (error) {
+                if (!missing(error)) {
+                    throw error;
+                }
+            }
+        }),
+        remove: (key) => attempt("blob.remove", async () => {
+            await client.send(new DeleteObjectCommand(object(key)));
+        }),
+        pending: (key) => attempt("blob.pending", async () => {
+            const response = await client.send(new ListMultipartUploadsCommand({ Bucket: binding.bucket, Prefix: key }));
+            if (response.IsTruncated) {
+                throw new Error("Unexpected truncated initialization recovery.");
+            }
+            return (response.Uploads ?? [])
+                .filter((upload) => upload.Key === key && upload.UploadId)
+                .map((upload) => upload.UploadId);
+        }),
+    };
+}

package/dist/storage/operator.d.ts

@@ -0,0 +1,11 @@
+import { Effect, Redacted } from "effect";
+import { BlobStorageError, type BlobStorageBinding } from "./provider.js";
+/** Scheduler capability that survives removal of blob declarations. Never reads file contents. */
+export declare function runBlobStorageMaintenance(input: {
+    readonly databaseUrl: Redacted.Redacted<string>;
+    readonly binding: Redacted.Redacted<BlobStorageBinding>;
+    readonly limit?: number;
+}): Effect.Effect<{
+    removed: number;
+    hasMore: boolean;
+}, import("effect/unstable/sql/SqlError").SqlError | BlobStorageError, never>;