@segmentstream-cloud/ontology 0.9.0 → 0.11.0

package/dist/storage/sessions.d.ts

@@ -0,0 +1,87 @@
+import { Effect, Schema } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { ActionRejected, Conflict, NotFound } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import type { Principal } from "../runtime.js";
+import type { BlobProvider } from "./provider.js";
+export declare const BeginUpload: Schema.encodeKeys<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly property: Schema.String;
+    readonly action: Schema.String;
+    readonly recordId: Schema.optionalKey<Schema.String>;
+    readonly createIntent: Schema.optionalKey<Schema.String>;
+    readonly idempotencyKey: Schema.optionalKey<Schema.String>;
+    readonly filename: Schema.String;
+    readonly contentType: Schema.String;
+    readonly size: Schema.Int;
+}>, {
+    readonly recordId: "record_id";
+    readonly createIntent: "create_intent";
+    readonly idempotencyKey: "idempotency_key";
+    readonly contentType: "content_type";
+}>;
+export type BeginUpload = typeof BeginUpload.Type;
+export declare const UploadView: Schema.encodeKeys<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly state: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly ticket: Schema.optionalKey<Schema.decodeTo<Schema.Struct<{
+        readonly uploadId: Schema.String;
+    }>, Schema.Struct<{
+        readonly upload_id: Schema.String;
+    }>, never, never>>;
+}>, {
+    readonly expiresAt: "expires_at";
+}>;
+export declare const TransferGrant: Schema.encodeKeys<Schema.Struct<{
+    readonly url: Schema.String;
+    readonly method: Schema.Literals<readonly ["GET", "PUT"]>;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly expiresAt: Schema.String;
+}>, {
+    readonly expiresAt: "expires_at";
+}>;
+export declare const DownloadRequest: Schema.encodeKeys<Schema.Struct<{
+    readonly revisionId: Schema.optionalKey<Schema.String>;
+    readonly inline: Schema.optionalKey<Schema.Boolean>;
+}>, {
+    readonly revisionId: "revision_id";
+}>;
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export declare function blobRuntime(ontology: Ontology, sql: SqlClient.SqlClient, provider: BlobProvider["Service"]): {
+    begin: (input: BeginUpload, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, ActionRejected | import("../errors.js").PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    status: (id: string, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, import("../errors.js").PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    part: (id: string, principal: Principal) => Effect.Effect<import("./provider.js").TransferGrant, import("../errors.js").PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    complete: (id: string, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, ActionRejected | import("../errors.js").PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    cancel: (id: string, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, import("../errors.js").PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    download: (entityName: string, recordId: string, propertyName: string, input: typeof DownloadRequest.Type, principal: Principal) => Effect.Effect<import("./provider.js").TransferGrant, import("../errors.js").PermissionDenied | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+};
+export type BlobRuntime = ReturnType<typeof blobRuntime>;

package/dist/storage/sessions.js

@@ -0,0 +1,341 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { uploadInput, BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES } from "../blob.js";
+import { wireStruct } from "../wire.js";
+import { ActionRejected, Conflict, NotFound } from "../errors.js";
+import { authorizeBlobOperation } from "./authorization.js";
+import { resolveAction } from "../runtime/pipeline.js";
+import { makeOntologyRuntime } from "../runtime/sql-runtime.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 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) {
+        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:
+            return false;
+    }
+}
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export function blobRuntime(ontology, sql, provider) {
+    const binding = provider.binding;
+    const conflict = () => new Conflict({ entity: "upload", message: "The upload is unavailable or busy." });
+    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
+      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);
+        return row;
+    });
+    const begin = (input, principal) => Effect.gen(function* () {
+        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 found = resolveAction(ontology, input.entity, input.action);
+        if (!entity ||
+            entity.source ||
+            !property ||
+            !found ||
+            !property.accept?.includes(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,
+        });
+        if (!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);
+            if (input.recordId) {
+                yield* makeOntologyRuntime(ontology, sql).get({
+                    entity: input.entity,
+                    id: input.recordId,
+                });
+            }
+            yield* sql.unsafe(`SELECT pg_advisory_xact_lock(818723)`);
+            const existing = yield* sql.unsafe(`SELECT id FROM "_blob_uploads" WHERE id = $1::uuid`, [
+                id,
+            ]);
+            if (existing.length) {
+                const row = yield* load(id, principal);
+                if (row.expired ||
+                    row.action !== `${input.entity}.${input.action}` ||
+                    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();
+                }
+                if (["uploading", "completing", "ready"].includes(row.state)) {
+                    return { row, recover: false };
+                }
+                if (row.state !== "initializing" || (row.claim && !row.claim_stale)) {
+                    return yield* conflict();
+                }
+                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 state IN ('initializing', 'uploading', 'completing', 'ready', 'deleting')) AS pending`, [principal.id]);
+            if (Number(usage.bytes) + input.size > binding.quotaBytes ||
+                Number(usage.pending) >= 8) {
+                return yield* new ActionRejected({
+                    message: "File storage capacity or pending upload limit reached.",
+                });
+            }
+            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,
+                `${input.entity}.${input.action}`,
+                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 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,
+            }));
+        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 });
+            }
+            return yield* conflict();
+        }
+        return yield* sql.withTransaction(load(row.id, principal).pipe(Effect.map(view)));
+    });
+    const status = (id, principal) => sql.withTransaction(load(id, principal).pipe(Effect.map(view)));
+    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
+            ? 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 complete = (id, principal) => 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 (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" ||
+            row.state === "initializing") {
+            return yield* conflict();
+        }
+        if (["deleted", "deleting", "canceled"].includes(row.state)) {
+            return view(row);
+        }
+        yield* sql.unsafe(`UPDATE "_blob_uploads" SET state = 'canceled', expires_at = now(), claim = NULL
+      WHERE id = $1::uuid`, [id]);
+        return view(yield* load(id, principal));
+    }));
+    const download = (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* () {
+            yield* authorizeBlobOperation(ontology, sql, principal.id, [`${entityName}:read`]);
+            let revisionId = input.revisionId;
+            if (!revisionId) {
+                const record = yield* makeOntologyRuntime(ontology, sql).get({
+                    entity: entityName,
+                    id: recordId,
+                });
+                revisionId = record[propertyName]?.id;
+            }
+            const [blob] = yield* sql.unsafe(`SELECT b.key, b.filename, b.content_type FROM "_blobs" b JOIN "_blob_references" r ON r.blob_id = b.id
+         WHERE b.id = $1::uuid AND b.state = 'retained' 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]);
+            if (!blob) {
+                return yield* new NotFound({
+                    entity: entityName,
+                    id: recordId,
+                    message: "File not found.",
+                });
+            }
+            return blob;
+        }));
+        return yield* provider.download({
+            key: blob.key,
+            filename: blob.filename,
+            contentType: blob.content_type,
+            inline: input.inline === true && blob.content_type.startsWith("image/"),
+        });
+    });
+    return { begin, status, part, complete, cancel, download };
+}

