@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/runtime/oauth.d.ts

@@ -0,0 +1,9 @@
+import { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import type { OAuthStore } from "../service/runtime-contract.js";
+/**
+ * The OAuth store on the runtime's OAuth tables, as `ontology_app`. Expiry is the database's
+ * wall clock; codes and refresh tokens are used with one `UPDATE … WHERE "used_at" IS NULL`, so two
+ * concurrent uses cannot both succeed.
+ */
+export declare function sqlOAuthStore(ontology: Ontology, sql: SqlClient.SqlClient): OAuthStore;

package/dist/runtime/oauth.js

@@ -0,0 +1,299 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { OAUTH_CLIENTS_TABLE, OAUTH_GRANTS_TABLE, OAUTH_REQUESTS_TABLE, OAUTH_TOKENS_TABLE, } from "../migrate/storage.js";
+import { lockSessionMember, resolveMemberById } from "./principals.js";
+import { CHANNEL_IDENTITIES_FROM, LIVE_CHANNEL_IDENTITY, USER_IDENTITY_TABLE, } from "./user-identity-sql.js";
+import { rejectedAccessToken, sameResource } from "../service/oauth/protocol.js";
+const CLIENTS = `"${OAUTH_CLIENTS_TABLE}"`;
+const REQUESTS = `"${OAUTH_REQUESTS_TABLE}"`;
+const GRANTS = `"${OAUTH_GRANTS_TABLE}"`;
+const TOKENS = `"${OAUTH_TOKENS_TABLE}"`;
+const CLIENT_COLUMNS = `"id", "name", "redirect_uris"::text AS "redirect_uris", "auth_method", "secret_hash", ` +
+    `"client_uri"`;
+/** A timestamp as epoch milliseconds, which every driver returns as a plain number. */
+function epochMs(column) {
+    return `(extract(epoch from ${column}) * 1000)::double precision`;
+}
+const REQUEST_COLUMNS = `"id", "client_id", "redirect_uri", "state", "code_challenge", "scope", "resource", ` +
+    `${epochMs(`"expires_at"`)} AS "expires_at"`;
+/** The grant's columns, read through the alias `g`. */
+const GRANT_COLUMNS = `"g"."id"::text AS "grant_id", "g"."client_id" AS "client_id", ` +
+    `"g"."user_id"::text AS "user_id", "g"."scope" AS "scope", "g"."resource" AS "resource"`;
+function text(value) {
+    return String(value);
+}
+function nullableText(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+function date(value) {
+    return new Date(Number(value));
+}
+function clientOf(row) {
+    return {
+        id: text(row.id),
+        name: text(row.name),
+        redirectUris: JSON.parse(text(row.redirect_uris)),
+        authMethod: text(row.auth_method),
+        secretHash: nullableText(row.secret_hash),
+        clientUri: nullableText(row.client_uri),
+    };
+}
+function requestOf(row) {
+    return {
+        id: text(row.id),
+        clientId: text(row.client_id),
+        redirectUri: text(row.redirect_uri),
+        state: nullableText(row.state),
+        codeChallenge: text(row.code_challenge),
+        scope: text(row.scope),
+        resource: text(row.resource),
+        expiresAt: date(row.expires_at),
+    };
+}
+function deviceOf(row) {
+    return {
+        hash: text(row.hash),
+        userCodeHash: text(row.user_code_hash),
+        clientId: text(row.client_id),
+        scope: text(row.scope),
+        resource: text(row.resource),
+        expiresAt: date(row.expires_at),
+        interval: Number(row.interval),
+        status: text(row.status),
+        userId: nullableText(row.user_id),
+    };
+}
+const DEVICE_COLUMNS = `*, ${epochMs('"expires_at"')} AS "expires_at"`;
+function grantOf(row) {
+    return {
+        id: text(row.grant_id),
+        clientId: text(row.client_id),
+        userId: text(row.user_id),
+        scope: text(row.scope),
+        resource: text(row.resource),
+    };
+}
+function tokenOf(row) {
+    return {
+        hash: text(row.hash),
+        grantId: text(row.grant_id),
+        kind: text(row.kind),
+        expiresAt: date(row.expires_at),
+        ...(row.redirect_uri === null ? {} : { redirectUri: text(row.redirect_uri) }),
+        ...(row.code_challenge === null ? {} : { codeChallenge: text(row.code_challenge) }),
+    };
+}
+const INSERT_TOKEN = `INSERT INTO ${TOKENS} ("hash", "grant_id", "kind", "redirect_uri", "code_challenge", ` +
+    `"expires_at") VALUES ($1, $2::uuid, $3, $4, $5, $6::timestamptz)`;
+function tokenValues(token) {
+    return [
+        token.hash,
+        token.grantId,
+        token.kind,
+        token.redirectUri ?? null,
+        token.codeChallenge ?? null,
+        token.expiresAt.toISOString(),
+    ];
+}
+/**
+ * The OAuth store on the runtime's OAuth tables, as `ontology_app`. Expiry is the database's
+ * wall clock; codes and refresh tokens are used with one `UPDATE … WHERE "used_at" IS NULL`, so two
+ * concurrent uses cannot both succeed.
+ */
+export function sqlOAuthStore(ontology, sql) {
+    const rows = (statement, values = []) => sql.unsafe(statement, values).pipe(Effect.orDie);
+    return {
+        withTokenLock: (hash, effect) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`SELECT "hash" FROM ${TOKENS} WHERE "hash" = $1 FOR UPDATE`, [hash]);
+            return yield* effect;
+        }))
+            .pipe(Effect.orDie),
+        refreshReplay: (hash, graceMs) => rows(`SELECT "t"."replay" FROM ${TOKENS} AS "t"
+       JOIN ${TOKENS} AS "s" ON "s"."hash" = "t"."successor_hash"
+       JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id"
+       WHERE "t"."hash" = $1 AND $2 > 0 AND "t"."used_at" IS NOT NULL
+       AND "t"."kind" = 'refresh' AND "t"."expires_at" > clock_timestamp()
+       AND "s"."kind" = 'refresh' AND "s"."grant_id" = "t"."grant_id"
+       AND "s"."used_at" IS NULL AND "s"."expires_at" > clock_timestamp()
+       AND "g"."revoked_at" IS NULL FOR UPDATE OF "s"`, [hash, graceMs]).pipe(Effect.map(([row]) => (row?.replay == null ? undefined : text(row.replay)))),
+        saveRefreshReplay: (hash, encrypted, successorHash) => rows(`UPDATE ${TOKENS} SET "replay" = $2, "successor_hash" = $3 WHERE "hash" = $1`, [
+            hash,
+            encrypted,
+            successorHash,
+        ]).pipe(Effect.asVoid),
+        saveDevice: (device) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM "_oauth_devices" WHERE "expires_at" < now() - interval '1 day'`);
+            const inserted = yield* rows(`INSERT INTO "_oauth_devices"
+         ("hash", "user_code_hash", "client_id", "scope", "resource", "expires_at", "interval")
+         VALUES ($1, $2, $3, $4, $5, $6::timestamptz, $7) ON CONFLICT DO NOTHING RETURNING "hash"`, [
+                device.hash,
+                device.userCodeHash,
+                device.clientId,
+                device.scope,
+                device.resource,
+                device.expiresAt.toISOString(),
+                device.interval,
+            ]);
+            return inserted.length === 1;
+        }))
+            .pipe(Effect.orDie),
+        findDevice: (hash) => rows(`SELECT ${DEVICE_COLUMNS} FROM "_oauth_devices" WHERE "user_code_hash" = $1`, [
+            hash,
+        ]).pipe(Effect.map(([row]) => (row === undefined ? undefined : deviceOf(row)))),
+        deviceAttempt: (memberId) => rows(`INSERT INTO "_oauth_device_attempts" ("member_id") VALUES ($1::uuid)
+       ON CONFLICT ("member_id") DO UPDATE SET
+       "attempts" = CASE WHEN "_oauth_device_attempts"."window_at" <= now() - interval '10 minutes'
+         THEN 1 ELSE "_oauth_device_attempts"."attempts" + 1 END,
+       "window_at" = CASE WHEN "_oauth_device_attempts"."window_at" <= now() - interval '10 minutes'
+         THEN now() ELSE "_oauth_device_attempts"."window_at" END RETURNING "attempts"`, [memberId]).pipe(Effect.map(([row]) => Number(row?.attempts) <= 10)),
+        decideDevice: (hash, userId, scope, decision) => rows(`UPDATE "_oauth_devices" SET "user_id" = $2::uuid, "status" = $3,
+       "scope" = CASE WHEN $4 = 'ontology:read' THEN $4 ELSE "scope" END
+       WHERE "user_code_hash" = $1 AND "status" = 'pending' AND "expires_at" > now()
+       RETURNING "hash"`, [hash, userId, decision === "approve" ? "approved" : "denied", scope ?? null]).pipe(Effect.map((updated) => updated.length === 1)),
+        pollDevice: (hash, clientId, resource) => sql
+            .withTransaction(Effect.gen(function* () {
+            const [row] = yield* rows(`SELECT ${DEVICE_COLUMNS}, "expires_at" <= now() AS "expired",
+         "next_poll_at" > clock_timestamp() AS "early"
+         FROM "_oauth_devices" WHERE "hash" = $1 AND "client_id" = $2 FOR UPDATE`, [hash, clientId]);
+            if (row === undefined ||
+                (resource !== undefined && !sameResource(resource, text(row.resource)))) {
+                return { status: "invalid_grant" };
+            }
+            if (row.expired === true) {
+                return { status: "expired_token" };
+            }
+            const device = deviceOf(row);
+            if (device.status === "consumed") {
+                return { status: "invalid_grant" };
+            }
+            if (row.early === true) {
+                yield* rows(`UPDATE "_oauth_devices" SET "interval" = "interval" + 5,
+          "next_poll_at" = clock_timestamp() + ("interval" + 5) * interval '1 second'
+          WHERE "hash" = $1`, [hash]);
+                return { status: "slow_down" };
+            }
+            yield* rows(`UPDATE "_oauth_devices" SET
+        "next_poll_at" = clock_timestamp() + "interval" * interval '1 second',
+        "status" = CASE WHEN "status" = 'approved' THEN 'consumed' ELSE "status" END
+        WHERE "hash" = $1`, [hash]);
+            if (device.status === "approved") {
+                return { status: "approved", device };
+            }
+            return {
+                status: device.status === "denied" ? "access_denied" : "authorization_pending",
+            };
+        }))
+            .pipe(Effect.orDie),
+        saveClient: (client) => rows(`INSERT INTO ${CLIENTS} ("id", "name", "redirect_uris", "auth_method", "secret_hash", ` +
+            `"client_uri") VALUES ($1, $2, $3::jsonb, $4, $5, $6)`, [
+            client.id,
+            client.name,
+            JSON.stringify(client.redirectUris),
+            client.authMethod,
+            client.secretHash,
+            client.clientUri,
+        ]).pipe(Effect.asVoid),
+        findClient: (id) => rows(`SELECT ${CLIENT_COLUMNS} FROM ${CLIENTS} WHERE "id" = $1`, [id]).pipe(Effect.map(([row]) => (row === undefined ? undefined : clientOf(row)))),
+        saveRequest: (request) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${REQUESTS} WHERE "expires_at" <= now()`);
+            yield* rows(`INSERT INTO ${REQUESTS} ("id", "client_id", "redirect_uri", "state", ` +
+                `"code_challenge", "scope", "resource", "expires_at") ` +
+                `VALUES ($1, $2, $3, $4, $5, $6, $7, $8::timestamptz)`, [
+                request.id,
+                request.clientId,
+                request.redirectUri,
+                request.state,
+                request.codeChallenge,
+                request.scope,
+                request.resource,
+                request.expiresAt.toISOString(),
+            ]);
+        }))
+            .pipe(Effect.orDie),
+        findRequest: (id) => rows(`SELECT ${REQUEST_COLUMNS} FROM ${REQUESTS} WHERE "id" = $1 AND "expires_at" > now()`, [
+            id,
+        ]).pipe(Effect.map(([row]) => (row === undefined ? undefined : requestOf(row)))),
+        takeRequest: (id) => rows(`DELETE FROM ${REQUESTS} WHERE "id" = $1 AND "expires_at" > now() ` +
+            `RETURNING ${REQUEST_COLUMNS}`, [id]).pipe(Effect.map(([row]) => (row === undefined ? undefined : requestOf(row)))),
+        saveGrant: (grant, code) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* lockSessionMember(sql, grant.userId);
+            yield* rows(`INSERT INTO ${GRANTS} ("id", "client_id", "user_id", "scope", "resource") ` +
+                `VALUES ($1::uuid, $2, $3::uuid, $4, $5)`, [grant.id, grant.clientId, grant.userId, grant.scope, grant.resource]);
+            if (code !== undefined) {
+                yield* rows(INSERT_TOKEN, tokenValues(code));
+            }
+        }))
+            .pipe(Effect.orDie),
+        useToken: (hash, kind) => Effect.gen(function* () {
+            const [used] = yield* rows(`UPDATE ${TOKENS} AS "t" SET "used_at" = clock_timestamp() FROM ${GRANTS} AS "g" ` +
+                `WHERE "t"."hash" = $1 AND "t"."kind" = $2 AND "t"."used_at" IS NULL ` +
+                `AND "t"."expires_at" > clock_timestamp() AND "g"."id" = "t"."grant_id" ` +
+                `AND "g"."revoked_at" IS NULL ` +
+                `RETURNING "t"."hash" AS "hash", "t"."kind" AS "kind", ` +
+                `"t"."redirect_uri" AS "redirect_uri", "t"."code_challenge" AS "code_challenge", ` +
+                `${epochMs(`"t"."expires_at"`)} AS "expires_at", ${GRANT_COLUMNS}`, [hash, kind]);
+            if (used !== undefined) {
+                return { status: "valid", token: tokenOf(used), grant: grantOf(used) };
+            }
+            const [reused] = yield* rows(`SELECT ${GRANT_COLUMNS}, "s"."used_at" IS NOT NULL AS "successor_used" FROM ${TOKENS} AS "t" ` +
+                `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" ` +
+                `LEFT JOIN ${TOKENS} AS "s" ON "s"."hash" = "t"."successor_hash" ` +
+                `AND "s"."grant_id" = "t"."grant_id" AND "s"."kind" = 'refresh' ` +
+                `WHERE "t"."hash" = $1 AND "t"."kind" = $2 AND "t"."used_at" IS NOT NULL ` +
+                `AND "t"."expires_at" > clock_timestamp() AND "g"."revoked_at" IS NULL`, [hash, kind]);
+            return reused === undefined
+                ? { status: "invalid" }
+                : {
+                    status: "reused",
+                    grant: grantOf(reused),
+                    ...(kind === "refresh" ? { successorUsed: reused.successor_used === true } : {}),
+                };
+        }),
+        saveTokens: (tokens) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${TOKENS} WHERE "expires_at" <= clock_timestamp()`);
+            for (const token of tokens) {
+                yield* rows(INSERT_TOKEN, tokenValues(token));
+            }
+        }))
+            .pipe(Effect.orDie),
+        findAccess: (hash) => rows(`SELECT ${GRANT_COLUMNS}, ${epochMs(`"t"."expires_at"`)} AS "access_expires_at", ` +
+            `"g"."identity_id" IS NOT NULL AS "channel", ` +
+            `(SELECT "i"."provider" FROM "${USER_IDENTITY_TABLE}" AS "i" ` +
+            `WHERE "i"."id" = "g"."identity_id") AS "identity_provider", ` +
+            `"t"."expires_at" <= clock_timestamp() AS "expired", ` +
+            `"g"."revoked_at" IS NOT NULL AS "revoked" FROM ${TOKENS} AS "t" ` +
+            `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" ` +
+            `WHERE "t"."hash" = $1 AND "t"."kind" = 'access' ` +
+            // A channel session lives while the member's channel account does.
+            `AND ("g"."identity_id" IS NULL OR EXISTS (` +
+            `SELECT 1 FROM ${CHANNEL_IDENTITIES_FROM} WHERE "i"."id" = "g"."identity_id" ` +
+            `AND "i"."user_id" = "g"."user_id" AND ${LIVE_CHANNEL_IDENTITY}))`, [hash]).pipe(Effect.flatMap(([row]) => {
+            if (row === undefined) {
+                return rejectedAccessToken("token_not_found");
+            }
+            const grant = grantOf(row);
+            if (row.revoked === true) {
+                return rejectedAccessToken("grant_revoked", grant.id);
+            }
+            if (row.expired === true) {
+                return rejectedAccessToken("token_expired", grant.id);
+            }
+            return Effect.succeed(row.channel === true
+                ? {
+                    ...grant,
+                    expiresAt: new Date(Number(row.access_expires_at)),
+                    identityProvider: String(row.identity_provider),
+                }
+                : grant);
+        })),
+        findGrantOfToken: (hash) => rows(`SELECT ${GRANT_COLUMNS} FROM ${TOKENS} AS "t" ` +
+            `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" WHERE "t"."hash" = $1`, [hash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : grantOf(row)))),
+        revokeGrant: (id) => rows(`UPDATE ${GRANTS} SET "revoked_at" = now() WHERE "id" = $1::uuid AND "revoked_at" IS NULL`, [id]).pipe(Effect.asVoid),
+        memberPrincipal: (userId) => resolveMemberById(ontology, userId).pipe(Effect.provideService(SqlClient.SqlClient, sql)),
+    };
+}

