@segmentstream-cloud/ontology 0.9.0 → 0.10.0

package/dist/runtime/generated-actions.js

@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect";
+import { uploadInput, BLOB_UPLOAD_ANNOTATION } from "../blob.js";
 import { action } from "../action.js";
 import { GENERATED_UPSERT_PREFIX } from "../names.js";
 import { generatedActionPermissions } from "../permissions.js";
@@ -16,7 +17,10 @@ export function upsertActionName(property) {
     return `${GENERATED_UPSERT_PREFIX}${property}`;
 }
 /** A property's value schema, refusing days that do not exist, which PostgreSQL would reject. */
-function propertyInput(field) {
+function propertyInput(field, entity) {
+    if (field.storage === "blob") {
+        return uploadInput(entity.name, field.name);
+    }
     const schema = propertyValueSchema(field.property);
     if (field.storage === "date") {
         return schema.check(Schema.makeFilter((value) => isCalendarDate(value) || "Expected a date that exists"));
@@ -44,7 +48,7 @@ function valueFields(entity, { mode }) {
         if (mode === "update" && definition?.managed === true) {
             continue;
         }
-        const value = propertyInput(field);
+        const value = propertyInput(field, entity);
         const required = mode === "create" &&
             !field.nullable &&
             !(definition !== undefined && "default" in definition);
@@ -164,7 +168,7 @@ function buildGeneratedActions(ontology, entityName) {
 }
 function inputJsonSchema(input) {
     const document = Schema.toJsonSchemaDocument(input, {
-        includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION,
+        includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
         onExcessProperty: "error",
     });
     const schema = document.schema;

package/dist/runtime/history.d.ts

@@ -57,6 +57,9 @@ export interface HistoryScope {
     readonly action: string;
     readonly actionId: string;
     readonly principalId: string | null;
+    readonly branchId?: string;
+    readonly blobActionKey?: string;
+    readonly createIntent?: string;
 }
 /** `INSERT` of one history row; `at` is the transaction's time, shared by the whole action. */
 export declare function insertHistory(scope: HistoryScope, write: HistoryWrite, params: Params): string;

package/dist/runtime/pipeline.d.ts

@@ -32,7 +32,10 @@ export interface ActionRequest<R = never> {
     readonly options?: {
         /** Decode the input and check the permission, without running `prepare` or the handler. */
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
+    readonly branchId?: string;
     readonly afterCommit?: ReadonlyArray<AfterCommit<R>>;
     /** The request's id, which `prepare` and the handler receive for logs; the action id by default. */
     readonly requestId?: string;
@@ -96,7 +99,8 @@ export declare function findAction(ontology: Ontology, entityName: string, actio
  * 1. decode the input with the action's schema; issues are returned, not raised;
  * 2. check that the principal's permissions cover the action's (PermissionDenied);
  * 3. with `validateOnly`, stop;
- * 4. run `prepare`, when the action has one, without a transaction: reads and the declared
+ * 4. reauthorize and replay a committed blob action, if its idempotency key matches;
+ *    otherwise run `prepare`, when the action has one, without a transaction: reads and the declared
  *    connections only, under {@link PREPARE_TIMEOUT};
  * 5. without a handler, answer with what `prepare` returned;
  * 6. open one transaction and run the handler with what `prepare` returned and the runtime, which

package/dist/runtime/pipeline.js

@@ -1,7 +1,10 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { Cause, Duration, Effect, Option, Schema } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import { isSqlError } from "effect/unstable/sql/SqlError";
+import { canonicalJson } from "../manifest.js";
+import { Conflict } from "../errors.js";
+import { authorizeBlobOperation } from "../storage/authorization.js";
 import { ConnectionError, ConnectionTransport, connectionContext } from "../connection.js";
 import { PermissionDenied } from "../errors.js";
 import { generatedActionPermissions, missingPermission } from "../permissions.js";
@@ -61,7 +64,8 @@ const NO_CONNECTIONS = {
  * 1. decode the input with the action's schema; issues are returned, not raised;
  * 2. check that the principal's permissions cover the action's (PermissionDenied);
  * 3. with `validateOnly`, stop;
- * 4. run `prepare`, when the action has one, without a transaction: reads and the declared
+ * 4. reauthorize and replay a committed blob action, if its idempotency key matches;
+ *    otherwise run `prepare`, when the action has one, without a transaction: reads and the declared
  *    connections only, under {@link PREPARE_TIMEOUT};
  * 5. without a handler, answer with what `prepare` returned;
  * 6. open one transaction and run the handler with what `prepare` returned and the runtime, which
@@ -107,6 +111,50 @@ export function runAction(ontology, request) {
         const actionId = randomUUID();
         const requestId = request.requestId ?? actionId;
         const context = { input: decoded.value, principal: request.principal, requestId };
+        const hasUploads = (value) => typeof value === "object" &&
+            value !== null &&
+            ("uploadId" in value || Object.values(value).some(hasUploads));
+        const key = request.options?.idempotencyKey;
+        const hasBlobProperties = ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"));
+        const consumesUpload = action.transactional && hasBlobProperties && (hasUploads(decoded.value) || key !== undefined);
+        if (consumesUpload && (!key || key.length > 128 || !request.branchId)) {
+            return yield* new Conflict({
+                entity: request.entity,
+                message: "Upload actions require an idempotency key.",
+            });
+        }
+        const fingerprint = consumesUpload
+            ? createHash("sha256")
+                .update(canonicalJson({
+                qualified,
+                manifestHash: ontology.manifest.hash,
+                branchId: request.branchId ?? null,
+                input: request.input,
+                createIntent: request.options?.createIntent ?? null,
+            }))
+                .digest("hex")
+            : undefined;
+        // A committed retry must not depend on preparation's external services being available.
+        // The handler transaction below still locks and rechecks the key for concurrent requests.
+        if (consumesUpload) {
+            const saved = yield* sql
+                .withTransaction(Effect.gen(function* () {
+                yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions);
+                const [saved] = yield* sql.unsafe(`SELECT fingerprint, outcome FROM "_blob_action_results"
+               WHERE principal_id = $1::uuid AND key = $2`, [request.principal.id, key]);
+                if (saved && saved.fingerprint !== fingerprint) {
+                    return yield* new Conflict({
+                        entity: request.entity,
+                        message: "Idempotency key was used for another action.",
+                    });
+                }
+                return saved?.outcome;
+            }))
+                .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+            if (saved) {
+                return saved;
+            }
+        }
         const prepared = action.prepare === undefined
             ? undefined
             : yield* prepare(ontology, sql, action, context, request.connections, qualified);
@@ -118,13 +166,49 @@ export function runAction(ontology, request) {
             action: qualified,
             actionId,
             principalId: request.principal.id,
+            ...(key ? { blobActionKey: key } : {}),
+            ...(request.branchId ? { branchId: request.branchId } : {}),
+            ...(request.options?.createIntent ? { createIntent: request.options.createIntent } : {}),
             onEdit: (edit) => edits.push(edit),
         });
         const handle = action.handler;
         const handler = Effect.suspend(() => handle({ ...context, prepared }));
+        let replay;
+        const transactionalHandler = Effect.gen(function* () {
+            if (consumesUpload) {
+                yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions);
+                yield* sql.unsafe(`INSERT INTO "_blob_action_results" (principal_id, key, fingerprint)
+          VALUES ($1::uuid, $2, $3) ON CONFLICT DO NOTHING`, [request.principal.id, key, fingerprint]);
+                const [saved] = yield* sql.unsafe(`SELECT fingerprint, outcome FROM "_blob_action_results" WHERE principal_id = $1::uuid AND key = $2
+           FOR UPDATE`, [request.principal.id, key]);
+                if (saved.fingerprint !== fingerprint) {
+                    return yield* new Conflict({
+                        entity: request.entity,
+                        message: "Idempotency key was used for another action.",
+                    });
+                }
+                if (saved.outcome) {
+                    replay = saved.outcome;
+                    return replay.result;
+                }
+            }
+            const result = yield* handler.pipe(OntologyRuntime.provide(runtime));
+            if (consumesUpload) {
+                yield* sql.unsafe(`UPDATE "_blob_action_results" SET outcome = $1::jsonb
+          WHERE principal_id = $2::uuid AND key = $3`, [
+                    JSON.stringify({ result: result ?? null, validation: VALID, edits }),
+                    request.principal.id,
+                    key,
+                ]);
+            }
+            return result;
+        });
         const result = yield* sql
-            .withTransaction(handler.pipe(OntologyRuntime.provide(runtime)))
+            .withTransaction(transactionalHandler)
             .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+        if (replay) {
+            return replay;
+        }
         const committed = {
             entity: request.entity,
             action: request.action,

package/dist/runtime/records.js

@@ -12,6 +12,11 @@ import { validate } from "./validation.js";
  */
 function readExpression(field, column) {
     switch (field.storage) {
+        case "blob":
+            return (`(SELECT json_build_object('id', b.id::text, 'filename', b.filename, ` +
+                `'contentType', b.content_type, 'size', b.size, 'createdAt', ` +
+                `to_char(b.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))::text ` +
+                `FROM "_blobs" b WHERE b.id = ${column})`);
         case "timestamp":
             return `to_char(${column} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`;
         case "date":
@@ -42,6 +47,7 @@ function readValue(field, value) {
     switch (field.storage) {
         case "integer":
             return Number(value);
+        case "blob":
         case "json":
             return typeof value === "string" ? JSON.parse(value) : value;
         case "timestamp":
@@ -76,6 +82,9 @@ export function bindValue(field, value) {
     if (value === null) {
         return null;
     }
+    if (field.storage === "blob") {
+        return typeof value === "string" ? value : value.id;
+    }
     return field.storage === "json" ? JSON.stringify(value) : value;
 }
 function propertyIssue(field, value) {

package/dist/runtime/service-binding.d.ts

@@ -1,10 +1,11 @@
 import { Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import type { SqlError } from "effect/unstable/sql/SqlError";
+import type { BlobStorageBinding } from "../storage/provider.js";
 import type { Ontology } from "../ontology.js";
 import { OntologyBackend, type OntologyServiceRuntime } from "../service/runtime-contract.js";
 /** The service's backend on the runtime, over the SQL client in context. */
-export declare function backendLayer(ontology: Ontology): Layer.Layer<OntologyBackend, never, SqlClient.SqlClient>;
+export declare function backendLayer(ontology: Ontology, blobStorage?: Redacted.Redacted<BlobStorageBinding>): Layer.Layer<OntologyBackend, never, SqlClient.SqlClient>;
 /**
  * `@effect/sql-pg` on the pooled `ontology_app` connection string, with the TLS server name a
  * Neon endpoint needs.

package/dist/runtime/service-binding.js

@@ -1,6 +1,9 @@
 import * as PgClient from "@effect/sql-pg/PgClient";
 import { Effect, Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
+import { neonBlobProvider } from "../storage/neon.js";
+import { maintainBlobStorage } from "../storage/maintenance.js";
+import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
 import { generatedActions } from "./generated-actions.js";
@@ -18,18 +21,26 @@ function rejectedAs(operation) {
     return (rejection) => Effect.logWarning("ontology.principal.rejected").pipe(Effect.annotateLogs({ operation, reason: rejection.reason }), Effect.as(undefined));
 }
 /** The service's backend on the runtime, over the SQL client in context. */
-export function backendLayer(ontology) {
+export function backendLayer(ontology, blobStorage) {
     return Layer.effect(OntologyBackend, Effect.gen(function* () {
         const sql = yield* SqlClient.SqlClient;
         const runtime = makeOntologyRuntime(ontology, sql);
         const withSql = (effect) => Effect.provideService(effect, SqlClient.SqlClient, sql);
+        const binding = blobStorage ? Redacted.value(blobStorage) : undefined;
+        const provider = binding
+            ? yield* Effect.acquireRelease(Effect.sync(() => neonBlobProvider(binding)), (provider) => Effect.sync(() => provider.close?.()))
+            : undefined;
+        const blobs = provider ? blobRuntime(ontology, sql, provider) : undefined;
         return OntologyBackend.of({
+            ...(blobs ? { blobs } : {}),
+            ...(provider ? { maintainBlobs: maintainBlobStorage(sql, provider) } : {}),
             runAction: (input) => withSql(runAction(ontology, {
                 entity: input.entity,
                 action: input.action,
                 input: input.input,
                 principal: input.principal,
                 options: input.options,
+                ...(binding ? { branchId: binding.branchId } : {}),
                 afterCommit: input.afterCommit === undefined ? [] : [input.afterCommit],
                 ...(input.requestId === undefined ? {} : { requestId: input.requestId }),
                 ...(input.connections === undefined ? {} : { connections: input.connections }),
@@ -66,5 +77,5 @@ export function postgresLayer(databaseUrl) {
 /** The default runtime of `createOntologyService`: the SQL runtime on the workspace database. */
 export const sqlServiceRuntime = {
     generatedActions: (entity, ontology) => generatedActions(ontology, entity.name),
-    connect: ({ ontology, databaseUrl }) => backendLayer(ontology).pipe(Layer.provide(postgresLayer(databaseUrl))),
+    connect: ({ ontology, databaseUrl, blobStorage }) => backendLayer(ontology, blobStorage).pipe(Layer.provide(postgresLayer(databaseUrl))),
 };

package/dist/runtime/writes.js

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import { resolveBlobWrites } from "../storage/writes.js";
 import { Conflict } from "../errors.js";
 import { quoteIdentifier } from "../migrate/storage.js";
 import { InvalidValues } from "./errors.js";
@@ -21,7 +22,9 @@ function requireReferences(context, references) {
 }
 function insertRecord(context, entity, values, onConflict) {
     return Effect.gen(function* () {
-        const write = yield* prepareWrite(entity, values, "create");
+        const recordId = uuidv7();
+        const resolved = yield* resolveBlobWrites(context, entity, recordId, values, true);
+        const write = yield* prepareWrite(entity, resolved, "create");
         yield* requireReferences(context, write.references);
         const params = new Params();
         const principal = params.add(context.scope.principalId, "uuid");
@@ -34,7 +37,7 @@ function insertRecord(context, entity, values, onConflict) {
             ...write.columns.map(({ field }) => quoteIdentifier(field.column)),
         ];
         const placeholders = [
-            params.add(uuidv7(), "uuid"),
+            params.add(recordId, "uuid"),
             "now()",
             "now()",
             principal,
@@ -64,11 +67,12 @@ export function createRecord(context, entity, values) {
 }
 export function updateRecord(context, entity, id, values) {
     return Effect.gen(function* () {
-        const write = yield* prepareWrite(entity, values, "update");
         const before = yield* loadRecord(context, entity, id, "update");
         if (before === undefined) {
             return yield* notFound(entity, id);
         }
+        const resolved = yield* resolveBlobWrites(context, entity, id, values, false);
+        const write = yield* prepareWrite(entity, resolved, "update");
         yield* requireReferences(context, write.references);
         let after = before;
         if (write.columns.length > 0) {
@@ -121,6 +125,16 @@ export function upsertRecord(context, entity, property, values) {
                 issues: [{ path: [property], message: `${property} is required` }],
             }));
         }
+        // A file ticket for an existing record must not be consumed by a speculative INSERT.
+        if (entity.fields.some((candidate) => candidate.storage === "blob" && values[candidate.name] != null)) {
+            const lookup = new Params();
+            const [existing] = yield* context.run(`SELECT id::text AS id FROM ${quoteIdentifier(entity.table)}
+        WHERE ${quoteIdentifier(field.column)} = ${lookup.add(bindValue(field, key), field.sqlType)} FOR UPDATE`, lookup);
+            if (existing) {
+                const record = yield* updateRecord(context, entity, existing.id, values);
+                return { record, created: false };
+            }
+        }
         const created = yield* insertRecord(context, entity, values, ` ON CONFLICT (${quoteIdentifier(field.column)}) DO NOTHING`);
         if (created !== undefined) {
             return { record: created, created: true };

package/dist/service/api.js

@@ -1,5 +1,7 @@
 import { Effect, Layer, Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi, } from "effect/unstable/httpapi";
+import { storageGroup } from "../storage/api.js";
+import { DownloadRequest, TransferGrant } from "../storage/sessions.js";
 import { permissionOf, READ_VERB } from "../permissions.js";
 import { generatedActions } from "../runtime/generated-actions.js";
 import { Authentication } from "./authentication.js";
@@ -121,6 +123,14 @@ function entityGroup(planned, schemas, names) {
             error: recordErrors,
         }), `History of a ${definition.label.toLowerCase()}`, `What each action changed on the record, newest first. ${read}`),
         ...planned.traversals.map((traversal) => traversalEndpoint(planned, traversal, schemas.get(traversal.target), names.get(traversal.target) ?? { label: traversal.target, plural: traversal.target })),
+        ...planned.resolved.properties
+            .filter((property) => property.definition.type === "blob")
+            .map((property) => documented(HttpApiEndpoint.post(`blobs.${property.name}`, `${base}/:id/blobs/${property.name}/download`, {
+            params: { id: IdParam },
+            payload: DownloadRequest,
+            success: TransferGrant,
+            error: recordErrors,
+        }), `Download ${property.name}`, `Requires ${planned.name}:read. Historical revisions must belong to this record and field.`)),
         ...planned.actions.map((action) => actionEndpoint(planned, action)),
     ];
     const [first, ...rest] = endpoints.map(authenticated);
@@ -172,6 +182,11 @@ export function buildApi(plan) {
     ]));
     const groups = [
         serviceGroup(),
+        ...(plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
+            ? [
+                storageGroup(authenticated, actionErrors, (endpoint) => endpoint.middleware(ErrorResponses)),
+            ]
+            : []),
         ...plan.entities.map((planned) => entityGroup(planned, schemas, names)),
     ];
     const api = HttpApi.make("ontology")

package/dist/service/config.d.ts

@@ -1,4 +1,5 @@
 import { Redacted, Schema } from "effect";
+import { BlobStorageBinding } from "../storage/provider.js";
 import type { Principal } from "../runtime.js";
 import { type ConnectionTransportFactory, type LocalConnectionContext } from "./connections.js";
 import type { OntologyServiceRuntime } from "./runtime-contract.js";
@@ -29,6 +30,8 @@ export interface NeonAuthEnvironment {
 export interface OntologyEnvironment {
     /** The pooled connection string of the `ontology_app` role. */
     readonly databaseUrl: Redacted.Redacted<string>;
+    readonly blobStorage?: Redacted.Redacted<BlobStorageBinding>;
+    readonly storageMaintenanceKey?: Redacted.Redacted<string>;
     /** The control plane: it issues app tokens and serves their JWKS. */
     readonly segmentstreamUrl: string;
     /** App tokens must be issued for this application: `aud: app:<application id>`. */

package/dist/service/config.js

@@ -1,4 +1,5 @@
 import { Redacted, Schema } from "effect";
+import { BlobStorageBinding } from "../storage/provider.js";
 import { LocalConnectionContextError, readLocalConnectionContext, RUNTIME_CONTEXT_FD, } from "./connections.js";
 /** The environment of the workspace deployment's ontology service. */
 export const ENVIRONMENT_VARIABLES = {
@@ -83,12 +84,29 @@ export function configFromEnv(environment = process.env) {
     }
     const neonAuth = neonAuthFromEnv(read);
     const localConnections = localConnectionsFromEnv(environment);
+    let blobStorage;
+    if (read("SEGMENTSTREAM_ONTOLOGY_STORAGE")) {
+        try {
+            blobStorage = Redacted.make(Schema.decodeUnknownSync(BlobStorageBinding)(JSON.parse(read("SEGMENTSTREAM_ONTOLOGY_STORAGE"))));
+        }
+        catch {
+            throw new OntologyServiceConfigError({
+                message: "SEGMENTSTREAM_ONTOLOGY_STORAGE is invalid.",
+            });
+        }
+    }
     return {
         databaseUrl: checkDatabaseUrl(ENVIRONMENT_VARIABLES.databaseUrl, read(ENVIRONMENT_VARIABLES.databaseUrl)),
         segmentstreamUrl: normalizeUrl(ENVIRONMENT_VARIABLES.segmentstreamUrl, read(ENVIRONMENT_VARIABLES.segmentstreamUrl)),
         applicationId: read(ENVIRONMENT_VARIABLES.applicationId),
         workspaceId: read(ENVIRONMENT_VARIABLES.workspaceId),
         organizationId: read(ENVIRONMENT_VARIABLES.organizationId),
+        ...(blobStorage === undefined ? {} : { blobStorage }),
+        ...(read("SEGMENTSTREAM_ONTOLOGY_STORAGE_MAINTENANCE_KEY")
+            ? {
+                storageMaintenanceKey: Redacted.make(read("SEGMENTSTREAM_ONTOLOGY_STORAGE_MAINTENANCE_KEY")),
+            }
+            : {}),
         ...(neonAuth === undefined ? {} : { neonAuth }),
         ...(localConnections === undefined ? {} : { localConnections }),
     };

package/dist/service/handlers.js

@@ -1,6 +1,8 @@
 import { HttpServerResponse } from "effect/unstable/http";
 import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
+import { STORAGE_GROUP } from "../storage/api.js";
+import { Conflict } from "../errors.js";
 import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
 import { nameToWire } from "../authoring-names.js";
 import { principalFromWire } from "../authoring.js";
@@ -181,7 +183,7 @@ function runAction(planned, { name, generated }, ontology, hook, connections) {
             action: name,
             input: envelope.input,
             principal,
-            options: { validateOnly },
+            options: { ...envelope.options, validateOnly },
             requestId,
             connections: connections({
                 identityToken: identityToken(request),
@@ -219,6 +221,18 @@ function entityHandlers(built, planned, hooks, targets, connections) {
             .handle("query", (request) => find(toQuery(request.payload)))
             .handle("get", (request) => readOwn.pipe(Effect.andThen(() => backend.get({ entity: planned.name, id: request.params.id }))))
             .handle("history", (request) => readOwn.pipe(Effect.andThen(() => backend.history({ entity: planned.name, id: request.params.id, ...request.query })), Effect.map(page)));
+        for (const property of planned.resolved.properties.filter((property) => property.definition.type === "blob")) {
+            registered = registered.handle(`blobs.${property.name}`, (request) => Effect.gen(function* () {
+                const principal = yield* CurrentPrincipal;
+                if (!backend.blobs) {
+                    return yield* new Conflict({
+                        entity: planned.name,
+                        message: "File storage is not configured.",
+                    });
+                }
+                return yield* backend.blobs.download(planned.name, request.params.id, property.name, request.payload, principal);
+            }));
+        }
         for (const traversal of planned.traversals) {
             registered = registered.handle(`related.${traversal.name}`, (request) => traverse(planned, traversal, request, targets).pipe(Effect.provideService(OntologyBackend, backend)));
         }
@@ -324,11 +338,36 @@ function serviceHandlers(built) {
             .handle("signInCheck", checkSignIn(backend, signInLimiter));
     }));
 }
+function storageHandlers(built) {
+    return dynamicGroup(built.api, STORAGE_GROUP, (handlers) => Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        const configured = () => backend.blobs
+            ? Effect.succeed(backend.blobs)
+            : Effect.fail(new Conflict({ entity: "upload", message: "File storage is not configured." }));
+        let registered = handlers.handle("begin", (request) => Effect.gen(function* () {
+            const principal = yield* CurrentPrincipal;
+            const blobs = yield* configured();
+            return yield* blobs.begin(request.payload, principal);
+        }));
+        for (const method of ["status", "part", "complete", "cancel"]) {
+            registered = registered.handle(method, (request) => Effect.gen(function* () {
+                const principal = yield* CurrentPrincipal;
+                const blobs = yield* configured();
+                return yield* blobs[method](request.params.id, principal);
+            }));
+        }
+        return registered.handle("maintain", () => backend.maintainBlobs ??
+            Effect.fail(new Conflict({ entity: "upload", message: "File storage is not configured." })));
+    }));
+}
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
 export function handlersLayer(built, hooks, connections) {
     const targets = relationshipTargets(built.plan);
     const layers = [
         serviceHandlers(built),
+        ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
+            ? [storageHandlers(built)]
+            : []),
         ...built.plan.entities.map((planned) => entityHandlers(built, planned, hooks, targets, connections)),
     ];
     const [first, ...rest] = layers;

package/dist/service/runtime-contract.d.ts

@@ -1,4 +1,6 @@
 import { Context, Schema, type Effect, type Layer, type Redacted } from "effect";
+import type { BlobRuntime } from "../storage/sessions.js";
+import type { BlobStorageBinding } from "../storage/provider.js";
 import type { AnyAction } from "../action.js";
 import type { ResolvedEntity } from "../analyze.js";
 import type { ConnectionError, ConnectionTransport } from "../connection.js";
@@ -23,6 +25,8 @@ export interface RunActionInput {
     readonly principal: Principal;
     readonly options: {
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
     /**
      * Runs once the action has committed, outside its transaction, before `runAction` returns. It
@@ -63,6 +67,10 @@ declare const NotInvited_base: Schema.Class<NotInvited, Schema.TaggedStruct<"Not
 export declare class NotInvited extends NotInvited_base {
 }
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
+    readonly blobs?: BlobRuntime;
+    readonly maintainBlobs?: Effect.Effect<{
+        readonly removed: number;
+    }, unknown>;
     readonly runAction: (input: RunActionInput) => Effect.Effect<ActionOutcome, PermissionDenied | ActionRejected | Conflict | NotFound | ConnectionError>;
     readonly get: (input: {
         readonly entity: string;
@@ -111,6 +119,7 @@ export interface OntologyServiceRuntime {
     readonly connect: (input: {
         readonly ontology: Ontology;
         readonly databaseUrl: Redacted.Redacted<string>;
+        readonly blobStorage?: Redacted.Redacted<BlobStorageBinding>;
     }) => Layer.Layer<OntologyBackend, unknown>;
 }
 export {};

package/dist/service/schemas.d.ts

@@ -124,6 +124,8 @@ export declare const ActionEnvelope: Schema.Codec<{
     readonly input: unknown;
     readonly options?: {
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
 }>;
 export declare const ActionResponse: Schema.Struct<{
@@ -151,7 +153,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly column: Schema.optionalKey<Schema.String>;
             readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly name: Schema.String;
-            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
             readonly label: Schema.String;
             readonly description: Schema.optionalKey<Schema.String>;
             readonly optional: Schema.Boolean;
@@ -163,6 +165,8 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly min: Schema.optionalKey<Schema.Number>;
             readonly max: Schema.optionalKey<Schema.Number>;
             readonly maxLength: Schema.optionalKey<Schema.Number>;
+            readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly maxBytes: Schema.optionalKey<Schema.Number>;
             readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly value: Schema.String;
                 readonly label: Schema.String;
@@ -171,6 +175,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
         }>, {
             readonly renamedFrom: "renamed_from";
             readonly maxLength: "max_length";
+            readonly maxBytes: "max_bytes";
         }>>;
         readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
             readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{
@@ -259,7 +264,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly column: Schema.optionalKey<Schema.String>;
             readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly name: Schema.String;
-            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
             readonly label: Schema.String;
             readonly description: Schema.optionalKey<Schema.String>;
             readonly optional: Schema.Boolean;
@@ -271,6 +276,8 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly min: Schema.optionalKey<Schema.Number>;
             readonly max: Schema.optionalKey<Schema.Number>;
             readonly maxLength: Schema.optionalKey<Schema.Number>;
+            readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly maxBytes: Schema.optionalKey<Schema.Number>;
             readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly value: Schema.String;
                 readonly label: Schema.String;
@@ -279,6 +286,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
         }>, {
             readonly renamedFrom: "renamed_from";
             readonly maxLength: "max_length";
+            readonly maxBytes: "max_bytes";
         }>>;
         readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
             readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{

package/dist/service/schemas.js

@@ -1,3 +1,4 @@
+import { BlobValue } from "../blob.js";
 import { Schema, SchemaTransformation } from "effect";
 import { wireStruct } from "../wire.js";
 import { OntologyManifestWire } from "../manifest.js";
@@ -68,6 +69,8 @@ function propertyValue(definition) {
         }
         case "json":
             return Schema.Json.annotate(documentation);
+        case "blob":
+            return BlobValue.annotate(documentation);
     }
 }
 function recordFields(entity) {
@@ -226,11 +229,20 @@ export const HistoryPage = Schema.Struct({
 })
     .pipe(Schema.encodeKeys({ nextCursor: "next_cursor" }))
     .annotate({ identifier: "HistoryPage" });
+const uploadOptions = {
+    idempotencyKey: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128))),
+    createIntent: Schema.optionalKey(Schema.String.check(Schema.isUUID())),
+};
 const ActionOptions = wireStruct({
+    ...uploadOptions,
     validateOnly: Schema.optionalKey(Schema.Boolean.annotate({
         description: "Validate the input and report issues without a write.",
     })),
-}, { validateOnly: "validate_only" });
+}, {
+    validateOnly: "validate_only",
+    idempotencyKey: "idempotency_key",
+    createIntent: "create_intent",
+});
 /** The body of `POST /<entity>/actions/<action>`, as documented. */
 export function actionRequest(input) {
     return Schema.Struct({ input, options: Schema.optionalKey(ActionOptions) });
@@ -238,7 +250,11 @@ export function actionRequest(input) {
 /** The body of `POST /<entity>/actions/<action>`, as decoded: `runAction` validates the input. */
 export const ActionEnvelope = closedStruct({
     input: Schema.Unknown,
-    options: Schema.optionalKey(wireStruct({ validateOnly: Schema.optionalKey(Schema.Boolean) }, { validateOnly: "validate_only" })),
+    options: Schema.optionalKey(wireStruct({ validateOnly: Schema.optionalKey(Schema.Boolean), ...uploadOptions }, {
+        validateOnly: "validate_only",
+        idempotencyKey: "idempotency_key",
+        createIntent: "create_intent",
+    })),
 }, "Unknown key; use input and options");
 export const ActionResponse = Schema.Struct({
     result: Schema.Unknown.annotate({ description: "What the action returned." }),