package/dist/storage/tables.d.ts

@@ -0,0 +1,2 @@
+/** Storage metadata lives in the ontology database and is migrated by its SDK. */
+export declare const BLOB_TABLES_DDL: ReadonlyArray<string>;

package/dist/storage/tables.js

@@ -0,0 +1,55 @@
+/** Storage metadata lives in the ontology database and is migrated by its SDK. */
+export const BLOB_TABLES_DDL = [
+    `CREATE TABLE IF NOT EXISTS "_blobs" (
+    "id" uuid PRIMARY KEY,
+    "branch_id" text NOT NULL,
+    "key" text NOT NULL UNIQUE,
+    "filename" text NOT NULL,
+    "content_type" text NOT NULL,
+    "size" bigint NOT NULL CHECK ("size" > 0),
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "state" text NOT NULL CHECK ("state" IN ('ready', 'retained', 'deleting', 'deleted')),
+    "entity_id" text,
+    "property_id" text,
+    "record_id" uuid
+  )`,
+    `CREATE TABLE IF NOT EXISTS "_blob_uploads" (
+    "id" uuid PRIMARY KEY,
+    "blob_id" uuid NOT NULL UNIQUE REFERENCES "_blobs" ("id"),
+    "principal_id" uuid NOT NULL REFERENCES "user" ("id"),
+    "branch_id" text NOT NULL,
+    "manifest_hash" text NOT NULL,
+    "action" text NOT NULL,
+    "entity_id" text NOT NULL,
+    "property_id" text NOT NULL,
+    "record_id" uuid,
+    "create_intent" uuid,
+    "filename" text NOT NULL,
+    "content_type" text NOT NULL,
+    "size" bigint NOT NULL CHECK ("size" > 0),
+    "provider_upload_id" text,
+    "state" text NOT NULL CHECK ("state" IN
+      ('initializing', 'uploading', 'completing', 'ready', 'consumed', 'canceled', 'deleting', 'deleted')),
+    "claim" uuid,
+    "claimed_at" timestamptz,
+    "created_at" timestamptz NOT NULL DEFAULT now(),
+    "expires_at" timestamptz NOT NULL DEFAULT now() + interval '1 hour',
+    CHECK (("record_id" IS NULL) <> ("create_intent" IS NULL))
+  )`,
+    `CREATE INDEX IF NOT EXISTS "_blob_uploads_expiry_idx" ON "_blob_uploads" ("state", "expires_at")`,
+    `CREATE TABLE IF NOT EXISTS "_blob_references" (
+    "blob_id" uuid NOT NULL REFERENCES "_blobs" ("id"),
+    "entity_id" text NOT NULL,
+    "property_id" text NOT NULL,
+    "record_id" uuid NOT NULL,
+    "action_id" uuid NOT NULL,
+    PRIMARY KEY ("blob_id", "entity_id", "property_id", "record_id")
+  )`,
+    `CREATE TABLE IF NOT EXISTS "_blob_action_results" (
+    "principal_id" uuid NOT NULL REFERENCES "user" ("id"),
+    "key" text NOT NULL,
+    "fingerprint" text NOT NULL,
+    "outcome" jsonb,
+    PRIMARY KEY ("principal_id", "key")
+  )`,
+];