package/dist/runtime/pipeline.d.ts

@@ -0,0 +1,155 @@
+import type { ActionRuntime } from "../runtime-source.js";
+import { Duration, Effect, Schema } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { type AnyAction } from "../action.js";
+import { ConnectionError, ConnectionTransport } from "../connection.js";
+import { type ActionError } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import { type Principal } from "../runtime.js";
+import { TriggerInputInvalid, UnknownAction, WorkflowRecoveryUnavailable } from "./errors.js";
+import { Edit } from "./history.js";
+import type { WriteGuard } from "./writes.js";
+/** An action that committed, as after-commit effects receive it. */
+export interface CommittedAction {
+    readonly entity: string;
+    readonly action: string;
+    readonly actionId: string;
+    readonly principal: Principal;
+    /** The decoded input. */
+    readonly input: unknown;
+    readonly result: unknown;
+    readonly edits: ReadonlyArray<Edit>;
+}
+/**
+ * Runs after the transaction commits, never inside it: starting a workflow that notifies the team
+ * or calls a webhook. A failure is logged; the action has committed and still succeeds.
+ */
+export type AfterCommit<R = never> = (committed: CommittedAction) => Effect.Effect<void, unknown, R>;
+export interface ActionRequest<R = never> {
+    readonly runtime?: ActionRuntime;
+    readonly entity: string;
+    readonly action: string;
+    /** The input as the caller sent it; the action's input schema decodes it. */
+    readonly input: unknown;
+    readonly principal: Principal;
+    readonly options?: {
+        /**
+         * Decode the input and check the permission, without running `prepare` or the handler. A
+         * generated action of a principal whose permission is scoped also runs its write in a
+         * transaction that is always rolled back, so that the scope's checks answer as they would.
+         */
+        readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
+        /** Internal channel lifecycle execution; marker commits atomically with the handler. */
+        readonly newUserHook?: true;
+        /**
+         * Describe what a person confirms before the action runs, in the chat's language, with the
+         * action's `confirm`: decode the input, check the permission, and answer with the confirmation,
+         * or `null` for an action without one. Nothing is prepared or written.
+         */
+        readonly confirm?: {
+            readonly locale: 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;
+    /**
+     * Sends the calls of `prepare` to the declared connections, bound to this request. The
+     * {@link ConnectionTransport} in context, such as `Connections.test`, is used when it is not set.
+     */
+    readonly connections?: ConnectionTransport["Service"];
+}
+/** How long an action's `confirm` may take: a person waits for the card it describes. */
+export declare const CONFIRM_TIMEOUT: Duration.Duration;
+/** How long `prepare` may take, connection calls included; each call has its own 30 s deadline. */
+export declare const PREPARE_TIMEOUT: Duration.Duration;
+export declare const ActionValidation: Schema.Struct<{
+    readonly ok: Schema.Boolean;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+        readonly message: Schema.String;
+    }>>;
+}>;
+export type ActionValidation = typeof ActionValidation.Type;
+/** The response of an action: its result, the input's validation, and the records it changed. */
+export declare const ActionOutcome: Schema.Struct<{
+    readonly result: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly validation: Schema.Struct<{
+        readonly ok: Schema.Boolean;
+        readonly issues: Schema.$Array<Schema.Struct<{
+            readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+            readonly message: Schema.String;
+        }>>;
+    }>;
+    readonly edits: Schema.$Array<Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly kind: Schema.Literals<readonly ["create", "update", "delete", "link", "unlink"]>;
+        readonly changes: Schema.$Record<Schema.String, Schema.Struct<{
+            readonly before: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly after: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>>;
+    }>>;
+}>;
+export interface ActionOutcome<Result = unknown> {
+    /** `null` when the input was invalid, under `validateOnly`, and for actions without a result. */
+    readonly result: Result | null;
+    readonly validation: ActionValidation;
+    readonly edits: ReadonlyArray<Edit>;
+}
+/** An action and every permission a principal needs to run it. */
+export interface FoundAction {
+    readonly action: AnyAction;
+    readonly permissions: ReadonlyArray<string>;
+    /**
+     * A generated `create`, `update`, `delete`, `upsert_by_<property>`, `link`, `unlink` or member
+     * action, whose input and result are in wire names.
+     */
+    readonly generated: boolean;
+}
+/**
+ * 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 declare function resolveAction(ontology: Ontology, entityName: string, actionName: string): FoundAction | undefined;
+/**
+ * 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 declare function writeGuard(entity: string, found: FoundAction, principal: Principal): WriteGuard | undefined;
+/** The entity's authored action of that name, or else its generated one. */
+export declare function findAction(ontology: Ontology, entityName: string, actionName: string): AnyAction | undefined;
+/**
+ * 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 declare function runAction<R = never>(ontology: Ontology, request: ActionRequest<R>): Effect.Effect<ActionOutcome, ActionError | ConnectionError | UnknownAction | TriggerInputInvalid | WorkflowRecoveryUnavailable, SqlClient.SqlClient | R>;