@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/pipeline.js

@@ -0,0 +1,597 @@
+import { createHash, randomUUID } from "node:crypto";
+import { Cause, Data, Duration, Effect, Option, Schema } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { isSqlError } from "effect/unstable/sql/SqlError";
+import { ActionIdentity } from "../action.js";
+import { ActionConfirmation } from "../confirmation.js";
+import { ConnectionError, ConnectionTransport, connectionContext } from "../connection.js";
+import { Files } from "../files.js";
+import { FileAccess, unavailableFiles } from "../storage/file-access.js";
+import { Conflict, PermissionDenied, } from "../errors.js";
+import { canonicalJson } from "../manifest.js";
+import { CHANNEL_USERS_TABLE, USER_TABLE } from "../migrate/storage.js";
+import { CHANNEL_IDENTITIES_FROM, LIVE_CHANNEL_IDENTITY, SIGN_IN_ORIGIN_SQL, USER_IDENTITY_TABLE, } from "./user-identity-sql.js";
+import { ATTACHMENTS_TABLE } from "../storage/tables.js";
+import { beginReplicationWrite } from "../replication/transaction.js";
+import { RuntimeDeployment } from "./deployment.js";
+import { requireDeploymentCapability } from "../deployment.js";
+import { authorizeBlobOperation } from "../storage/authorization.js";
+import { effectiveScope, generatedActionPermissions, missingPermission, parsePermission, } from "../permissions.js";
+import { OntologyReads, OntologyRuntime } from "../runtime.js";
+import { UnknownAction, ValidationIssue, WorkflowRecoveryUnavailable, } from "./errors.js";
+import { generatedActions, writesOnlyThroughActions } from "./generated-actions.js";
+import { Edit } from "./history.js";
+import { canonicalInstant, isRecordId } from "./records.js";
+import { makeOntologyRuntime } from "./sql-runtime.js";
+import { AgentFileRecords, resolveFileRecord } from "./files.js";
+import { validate } from "./validation.js";
+import { evaluateTriggers, insertStarts, matchingTriggers, startCommitted, WorkflowStarter, } from "./workflow-starts.js";
+import { sendQueuedSignInEmails, SignInLinks } from "./sign-in-links.js";
+import { ACTION_TRANSACTION_LIMITS, ActionTransactions } from "./action-transactions.js";
+import { actionTransaction } from "./action-deadlocks.js";
+/** Keep every primary, cleanup and interruption reason when hiding SQL failures from callers. */
+const sqlFailuresAsDefects = (effect) => effect.pipe(Effect.catchCause((cause) => Effect.failCause(Cause.fromReasons(cause.reasons.map((reason) => reason._tag === "Fail" && isSqlError(reason.error)
+    ? Cause.makeDieReason(reason.error)
+    : reason)))));
+/** How long an action's `confirm` may take: a person waits for the card it describes. */
+export const CONFIRM_TIMEOUT = Duration.seconds(15);
+/** How long `prepare` may take, connection calls included; each call has its own 30 s deadline. */
+export const PREPARE_TIMEOUT = Duration.seconds(60);
+export const ActionValidation = Schema.Struct({
+    ok: Schema.Boolean,
+    issues: Schema.Array(ValidationIssue),
+});
+/** The response of an action: its result, the input's validation, and the records it changed. */
+export const ActionOutcome = Schema.Struct({
+    result: Schema.Json,
+    validation: ActionValidation,
+    edits: Schema.Array(Edit),
+});
+const VALID = { ok: true, issues: [] };
+/** Rolls back the transaction of a write that ran only to be validated. */
+class ValidationRollback extends Data.TaggedError("ValidationRollback") {
+}
+/**
+ * A validated write's NotFound or ScopeViolated as a validation issue. A record that was not found
+ * is at the input key that holds its id; a scope the change would leave is at the input's root.
+ */
+function writeIssue(input, error) {
+    const key = error._tag === "NotFound" && typeof input === "object" && input !== null
+        ? Object.entries(input).find(([, value]) => value === error.id)?.[0]
+        : undefined;
+    return { path: key === undefined ? [] : [key], message: error.message };
+}
+/**
+ * The entity's authored action of that name with the permission it requires, or else its generated
+ * one with the permissions named after it.
+ */
+export function resolveAction(ontology, entityName, actionName) {
+    const entity = ontology.entities.find((candidate) => candidate.name === entityName);
+    if (entity === undefined) {
+        return undefined;
+    }
+    const authored = entity.actions.find((candidate) => candidate.name === actionName);
+    if (authored !== undefined) {
+        return { action: authored.action, permissions: [authored.permission], generated: false };
+    }
+    const generated = generatedActions(ontology, entityName)[actionName];
+    return generated === undefined
+        ? undefined
+        : {
+            action: generated,
+            permissions: generatedActionPermissions(entityName, actionName),
+            generated: true,
+        };
+}
+/**
+ * The scopes the principal's grants put on an action's writes of its own entity. An authored action
+ * checks every write of its entity against the scope of its permission. A generated action checks
+ * records it creates against `<entity>:create` and records it changes against the permission of its
+ * verb; `upsert_by_<property>` checks against `create` or `update`, whichever it does. `undefined`
+ * when every permission is held unscoped, so that unscoped principals write as before.
+ */
+export function writeGuard(entity, found, principal) {
+    const check = (permission) => {
+        const where = effectiveScope(permission, principal);
+        return where === undefined ? undefined : { permission, scope: { reader: principal, where } };
+    };
+    let create;
+    let change;
+    if (principal.scopes === undefined || principal.scopes.length === 0) {
+        return undefined;
+    }
+    for (const permission of found.permissions) {
+        const scoped = check(permission);
+        if (!found.generated) {
+            create = scoped;
+            change = scoped;
+        }
+        else if (parsePermission(permission)?.verb === "create") {
+            create = scoped;
+        }
+        else {
+            change = scoped;
+        }
+    }
+    return create === undefined && change === undefined
+        ? undefined
+        : {
+            entity,
+            ...(create === undefined ? {} : { create }),
+            ...(change === undefined ? {} : { change }),
+        };
+}
+/** The entity's authored action of that name, or else its generated one. */
+export function findAction(ontology, entityName, actionName) {
+    return resolveAction(ontology, entityName, actionName)?.action;
+}
+/** A transport for a service that has none: every call is refused as a platform fault. */
+const NO_CONNECTIONS = {
+    request: (call) => Effect.fail(new ConnectionError({
+        connection: call.connection,
+        reason: "not_granted",
+        message: "This ontology service has no connection transport.",
+        retryable: false,
+    })),
+};
+/**
+ * Runs an action the way every action runs, authored or generated:
+ *
+ * 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, unless the action is generated, the principal's permission for it is
+ *    scoped and the input holds no upload: then run step 6 in a transaction that is
+ *    always rolled back, and answer a NotFound or ScopeViolated of the writes as a validation issue;
+ * 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; when a trigger matches the action, make
+ *    sure through the {@link WorkflowStarter} in context that a recovery run will sweep after the
+ *    transaction's deadline, and refuse the action with WorkflowRecoveryUnavailable when it cannot;
+ * 6. open a transaction and run the handler with what `prepare` returned and the runtime, which
+ *    records history rows for every write, under one action id, with `created_by`/`updated_by` set to
+ *    the principal;
+ * 7. evaluate the action triggers that match the action, and insert the starts they decide, in the
+ *    same transaction: a trigger function that throws rolls the action back, an input its workflow
+ *    does not accept fails it with TriggerInputInvalid;
+ * 8. commit, or roll back on any failure, defect or interruption; an action explicitly declared
+ *    retryOnDeadlock may repeat steps 6–8 after a confirmed deadlock rollback, with fresh state;
+ * 9. start the decided runs through the {@link WorkflowStarter} in context, then run the
+ *    after-commit effects, outside the transaction.
+ *
+ * Database failures are defects.
+ */
+export function runAction(ontology, request) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const deployment = Option.getOrUndefined(yield* Effect.serviceOption(RuntimeDeployment));
+        if (deployment) {
+            yield* Effect.sync(() => requireDeploymentCapability(deployment));
+        }
+        const qualified = `${request.entity}.${request.action}`;
+        const found = resolveAction(ontology, request.entity, request.action);
+        if (found === undefined) {
+            return yield* new UnknownAction({
+                entity: request.entity,
+                action: request.action,
+                message: writesOnlyThroughActions(ontology, request.entity, request.action) ??
+                    `${qualified} is not an action of this ontology.`,
+            });
+        }
+        const { action } = found;
+        // An authored action that declares the entities it writes may write only those.
+        const declaredTargets = found.generated
+            ? undefined
+            : ontology.manifest.entities
+                .find((candidate) => candidate.name === request.entity)
+                ?.actions.find((candidate) => candidate.name === request.action)?.writes;
+        const declaredWrites = declaredTargets === undefined ? undefined : new Set(declaredTargets);
+        if (deployment?.target === "preview" && action.connections.length > 0) {
+            yield* Effect.sync(() => requireDeploymentCapability(deployment, "connections"));
+        }
+        const newUserHook = request.options?.newUserHook === true;
+        if (newUserHook &&
+            (ontology.signIn.onNewUser !== `${request.entity}:${request.action}` ||
+                action.prepare !== undefined ||
+                action.connections.length > 0 ||
+                action.hints?.idempotent !== true ||
+                (request.afterCommit?.length ?? 0) > 0)) {
+            return yield* Effect.die(new Error("Invalid onNewUser action."));
+        }
+        const decoded = validate(action.input, request.input);
+        if (!decoded.ok) {
+            return { result: null, validation: { ok: false, issues: decoded.issues }, edits: [] };
+        }
+        const missing = missingPermission(found.permissions, request.principal);
+        if (missing !== undefined) {
+            return yield* new PermissionDenied({
+                permission: missing,
+                message: `${qualified} requires ${missing}, which the principal's roles do not grant.`,
+            });
+        }
+        const confirming = request.options?.confirm;
+        // A principal whose permission for the action is scoped may not read what `confirm` reads
+        // about a record outside the scope: it gets the action's fields, read as it may read them.
+        if (confirming !== undefined) {
+            return {
+                result: action.confirm === undefined ||
+                    writeGuard(request.entity, found, request.principal) !== undefined
+                    ? null
+                    : yield* confirmation(ontology, sql, action, qualified, {
+                        input: decoded.value,
+                        principal: request.principal,
+                        locale: confirming.locale,
+                        requestId: request.requestId ?? randomUUID(),
+                    }),
+                validation: VALID,
+                edits: [],
+            };
+        }
+        const hasUploads = (value) => typeof value === "object" &&
+            value !== null &&
+            ("uploadId" in value || Object.values(value).some(hasUploads));
+        // The tickets the caller handed this action, which it settles when it commits.
+        const suppliedUploads = (value, found = new Set()) => {
+            if (typeof value === "object" && value !== null) {
+                const uploadId = "uploadId" in value ? value.uploadId : undefined;
+                if (typeof uploadId === "string" && isRecordId(uploadId)) {
+                    found.add(uploadId.toLowerCase());
+                }
+                for (const item of Object.values(value)) {
+                    suppliedUploads(item, found);
+                }
+            }
+            return found;
+        };
+        const key = request.options?.idempotencyKey;
+        // A UUID in either case names one record; the uuid column answers in lower case.
+        const createIntent = request.options?.createIntent?.toLowerCase();
+        const hasBlobProperties = ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"));
+        const consumesUpload = action.transactional &&
+            hasBlobProperties &&
+            (hasUploads(decoded.value) || key !== undefined || (action.files?.length ?? 0) > 0);
+        const guard = writeGuard(request.entity, found, request.principal);
+        // A scoped generated write is validated by running it and rolling it back: its scope checks
+        // need the record as the write would leave it. Authored handlers run only when executed.
+        const validateOnly = request.options?.validateOnly === true;
+        if (validateOnly && (guard === undefined || !found.generated || consumesUpload)) {
+            return { result: null, validation: VALID, edits: [] };
+        }
+        // Inside a caller's transaction, the commit would come after the after-commit effects, and
+        // `prepare` would hold the caller's locks while it waits for a provider.
+        if (Option.isSome(yield* Effect.serviceOption(sql.transactionService))) {
+            return yield* Effect.die(new Error(`${qualified} must run outside any transaction.`));
+        }
+        const actionId = randomUUID();
+        const requestId = request.requestId ?? actionId;
+        const context = {
+            input: decoded.value,
+            principal: request.principal,
+            requestId,
+            ...(request.runtime === undefined ? {} : { runtime: request.runtime }),
+        };
+        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: 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, request.principal.execution, request.principal.workflow);
+                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(sqlFailuresAsDefects);
+            if (saved) {
+                return saved;
+            }
+        }
+        const prepared = action.prepare === undefined
+            ? undefined
+            : yield* prepare(ontology, sql, action, context, request.connections, qualified, {
+                principal: request.principal,
+                action: qualified,
+                idempotencyKey: key,
+                createIntent,
+            });
+        if (!action.transactional) {
+            return { result: prepared ?? null, validation: VALID, edits: [] };
+        }
+        const admission = Option.getOrUndefined(yield* Effect.serviceOption(ActionTransactions));
+        const configuredLimits = admission?.limits ?? ACTION_TRANSACTION_LIMITS;
+        const limits = newUserHook
+            ? {
+                handlerTimeoutMs: Math.min(5_000, configuredLimits.handlerTimeoutMs),
+                statementTimeoutMs: Math.min(5_000, configuredLimits.statementTimeoutMs),
+                lockTimeoutMs: Math.min(5_000, configuredLimits.lockTimeoutMs),
+            }
+            : configuredLimits;
+        // Triggers are definitions; all mutable runtime and trigger state belongs to one attempt.
+        const triggers = matchingTriggers(ontology, request.entity, request.action, request.principal);
+        const starter = Option.getOrUndefined(yield* Effect.serviceOption(WorkflowStarter));
+        // Before the transaction: whatever it commits must be swept if this request does not start it.
+        if (triggers.length > 0 && !validateOnly && starter !== undefined) {
+            yield* starter.ensureRecovery({ commitBy: Date.now() + limits.handlerTimeoutMs }).pipe(Effect.mapError((error) => new WorkflowRecoveryUnavailable({
+                message: `${qualified} was not run: ${error.message}`,
+                cause: error,
+            })));
+        }
+        const transaction = actionTransaction(sql, () => {
+            const edits = [];
+            const held = new Map();
+            let starts = [];
+            const signInEmails = [];
+            const runtime = makeOntologyRuntime(ontology, sql, {
+                action: qualified,
+                actionId,
+                principalId: request.principal.id,
+                ...(request.principal.execution ? { execution: request.principal.execution } : {}),
+                ...(request.principal.workflow ? { workflow: request.principal.workflow } : {}),
+                ...(key ? { blobActionKey: key } : {}),
+                ...(request.branchId ? { branchId: request.branchId } : {}),
+                ...(createIntent ? { createIntent } : {}),
+                ...(declaredWrites ? { declaredWrites } : {}),
+                onEdit: (edit) => edits.push(edit),
+                onSignInEmail: (email) => signInEmails.push(email),
+                ...(triggers.length > 0
+                    ? {
+                        onSnapshot: (snapshot) => {
+                            if (snapshot.entity !== request.entity) {
+                                return;
+                            }
+                            const previous = held.get(snapshot.id);
+                            held.set(snapshot.id, {
+                                before: previous === undefined ? snapshot.before : previous.before,
+                                after: snapshot.after,
+                            });
+                        },
+                    }
+                    : {}),
+                replicationInitialized: true,
+                ...(newUserHook ? { protectPrincipals: true } : {}),
+                ...(guard === undefined ? {} : { guard }),
+            });
+            const handle = action.handler;
+            const handler = Effect.gen(function* () {
+                const identities = isRecordId(context.principal.id)
+                    ? yield* sql
+                        .unsafe(`SELECT "i"."provider", "i"."subject", true AS "verified", "i"."username" ` +
+                        `FROM ${CHANNEL_IDENTITIES_FROM} ` +
+                        `WHERE "i"."user_id" = $1::uuid AND ${LIVE_CHANNEL_IDENTITY}`, [context.principal.id])
+                        .pipe(Effect.map((found) => Schema.decodeUnknownSync(Schema.Array(ActionIdentity))(found.map(({ username, ...identity }) => ({
+                        ...identity,
+                        ...(username === null ? {} : { username }),
+                    })))))
+                    : [];
+                const [provenance] = isRecordId(context.principal.id)
+                    ? yield* sql.unsafe(`SELECT COALESCE(c."created_via", CASE
+           WHEN u."kind"::text = 'service' THEN 'service'
+           WHEN NOT EXISTS (SELECT 1 FROM "${USER_IDENTITY_TABLE}" i WHERE i."user_id" = u."id"
+             AND i."origin"::text IN ${SIGN_IN_ORIGIN_SQL} AND i."revoked_at" IS NULL) OR EXISTS (
+             SELECT 1 FROM "user_history" h WHERE h."record_id" = u."id"
+             AND h."action" = 'user.invite' AND h."kind"::text = 'create'
+           ) THEN 'invite' ELSE 'email' END) AS "created_via"
+         FROM "${USER_TABLE}" u
+         LEFT JOIN "${CHANNEL_USERS_TABLE}" c ON c."user_id" = u."id"
+         WHERE u."id" = $1::uuid`, [context.principal.id])
+                    : [];
+                return yield* handle({
+                    ...context,
+                    principal: {
+                        ...context.principal,
+                        identities,
+                        createdVia: provenance?.created_via ?? "unknown",
+                        authenticatedVia: context.principal.authenticatedVia ?? "unknown",
+                    },
+                    prepared,
+                });
+            });
+            let replay;
+            const transactionalHandler = Effect.gen(function* () {
+                if (newUserHook) {
+                    // Administrative mutations lock User first too. Keep this order before the lifecycle row
+                    // so handler writes that reference the user cannot deadlock with blocking/deactivation.
+                    yield* sql.unsafe(`SELECT "id" FROM "${USER_TABLE}" WHERE "id" = $1::uuid FOR UPDATE`, [
+                        request.principal.id,
+                    ]);
+                    const [pending] = yield* sql.unsafe(`SELECT 1 FROM "${CHANNEL_USERS_TABLE}" c JOIN "${USER_TABLE}" u ON u."id" = c."user_id"
+           WHERE c."user_id" = $1::uuid AND c."created_via" NOT IN ('invite', 'email')
+           AND c."blocked_at" IS NULL AND c."on_new_user_completed_at" IS NULL AND u."active" FOR UPDATE OF c`, [request.principal.id]);
+                    if (pending === undefined) {
+                        return null;
+                    }
+                }
+                // Workloads and workflow users are re-checked against the database in the transaction.
+                if (request.principal.execution !== undefined ||
+                    request.principal.workflow !== undefined) {
+                    yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions, request.principal.execution, request.principal.workflow);
+                }
+                if (consumesUpload) {
+                    yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions, request.principal.execution, request.principal.workflow);
+                    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 (validateOnly) {
+                    return yield* new ValidationRollback();
+                }
+                if (triggers.length > 0 && edits.some((edit) => edit.entity === request.entity)) {
+                    const [now] = yield* sql.unsafe(`SELECT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS "at"`);
+                    starts = yield* evaluateTriggers(triggers, {
+                        ontology,
+                        entity: request.entity,
+                        action: request.action,
+                        definition: action,
+                        generated: found.generated,
+                        actionId,
+                        at: canonicalInstant(now.at),
+                        principal: request.principal,
+                        input: decoded.value,
+                        result,
+                        edits,
+                        held,
+                        load: (id) => runtime.get({ entity: request.entity, id }).pipe(Effect.map((record) => record), Effect.catchTag("NotFound", () => Effect.succeed(undefined))),
+                    });
+                    yield* insertStarts(sql, starts);
+                }
+                if (newUserHook) {
+                    yield* sql.unsafe(`UPDATE "${CHANNEL_USERS_TABLE}" SET "on_new_user_completed_at" = now() WHERE "user_id" = $1::uuid`, [request.principal.id]);
+                }
+                if (consumesUpload) {
+                    // A ticket this action was given and did not store, such as a file it found already
+                    // kept, is released with the commit: it stops counting towards the caller's open
+                    // uploads, and storage maintenance removes its bytes. A rejected action rolls this
+                    // back and leaves the ticket for a retry; a retry of this committed action replays
+                    // its saved outcome. Promoted chat attachments keep their file and their upload.
+                    for (const uploadId of suppliedUploads(decoded.value)) {
+                        yield* sql.unsafe(`UPDATE "_blob_uploads" u SET state = 'canceled', expires_at = now(),
+                   claim = NULL, claimed_at = NULL
+                 WHERE u.id = $1::uuid AND u.principal_id = $2::uuid AND u.action = $3
+                   AND u.state = 'ready'
+                   AND NOT EXISTS (SELECT 1 FROM "${ATTACHMENTS_TABLE}" a WHERE a.blob_id = u.blob_id)`, [uploadId, request.principal.id, qualified]);
+                    }
+                    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 transactionBody = Effect.gen(function* () {
+                // Server deadlines also protect the reserved connection if client cancellation cannot arrive.
+                yield* sql.unsafe(`SELECT set_config('statement_timeout', $1, true), set_config('lock_timeout', $2, true)`, [`${limits.statementTimeoutMs}ms`, `${limits.lockTimeoutMs}ms`]);
+                yield* beginReplicationWrite(sql);
+                return yield* transactionalHandler;
+            });
+            return transactionBody.pipe(Effect.map((result) => ({ result, edits, starts, signInEmails, replay })));
+        }, {
+            qualified,
+            actionId,
+            requestId,
+            retryOnDeadlock: action.retryOnDeadlock === true,
+            // A resent request runs prepare again; only without connections does that repeat nothing.
+            conflictRetryable: action.connections.length === 0,
+            handlerTimeoutMs: limits.handlerTimeoutMs,
+        });
+        const settled = (admission ? admission.admit(transaction) : transaction).pipe(Effect.annotateLogs({ action: qualified, actionId, requestId }), sqlFailuresAsDefects);
+        if (validateOnly) {
+            return yield* settled.pipe(Effect.as(VALID), Effect.catchTag("ValidationRollback", () => Effect.succeed(VALID)), Effect.catchTag(["NotFound", "ScopeViolated"], (error) => Effect.succeed({ ok: false, issues: [writeIssue(request.input, error)] })), Effect.map((validation) => ({ result: null, validation, edits: [] })));
+        }
+        const { result, edits, starts, signInEmails, replay } = yield* settled.pipe(Effect.catchTag("ValidationRollback", (rollback) => Effect.die(rollback)));
+        if (replay) {
+            return replay;
+        }
+        // The decided runs start before the after-commit effects; a failure leaves them pending for the
+        // recovery run armed above.
+        yield* startCommitted(sql, starter, starts, requestId);
+        yield* sendQueuedSignInEmails(sql, Option.getOrUndefined(yield* Effect.serviceOption(SignInLinks)), signInEmails, requestId);
+        const committed = {
+            entity: request.entity,
+            action: request.action,
+            actionId,
+            principal: request.principal,
+            input: decoded.value,
+            result,
+            edits,
+        };
+        for (const afterCommit of request.afterCommit ?? []) {
+            yield* Effect.suspend(() => afterCommit(committed)).pipe(Effect.catchCause((cause) => Effect.logWarning("An after-commit effect failed; the action had committed.", Cause.pretty(cause)).pipe(Effect.annotateLogs({
+                operation: "ontology.after_commit",
+                action: qualified,
+                actionId,
+            }))));
+        }
+        return { result: result ?? null, validation: VALID, edits };
+    });
+}
+/**
+ * Runs an action's `confirm` outside any transaction, with reads only, and checks what it describes.
+ * A confirmation the schema refuses is the action's defect, as a handler's would be.
+ */
+function confirmation(ontology, sql, action, qualified, context) {
+    const runtime = makeOntologyRuntime(ontology, sql);
+    const reads = {
+        get: ({ entity, id }) => runtime.get({ entity, id }),
+        find: ({ entity, options }) => runtime.find({ entity, options: { ...options, forUpdate: false } }),
+        queryMetrics: (input) => runtime.queryMetrics(input),
+    };
+    return Effect.suspend(() => action.confirm(context)).pipe(Effect.provideService(OntologyReads, reads), Effect.timeoutOrElse({
+        duration: CONFIRM_TIMEOUT,
+        orElse: () => Effect.die(new Error(`${qualified} confirm exceeded its ${Duration.format(CONFIRM_TIMEOUT)} deadline.`)),
+    }), Effect.flatMap((described) => Schema.decodeUnknownEffect(ActionConfirmation)(described, {
+        onExcessProperty: "error",
+    }).pipe(Effect.mapError((issue) => new Error(`${qualified} confirm described an invalid confirmation: ${issue}`)), Effect.orDie)), sqlFailuresAsDefects);
+}
+/**
+ * Runs `prepare` outside any transaction, with reads, declared connections and file access.
+ * Reads take no locks here: `forUpdate` is dropped, since a lock
+ * outside a transaction would be released at once.
+ */
+function prepare(ontology, sql, action, context, connections, qualified, fileInvocation) {
+    return Effect.gen(function* () {
+        const transport = connections ?? Option.getOrUndefined(yield* Effect.serviceOption(ConnectionTransport));
+        const fileAccess = Option.getOrUndefined(yield* Effect.serviceOption(FileAccess));
+        const files = fileAccess?.forInvocation(fileInvocation) ?? unavailableFiles;
+        const runtime = makeOntologyRuntime(ontology, sql);
+        const reads = {
+            get: ({ entity, id }) => runtime.get({ entity, id }),
+            find: ({ entity, options }) => runtime.find({ entity, options: { ...options, forUpdate: false } }),
+            queryMetrics: (input) => runtime.queryMetrics(input),
+        };
+        const run = Effect.suspend(() => action.prepare(context));
+        return yield* run.pipe(Effect.provideService(OntologyReads, reads), Effect.provideService(Files, action.hints?.readOnly === true
+            ? {
+                ...files,
+                stage: () => Effect.fail(new Conflict({ entity: "upload", message: "file_write_not_permitted" })),
+            }
+            : files), Effect.provideService(AgentFileRecords, {
+            resolve: (reference, principal) => resolveFileRecord({ manifest: ontology.manifest, reads, reference, principal }),
+        }), Effect.provideContext(connectionContext(action.connections, transport ?? NO_CONNECTIONS, {
+            readOnly: action.hints?.readOnly === true || action.hints?.connectionsReadOnly === true,
+        })), Effect.timeoutOrElse({
+            duration: PREPARE_TIMEOUT,
+            orElse: () => Effect.fail(new ConnectionError({
+                connection: action.connections.map((handle) => handle.key).join(","),
+                reason: "timeout",
+                message: `${qualified} prepare exceeded its ${Duration.format(PREPARE_TIMEOUT)} deadline.`,
+                retryable: true,
+            })),
+        }), sqlFailuresAsDefects);
+    });
+}

package/dist/runtime/postgres-tls.d.ts

@@ -0,0 +1,10 @@
+import { Redacted } from "effect";
+/**
+ * The TLS options for a connection string. A Neon endpoint routes by TLS server name and the
+ * pinned driver does not send one on its own, so the service and the migrate command would fail
+ * to connect without it. Other hosts keep the driver's defaults.
+ */
+export declare function postgresTls(connection: Redacted.Redacted<string>): {
+    readonly servername: string;
+    readonly rejectUnauthorized: true;
+} | undefined;

package/dist/runtime/postgres-tls.js

@@ -0,0 +1,14 @@
+import { Redacted } from "effect";
+/**
+ * The TLS options for a connection string. A Neon endpoint routes by TLS server name and the
+ * pinned driver does not send one on its own, so the service and the migrate command would fail
+ * to connect without it. Other hosts keep the driver's defaults.
+ */
+export function postgresTls(connection) {
+    const value = Redacted.value(connection);
+    const hostname = URL.canParse(value) ? new URL(value).hostname : "";
+    if (!hostname.endsWith(".neon.tech")) {
+        return undefined;
+    }
+    return { servername: hostname, rejectUnauthorized: true };
+}