package/dist/storage/writes.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+import { Conflict } from "../errors.js";
+import type { StoredValues } from "../runtime.js";
+import type { EntityModel } from "../runtime/model.js";
+import type { WriteContext } from "../runtime/writes.js";
+/** Resolves tickets in the action's transaction. There is no provider I/O here. */
+export declare function resolveBlobWrites(context: WriteContext, entity: EntityModel, recordId: string, values: StoredValues, creating: boolean): Effect.Effect<Record<string, unknown>, Conflict | import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/storage/writes.js

@@ -0,0 +1,88 @@
+import { Effect } from "effect";
+import { authorizeBlobOperation } from "./authorization.js";
+import { generatedActionPermissions } from "../permissions.js";
+import { Conflict } from "../errors.js";
+import { isRecordId } from "../runtime/records.js";
+import { Params } from "../runtime/statement.js";
+/** Resolves tickets in the action's transaction. There is no provider I/O here. */
+export function resolveBlobWrites(context, entity, recordId, values, creating) {
+    return Effect.gen(function* () {
+        const resolved = { ...values };
+        for (const property of entity.manifest.properties.filter((field) => field.type === "blob")) {
+            const value = values[property.name];
+            if (value === undefined || value === null) {
+                continue;
+            }
+            const reject = () => new Conflict({
+                entity: entity.name,
+                property: property.name,
+                message: "This upload cannot be attached to this record.",
+            });
+            const uploadId = typeof value === "object" && "uploadId" in value ? value.uploadId : undefined;
+            if (typeof uploadId !== "string" ||
+                !isRecordId(uploadId) ||
+                !context.scope.branchId ||
+                !context.scope.principalId ||
+                !context.scope.blobActionKey) {
+                return yield* reject();
+            }
+            const [actionEntity, actionName] = context.scope.action.split(".");
+            const authored = context.model.ontology.entities
+                .find((item) => item.name === actionEntity)
+                ?.actions.find((item) => item.name === actionName);
+            yield* authorizeBlobOperation(context.model.ontology, {
+                unsafe: (statement, args) => {
+                    const params = new Params();
+                    // The authorization statements use positional parameters and no dynamic identifiers.
+                    for (const value of args) {
+                        params.add(value, "text");
+                    }
+                    return context.run(statement, params);
+                },
+            }, context.scope.principalId, authored ? [authored.permission] : generatedActionPermissions(actionEntity, actionName)).pipe(Effect.catchTag("PermissionDenied", () => Effect.fail(reject())));
+            const params = new Params();
+            const rows = yield* context.run(`SELECT u.*, b.id::text AS blob_id, b.filename, b.content_type, b.size::text AS size,
+          to_char(b.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at
+         FROM "_blob_uploads" u JOIN "_blobs" b ON b.id = u.blob_id
+         JOIN "user" p ON p.id = u.principal_id AND p.active = true
+         WHERE u.id = ${params.add(uploadId, "uuid")}
+           AND u.principal_id = ${params.add(context.scope.principalId, "uuid")}
+           AND u.branch_id = ${params.add(context.scope.branchId, "text")}
+           AND u.manifest_hash = ${params.add(context.model.ontology.manifest.hash, "text")}
+           AND u.action = ${params.add(context.scope.action, "text")}
+           AND u.entity_id = ${params.add(entity.manifest.id, "text")}
+           AND u.property_id = ${params.add(property.name, "text")}
+           AND u.state = 'ready' AND u.expires_at > now() AND b.state = 'ready'
+         FOR UPDATE OF u, b FOR SHARE OF p`, params);
+            const row = rows[0];
+            if (!row ||
+                (creating
+                    ? row.create_intent !== context.scope.createIntent
+                    : row.record_id !== recordId.toLowerCase())) {
+                return yield* reject();
+            }
+            const consume = new Params();
+            yield* context.run(`UPDATE "_blob_uploads" SET state = 'consumed'
+        WHERE id = ${consume.add(uploadId, "uuid")}`, consume);
+            const retain = new Params();
+            yield* context.run(`UPDATE "_blobs" SET state = 'retained',
+        entity_id = ${retain.add(entity.manifest.id, "text")},
+        property_id = ${retain.add(property.name, "text")}, record_id = ${retain.add(recordId, "uuid")}
+        WHERE id = ${retain.add(row.blob_id, "uuid")}`, retain);
+            const reference = new Params();
+            yield* context.run(`INSERT INTO "_blob_references"
+        (blob_id, entity_id, property_id, record_id, action_id) VALUES
+        (${reference.add(row.blob_id, "uuid")}, ${reference.add(entity.manifest.id, "text")},
+        ${reference.add(property.name, "text")}, ${reference.add(recordId, "uuid")},
+        ${reference.add(context.scope.actionId, "uuid")})`, reference);
+            resolved[property.name] = {
+                id: row.blob_id,
+                filename: row.filename,
+                contentType: row.content_type,
+                size: Number(row.size),
+                createdAt: row.created_at,
+            };
+        }
+        return resolved;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -20,6 +20,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./nitro": {
+      "types": "./dist/nitro.d.ts",
+      "import": "./dist/nitro.js"
     }
   },
   "bin": {
@@ -43,6 +47,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1148.0",
+    "@aws-sdk/s3-request-presigner": "^3.1148.0",
     "@effect/sql-pg": "4.0.0-rc.113",
     "jose": "^6.2.12",
     "tsx": "4.21.0"
@@ -52,6 +58,7 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "0.4.6",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@types/node": "^24",
     "effect": "4.0.0-rc.113",
     "typescript": "^5.9",