@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/runtime/sign-in-links.js

@@ -0,0 +1,147 @@
+import { Context, Effect } from "effect";
+import { SIGN_IN_EMAIL_PARAMETER } from "../emails.js";
+import { SIGN_IN_EMAILS_TABLE } from "../storage/tables.js";
+/** How long Neon Auth may take to issue a link, which includes the platform's webhook sending it. */
+const REQUEST_TIMEOUT_MS = 20_000;
+/** How many links are requested at once after one action's commit. */
+const REQUEST_CONCURRENCY = 5;
+/** How long sign-in email rows are kept, for an operator, before a later send deletes them. */
+export const SIGN_IN_EMAIL_RETENTION_DAYS = 30;
+/**
+ * Asks the app's Neon Auth for a sign-in link to `returnTo` for a queued email. Neon Auth posts the
+ * link to the platform's email webhook, which sends the email, before it answers. The ontology
+ * service provides it in production; a runtime without one marks its rows `failed`.
+ */
+export class SignInLinks extends Context.Service()("@segmentstream/ontology/SignInLinks") {
+}
+/**
+ * The callback a queued email's link is requested with: the path on the app's origin, with
+ * {@link SIGN_IN_EMAIL_PARAMETER} naming the row, which the platform's webhook reads and removes.
+ */
+export function signInEmailCallback(origin, email) {
+    const url = new URL(email.returnTo, origin);
+    url.searchParams.set(SIGN_IN_EMAIL_PARAMETER, email.id);
+    return url.href;
+}
+/**
+ * {@link SignInLinks} through Better Auth's `POST /sign-in/magic-link` on the app's Neon Auth, with
+ * the app's production origin, which Neon Auth trusts for callbacks. A 404 means the workspace has
+ * no magic links yet; it is reconciled for them.
+ */
+export function neonSignInLinks(config) {
+    const fetcher = config.fetch ?? fetch;
+    const endpoint = `${config.baseUrl.replace(/\/+$/, "")}/sign-in/magic-link`;
+    return {
+        request: (email) => Effect.promise(async () => {
+            let response;
+            try {
+                response = await fetcher(endpoint, {
+                    method: "POST",
+                    redirect: "error",
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                    headers: { "content-type": "application/json", origin: config.origin },
+                    body: JSON.stringify({
+                        email: email.email,
+                        callbackURL: signInEmailCallback(config.origin, email),
+                    }),
+                });
+            }
+            catch {
+                return "unreachable";
+            }
+            void response.body?.cancel().catch(() => undefined);
+            if (response.ok) {
+                return undefined;
+            }
+            return response.status === 404 ? "disabled" : "refused";
+        }),
+    };
+}
+/**
+ * Requests the links of the emails an action queued, after its commit, in the same request, and
+ * records each outcome on its row; rows older than {@link SIGN_IN_EMAIL_RETENTION_DAYS} days go.
+ * Without {@link SignInLinks}, as in a preview, the rows are `failed` with `unavailable`. Nothing
+ * here fails the action, and logs never carry an address or a link.
+ */
+export function sendQueuedSignInEmails(sql, links, emails, requestId) {
+    if (emails.length === 0) {
+        return Effect.void;
+    }
+    return Effect.forEach(emails, (email) => (links === undefined
+        ? Effect.succeed("unavailable")
+        : links.request(email)).pipe(Effect.flatMap((failure) => sql
+        .unsafe(failure === undefined
+        ? `UPDATE "${SIGN_IN_EMAILS_TABLE}" SET "status" = 'requested',
+                     "requested_at" = now() WHERE "id" = $1::uuid`
+        : `UPDATE "${SIGN_IN_EMAILS_TABLE}" SET "status" = 'failed', "failure" = $2
+                     WHERE "id" = $1::uuid`, failure === undefined ? [email.id] : [email.id, failure])
+        .pipe(Effect.andThen(failure === undefined
+        ? Effect.logInfo("ontology.sign_in_email.requested")
+        : Effect.logWarning("ontology.sign_in_email.failed")), Effect.annotateLogs({
+        requestId,
+        signInEmail: email.id,
+        ...(failure === undefined ? {} : { failure }),
+    })))), { concurrency: REQUEST_CONCURRENCY, discard: true }).pipe(Effect.andThen(sql.unsafe(`DELETE FROM "${SIGN_IN_EMAILS_TABLE}"
+         WHERE "created_at" < now() - make_interval(days => $1)`, [SIGN_IN_EMAIL_RETENTION_DAYS])), Effect.asVoid, Effect.catchCause((cause) => Effect.logError("ontology.sign_in_email.record_failed", cause).pipe(Effect.annotateLogs({ requestId, queued: emails.length }))));
+}
+/** How long after it was queued an email's link may still arrive from Neon Auth. */
+const DELIVERY_WINDOW_HOURS = 24;
+/**
+ * The queued email with this id, while its link may still arrive; undefined for an unknown or
+ * older one, and in a database migrated before the table existed.
+ */
+export function findSignInEmail(sql, id) {
+    return Effect.gen(function* () {
+        const [table] = yield* sql.unsafe(`SELECT to_regclass($1) IS NOT NULL AS "present"`, [SIGN_IN_EMAILS_TABLE]);
+        if (!table?.present) {
+            return undefined;
+        }
+        const [row] = yield* sql.unsafe(`SELECT e."id", e."email", e."template", e."values", e."return_to",
+              u."name" AS "member_name", s."email" AS "sender_email"
+       FROM "${SIGN_IN_EMAILS_TABLE}" e
+       JOIN "user" u ON u."id" = e."user_id"
+       LEFT JOIN "user" s ON s."id" = e."sender_id" AND s."kind" = 'member'
+       WHERE e."id" = $1::uuid
+         AND e."created_at" > now() - make_interval(hours => $2)`, [id, DELIVERY_WINDOW_HOURS]);
+        return row === undefined
+            ? undefined
+            : {
+                id: row.id,
+                email: row.email,
+                template: row.template,
+                values: row.values,
+                returnTo: row.return_to,
+                memberName: row.member_name ?? row.email,
+                senderEmail: row.sender_email ?? undefined,
+            };
+    });
+}
+/** Sends committed queued context through the platform's deployment-authenticated mail boundary. */
+export function segmentstreamSignInLinks(config) {
+    return {
+        request: (email) => Effect.promise(async () => {
+            const token = config.identityToken();
+            if (!token) {
+                return "disabled";
+            }
+            try {
+                const response = await (config.fetch ?? fetch)(new URL("/api/internal/v1/app-auth/sign-in-email", config.segmentstreamUrl), {
+                    method: "POST",
+                    redirect: "error",
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                    body: JSON.stringify({
+                        id: email.id,
+                        workspace_id: config.workspaceId,
+                        organization_id: config.organizationId,
+                    }),
+                });
+                void response.body?.cancel().catch(() => undefined);
+                return response.ok ? undefined : "refused";
+            }
+            catch {
+                return "unreachable";
+            }
+        }),
+    };
+}

package/dist/runtime/sql-runtime.d.ts

@@ -0,0 +1,131 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import { Conflict, type NotFound } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import type { Query, QueryResult } from "../query.js";
+import type { OntologyRuntimeService, StoredRecord, StoredValues } from "../runtime.js";
+import { type BatchOperation } from "./batch.js";
+import { InvalidQuery, UnknownRole } from "./errors.js";
+import type { Edit, HistoryEntry, HistoryScope } from "./history.js";
+import { type QueuedSignInEmail } from "./member-writes.js";
+import { type EntityModel } from "./model.js";
+import { type RecordSnapshot, type WriteGuard } from "./writes.js";
+import { type ScopeReader } from "./where.js";
+/**
+ * The action a runtime writes for. Every write records history rows naming it, and sets
+ * `created_by`/`updated_by` to its principal.
+ */
+export interface WriteScope extends HistoryScope {
+    /** Set only when the enclosing action initialized replication in its outer transaction. */
+    readonly replicationInitialized?: boolean;
+    /** Channel onboarding cannot mutate platform principals through entity handles. */
+    readonly protectPrincipals?: true;
+    /** Receives the edits of each write that succeeded, in order. */
+    readonly onEdit?: (edit: Edit) => void;
+    /**
+     * Receives the stored record before and after each create, update and delete that succeeded, in
+     * order. Unset, the writes collect none.
+     */
+    readonly onSnapshot?: (snapshot: RecordSnapshot) => void;
+    /**
+     * The scopes the acting principal's grants put on the action's writes of its own entity, checked
+     * before and after each write. Absent when it holds the action's permissions unscoped.
+     */
+    readonly guard?: WriteGuard;
+    /** Receives each sign-in email the action queued, which is sent after its commit. */
+    readonly onSignInEmail?: (email: QueuedSignInEmail) => void;
+    /**
+     * The entities the action declares it writes, by name, as `action({ writes })` lists them. A write
+     * of any other entity is a defect. Absent when the action declares none.
+     */
+    readonly declaredWrites?: ReadonlySet<string>;
+}
+/**
+ * The SQL runtime: the {@link OntologyRuntime} contract for action handlers, plus the paged reads
+ * the HTTP API serves.
+ */
+export interface SqlOntologyRuntime extends OntologyRuntimeService {
+    /** A page of records matching a query. Fails with InvalidQuery when it does not fit the entity. */
+    readonly query: (input: {
+        readonly entity: string;
+        readonly query: Query;
+        /** The caller, whose read scopes leave out the rows outside them. */
+        readonly reader?: ScopeReader;
+    }) => Effect.Effect<QueryResult<StoredRecord>, InvalidQuery>;
+    /** One record; outside the `reader`'s read scope it is not found. */
+    readonly get: (input: {
+        readonly entity: string;
+        readonly id: string;
+        readonly forUpdate?: boolean;
+        readonly reader?: ScopeReader;
+    }) => Effect.Effect<StoredRecord, NotFound>;
+    /** A page of the records related to one record, as `GET /lead/{id}/notes` serves it. */
+    readonly related: (input: {
+        readonly entity: string;
+        readonly id: string;
+        readonly relationship: string;
+        readonly query?: Query;
+        readonly reader?: ScopeReader;
+    }) => Effect.Effect<QueryResult<StoredRecord>, InvalidQuery | NotFound>;
+    /**
+     * A page of one record's history, newest first. A `reader` with a read scope of the entity reads
+     * the history of a record inside it now, and finds no other.
+     */
+    readonly history: (input: {
+        readonly entity: string;
+        readonly id: string;
+        readonly after?: string;
+        readonly limit?: number;
+        readonly reader?: ScopeReader;
+    }) => Effect.Effect<QueryResult<HistoryEntry>, InvalidQuery | NotFound>;
+    /**
+     * The member writes behind `grantUserRoles`, `revokeUserRoles`, `inviteUser` and `setUserActive`,
+     * failing with UnknownRole where those reject a role, for the console's and the CLI's principal
+     * functions. Each writes history under the scope's action when it changes something.
+     */
+    readonly members: {
+        readonly grantRoles: (input: {
+            readonly id: string;
+            readonly roles: ReadonlyArray<string>;
+        }) => Effect.Effect<StoredRecord, UnknownRole | NotFound>;
+        readonly revokeRoles: (input: {
+            readonly id: string;
+            readonly roles: ReadonlyArray<string> | "all";
+        }) => Effect.Effect<StoredRecord, UnknownRole | NotFound>;
+        readonly invite: (input: {
+            readonly email: string;
+            readonly name?: string | undefined;
+            readonly roles?: ReadonlyArray<string> | undefined;
+        }) => Effect.Effect<StoredRecord, UnknownRole | Conflict>;
+        readonly setActive: (input: {
+            readonly id: string;
+            readonly active: boolean;
+        }) => Effect.Effect<StoredRecord, NotFound>;
+    };
+}
+/** A unique violation becomes Conflict, naming the property when the index covers one column. */
+export declare function uniqueConflict(entity: EntityModel, error: SqlError, batch?: {
+    readonly operation: BatchOperation;
+    readonly scope: HistoryScope;
+}): Effect.Effect<never, Conflict>;
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export declare function makePrincipalUserWriter(ontology: Ontology, sql: SqlClient.SqlClient, scope: Pick<HistoryScope, "action" | "actionId">): {
+    recordsSignIn: boolean;
+    create: (values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+    update: (id: string, values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+};
+/**
+ * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
+ * client runs them on the transaction of the calling fiber, so a runtime made for an action shares
+ * the action's transaction.
+ *
+ * Reads work without a scope. Writes need one: each write runs in its own savepoint (or its own
+ * transaction outside an action), so that the write and its history rows land together and a
+ * failed write, such as a Conflict a handler catches, leaves the action's transaction usable.
+ */
+export declare function makeOntologyRuntime(ontology: Ontology, sql: SqlClient.SqlClient, scope?: WriteScope): SqlOntologyRuntime;

package/dist/runtime/sql-runtime.js

@@ -0,0 +1,362 @@
+import { Effect, Exit, Option } from "effect";
+import { beginReplicationWrite } from "../replication/transaction.js";
+import { isSqlError } from "effect/unstable/sql/SqlError";
+import { ActionRejected, Conflict } from "../errors.js";
+import { toSnakeCase } from "../names.js";
+import { User } from "../user.js";
+import { UserIdentity } from "../user-identity.js";
+import { ACTION_MAX_BATCH_ROWS, BATCH_MAX_BYTES, BATCH_MAX_ROWS, batchInputBytes, executeBatch, planBatch, } from "./batch.js";
+import { logBatchConflict } from "./batch-diagnostics.js";
+import { runMetricQuery } from "./metric-query.js";
+import { InvalidQuery, UndeclaredWrite, UnknownRole, WriteOutsideAction } from "./errors.js";
+import { grantMemberRoles, inviteMember, queueSignInEmail, revokeMemberRoles, setMemberActive, } from "./member-writes.js";
+import { entityModel, ontologyModel } from "./model.js";
+import { loadRecord, notFound, readHistory, relatedCondition, runQuery, validateQuery, } from "./reads.js";
+import { createRecord, deleteRecord, linkRecords, unlinkRecords, updateRecord, upsertRecord, } from "./writes.js";
+import { readScopeOf } from "./where.js";
+/** A handler wrote an entity its action's `writes` does not list. */
+function undeclaredWrite(scope, entity) {
+    return new UndeclaredWrite({
+        entity,
+        action: scope.action,
+        message: `${scope.action} wrote ${entity}, which its writes do not list ` +
+            `(${[...(scope.declaredWrites ?? [])].join(", ") || "none"}). Add ${entity} to the ` +
+            "action's writes, or remove the write.",
+    });
+}
+/** A role a handler may not assign is the caller's to fix: its message is returned to them. */
+const rejectRole = (effect) => effect.pipe(Effect.mapError((error) => error instanceof UnknownRole ? new ActionRejected({ message: error.message }) : error));
+/** An unexpected database failure is a defect: callers see a sanitized server error. */
+const orDieOnSql = (effect) => effect.pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+/** Drops `undefined` object values, which handlers may pass and JSON cannot express. */
+function withoutUndefined(value) {
+    if (Array.isArray(value)) {
+        return value.map(withoutUndefined);
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .map(([key, entry]) => [key, withoutUndefined(entry)]));
+}
+/** A unique violation becomes Conflict, naming the property when the index covers one column. */
+export function uniqueConflict(entity, error, batch) {
+    const cause = (error.reason.cause ?? {});
+    const unique = error.reason._tag === "UniqueViolation" || cause.code === "23505";
+    if (!unique) {
+        return Effect.die(error);
+    }
+    const columns = typeof cause.detail === "string" ? /^Key \(([^)]*)\)=/.exec(cause.detail)?.[1] : undefined;
+    const field = entity.fields.find((candidate) => candidate.column === columns);
+    const fields = typeof columns === "string"
+        ? columns.split(", ").flatMap((column) => {
+            const candidate = entity.fields.find((entry) => entry.column === column);
+            return candidate === undefined ? [] : [candidate.relationship ?? candidate.name];
+        })
+        : [];
+    const details = batch ? { batch: { indices: [], ...(fields.length > 0 ? { fields } : {}) } } : {};
+    const label = entity.label.toLowerCase();
+    const conflict = field === undefined
+        ? new Conflict({
+            entity: entity.name,
+            message: `The ${label} conflicts with an existing one.`,
+            ...details,
+        })
+        : new Conflict({
+            entity: entity.name,
+            property: field.name,
+            message: `A ${label} with this ${field.name} already exists.`,
+            ...details,
+        });
+    // Keep the driver's cause for diagnostics and unique-violation retries, never on the wire.
+    Object.defineProperty(conflict, "cause", { value: error, enumerable: false });
+    if (batch) {
+        return logBatchConflict(entity, error, {
+            operation: batch.operation,
+            action: batch.scope.action,
+            actionId: batch.scope.actionId,
+        }).pipe(Effect.andThen(Effect.fail(conflict)));
+    }
+    return Effect.fail(conflict);
+}
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export function makePrincipalUserWriter(ontology, sql, scope) {
+    const model = ontologyModel(ontology);
+    const user = entityModel(model, User.name);
+    const allowed = new Set(Object.keys(User.definition.properties).map(toSnakeCase));
+    const client = sql.withoutTransforms();
+    const context = () => ({
+        model,
+        scope: { action: scope.action, actionId: scope.actionId, principalId: null },
+        edits: [],
+        run: (text, params) => client.unsafe(text, params.values),
+    });
+    const write = (values, operation) => Effect.suspend(() => {
+        if (!user.manifest.builtIn ||
+            Object.keys(values).some((name) => !allowed.has(name) || user.fieldsByName.get(name)?.source !== "property")) {
+            return Effect.die(new Error("Principal writes accept only built-in User properties."));
+        }
+        return sql
+            .withTransaction(operation())
+            .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(user, error)));
+    });
+    return {
+        recordsSignIn: user.fieldsByName.has("last_sign_in_at"),
+        // Unguarded writes: no scope applies, so ScopeViolated cannot occur.
+        create: (values) => write(values, () => createRecord(context(), user, values).pipe(Effect.catchTag("ScopeViolated", (error) => Effect.die(error)))),
+        update: (id, values) => write(values, () => updateRecord(context(), user, id, values).pipe(Effect.catchTag("ScopeViolated", (error) => Effect.die(error)))),
+    };
+}
+/**
+ * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
+ * client runs them on the transaction of the calling fiber, so a runtime made for an action shares
+ * the action's transaction.
+ *
+ * Reads work without a scope. Writes need one: each write runs in its own savepoint (or its own
+ * transaction outside an action), so that the write and its history rows land together and a
+ * failed write, such as a Conflict a handler catches, leaves the action's transaction usable.
+ */
+export function makeOntologyRuntime(ontology, sql, scope) {
+    const model = ontologyModel(ontology);
+    const client = sql.withoutTransforms();
+    const context = {
+        model,
+        run: (text, params) => client.unsafe(text, params.values),
+    };
+    const entityOf = (name) => Effect.sync(() => entityModel(model, name));
+    const reading = (reader) => reader === undefined ? context : { ...context, reader };
+    // The checks of the action's own entity; other entities are written with the action's authority.
+    const guardOf = (entity) => scope?.guard?.entity === entity.name ? scope.guard : undefined;
+    let attemptedBatchRows = 0;
+    let attributionInitialized = false;
+    const write = (entityName, operation) => Effect.gen(function* () {
+        const entity = yield* entityOf(entityName);
+        if (scope?.protectPrincipals && entity.name === User.name) {
+            return yield* Effect.die(new Error("onNewUser cannot change platform principals."));
+        }
+        // Sign-in identities authenticate members: only the platform's identity writer changes them.
+        if (entity.name === UserIdentity.name) {
+            return yield* Effect.die(new Error("Sign-in identities change only through the platform, never in an action."));
+        }
+        if (scope === undefined) {
+            return yield* Effect.die(new WriteOutsideAction({
+                entity: entityName,
+                message: `Writes to ${entityName} run inside an action, which history records.`,
+            }));
+        }
+        if (scope.declaredWrites !== undefined && !scope.declaredWrites.has(entity.name)) {
+            return yield* Effect.die(undeclaredWrite(scope, entity.name));
+        }
+        const edits = [];
+        const snapshots = scope.onSnapshot === undefined ? undefined : [];
+        const enclosingTransaction = yield* Effect.serviceOption(sql.transactionService);
+        const initialized = scope.replicationInitialized && Option.isSome(enclosingTransaction);
+        const result = yield* sql
+            .withTransaction((initialized ? Effect.void : beginReplicationWrite(sql)).pipe(Effect.andThen(operation({ ...context, scope, edits, ...(snapshots === undefined ? {} : { snapshots }) }, entity, guardOf(entity)))))
+            .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(entity, error)));
+        for (const edit of edits) {
+            scope.onEdit?.(edit);
+        }
+        for (const snapshot of snapshots ?? []) {
+            scope.onSnapshot?.(snapshot);
+        }
+        if (edits.length > 0 && scope.execution !== undefined) {
+            attributionInitialized = true;
+        }
+        return result;
+    });
+    const batch = (entityName, operation, input) => Effect.suspend(() => {
+        const startedAt = Date.now();
+        let statements = 0;
+        let distinctReferences = 0;
+        let counts = { created: 0, updated: 0, unchanged: 0 };
+        const run = Effect.gen(function* () {
+            if (scope === undefined) {
+                return yield* Effect.die(new WriteOutsideAction({
+                    entity: entityName,
+                    message: `Writes to ${entityName} run inside an action, which history records.`,
+                }));
+            }
+            if (scope.declaredWrites !== undefined && !scope.declaredWrites.has(entityName)) {
+                return yield* Effect.die(undeclaredWrite(scope, entityName));
+            }
+            const declared = ontology.entities.find((entity) => entity.name === entityName);
+            if (declared?.builtIn === true || declared?.entity.definition.source !== undefined) {
+                return yield* new ActionRejected({
+                    message: "Batch writes require an ordinary stored entity.",
+                    batch: { indices: [] },
+                });
+            }
+            const entity = yield* entityOf(entityName);
+            const length = input.records.length;
+            if (length > 0) {
+                attemptedBatchRows += length;
+            }
+            if (length > BATCH_MAX_ROWS || (length > 0 && attemptedBatchRows > ACTION_MAX_BATCH_ROWS)) {
+                return yield* new ActionRejected({
+                    message: length > BATCH_MAX_ROWS
+                        ? `A batch accepts at most ${BATCH_MAX_ROWS} records.`
+                        : `An action accepts at most ${ACTION_MAX_BATCH_ROWS} attempted batch records.`,
+                    batch: { indices: [] },
+                });
+            }
+            if (batchInputBytes(input) > BATCH_MAX_BYTES) {
+                return yield* new ActionRejected({
+                    message: `A batch accepts at most ${BATCH_MAX_BYTES} UTF-8 JSON bytes.`,
+                    batch: { indices: [] },
+                });
+            }
+            const plan = yield* planBatch(entity, operation, input);
+            distinctReferences = plan.distinctReferences;
+            if (length === 0) {
+                return plan.returning === "summary" ? counts : { ...counts, items: [] };
+            }
+            const enclosingTransaction = yield* Effect.serviceOption(sql.transactionService);
+            if (Option.isNone(enclosingTransaction)) {
+                return yield* Effect.die(new WriteOutsideAction({
+                    entity: entityName,
+                    message: "Batch writes require the enclosing action transaction.",
+                }));
+            }
+            const edits = [];
+            const snapshots = scope.onSnapshot === undefined ? undefined : [];
+            statements += 1; // The SQL client's nested transaction issues one savepoint.
+            const result = yield* sql
+                .withTransaction((scope.replicationInitialized ? Effect.void : beginReplicationWrite(sql)).pipe(Effect.andThen(executeBatch({
+                ...context,
+                scope,
+                edits,
+                ...(snapshots === undefined ? {} : { snapshots }),
+                attributionInitialized,
+                run: (text, params) => {
+                    statements += 1;
+                    return context.run(text, params);
+                },
+            }, entity, plan, guardOf(entity))), Effect.onExit((exit) => Effect.sync(() => {
+                if (Exit.isFailure(exit)) {
+                    statements += 1; // A failed nested transaction rolls back to its savepoint.
+                }
+            }))))
+                .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(entity, error, { operation, scope })));
+            counts = { created: result.created, updated: result.updated, unchanged: result.unchanged };
+            for (const edit of edits) {
+                scope.onEdit?.(edit);
+            }
+            for (const snapshot of snapshots ?? []) {
+                scope.onSnapshot?.(snapshot);
+            }
+            if (edits.length > 0 && scope.execution !== undefined) {
+                attributionInitialized = true;
+            }
+            return result;
+        });
+        return run.pipe(Effect.onExit((exit) => Effect.logDebug("ontology.action.batch_completed").pipe(Effect.annotateLogs({
+            operation,
+            entity: entityName,
+            action: scope?.action,
+            actionId: scope?.actionId,
+            inputCount: input.records.length,
+            distinctReferenceCount: distinctReferences,
+            changedCount: counts.created + counts.updated,
+            unchangedCount: counts.unchanged,
+            sqlStatements: statements,
+            batchMs: Date.now() - startedAt,
+            outcome: Exit.isSuccess(exit) ? "success" : "failure",
+        }))));
+    });
+    const declaredRoles = ontology.roles.map((candidate) => candidate.name);
+    const memberWrite = (operation) => write(User.name, (writeContext, entity) => operation({ ...writeContext, sql, roles: declaredRoles }, entity));
+    const members = {
+        grantRoles: (input) => memberWrite((context, entity) => grantMemberRoles(context, entity, input)).pipe(Effect.catchTag("Conflict", (error) => Effect.die(error))),
+        revokeRoles: (input) => memberWrite((context, entity) => revokeMemberRoles(context, entity, input)).pipe(Effect.catchTag("Conflict", (error) => Effect.die(error))),
+        invite: (input) => memberWrite((context, entity) => inviteMember(context, entity, input)),
+        setActive: (input) => memberWrite((context, entity) => setMemberActive(context, entity, input)).pipe(Effect.catchTag("Conflict", (error) => Effect.die(error))),
+    };
+    const query = (input) => Effect.gen(function* () {
+        const entity = yield* entityOf(input.entity);
+        const validated = yield* validateQuery(entity, input.query);
+        return yield* orDieOnSql(runQuery(reading(input.reader), entity, validated));
+    });
+    /** One record, or undefined when it does not exist or is outside the reader's read scope. */
+    const load = (entity, id, reader, forUpdate) => loadRecord(context, entity, id, forUpdate === true ? "update" : undefined, readScopeOf(reader, entity));
+    return {
+        createMany: ((input) => batch(input.entity, "create", input)),
+        updateMany: ((input) => batch(input.entity, "update", input)),
+        upsertMany: ((input) => batch(input.entity, "upsert", input)),
+        get: (input) => orDieOnSql(Effect.gen(function* () {
+            const entity = yield* entityOf(input.entity);
+            const record = yield* load(entity, input.id, input.reader, input.forUpdate);
+            return record ?? (yield* notFound(entity, input.id));
+        })),
+        find: (input) => Effect.gen(function* () {
+            const entity = yield* entityOf(input.entity);
+            const { forUpdate, ...options } = input.options;
+            if ("select" in options && options.select !== undefined) {
+                return yield* new InvalidQuery({
+                    entity: entity.name,
+                    message: "Action reads return complete records.",
+                    issues: [{ path: ["select"], message: "Unknown key" }],
+                });
+            }
+            // `{ where: { name: input.name } }` with an absent name means no condition on it.
+            const validated = yield* validateQuery(entity, withoutUndefined(options));
+            const page = yield* runQuery(context, entity, validated, { forUpdate: forUpdate === true });
+            return page.items;
+            // Handlers pass typed options, so a query that does not fit is a defect in the handler.
+        }).pipe(Effect.orDie),
+        queryMetrics: (input) => Effect.gen(function* () {
+            const entity = yield* entityOf(input.entity);
+            return yield* runMetricQuery(context, entity, withoutUndefined(input.options));
+            // As with find, options that do not fit the entity are a defect in the handler.
+        }).pipe(Effect.orDie),
+        create: (input) => write(input.entity, (writeContext, entity, guard) => createRecord(writeContext, entity, input.values, guard)),
+        update: (input) => write(input.entity, (writeContext, entity, guard) => updateRecord(writeContext, entity, input.id, input.values, guard?.change)),
+        upsertBy: (input) => write(input.entity, (writeContext, entity, guard) => upsertRecord(writeContext, entity, input.property, input.values, guard)),
+        delete: (input) => write(input.entity, (writeContext, entity, guard) => deleteRecord(writeContext, entity, input.id, new Set(), guard?.change)),
+        link: (input) => write(input.entity, (writeContext, entity, guard) => linkRecords(writeContext, entity, input, guard?.change)).pipe(Effect.catchTag("Conflict", (error) => Effect.die(error))),
+        unlink: (input) => write(input.entity, (writeContext, entity, guard) => unlinkRecords(writeContext, entity, input, guard?.change)).pipe(Effect.catchTag("Conflict", (error) => Effect.die(error))),
+        query,
+        related: (input) => Effect.gen(function* () {
+            const entity = yield* entityOf(input.entity);
+            const link = entity.links.get(input.relationship);
+            if (link === undefined) {
+                return yield* new InvalidQuery({
+                    entity: entity.name,
+                    message: `${input.relationship} is not a relationship of ${entity.name}.`,
+                    issues: [{ path: ["relationship"], message: "Expected a relationship of the entity" }],
+                });
+            }
+            const source = yield* orDieOnSql(load(entity, input.id, input.reader));
+            if (source === undefined) {
+                return yield* notFound(entity, input.id);
+            }
+            const target = entityModel(model, link.target);
+            const validated = yield* validateQuery(target, input.query ?? {});
+            const keyValue = link.via === "key" ? (source[`${link.name}_id`] ?? null) : null;
+            return yield* orDieOnSql(runQuery(reading(input.reader), target, validated, {
+                condition: relatedCondition(link, source.id, keyValue),
+            }));
+        }),
+        history: (input) => Effect.gen(function* () {
+            const entity = yield* entityOf(input.entity);
+            // A scoped reader reads the history of a record it can read now: the record must exist
+            // inside its read scope. Everyone else reads any record's history, a deleted one's too.
+            if (readScopeOf(input.reader, entity) !== undefined &&
+                (yield* orDieOnSql(load(entity, input.id, input.reader))) === undefined) {
+                return yield* notFound(entity, input.id);
+            }
+            return yield* orDieOnSql(readHistory(context, entity, input));
+        }),
+        grantUserRoles: (input) => rejectRole(members.grantRoles(input)),
+        revokeUserRoles: (input) => rejectRole(members.revokeRoles(input)),
+        inviteUser: (input) => rejectRole(members.invite(input)),
+        setUserActive: members.setActive,
+        sendUserSignInLink: (input) => memberWrite((context, entity) => queueSignInEmail(context, entity, ontology.manifest.emails ?? {}, input)).pipe(Effect.catchTag("Conflict", (error) => Effect.die(error)), Effect.flatMap((queued) => Effect.sync(() => scope?.onSignInEmail?.(queued)))),
+        members,
+    };
+}

package/dist/runtime/statement.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Collects the parameters of one statement. Values are always bound as parameters, cast to the
+ * column's type; only identifiers from the definition are written into the SQL text.
+ */
+export declare class Params {
+    readonly values: Array<unknown>;
+    /** Binds a value and returns its placeholder, cast when a type is given: `$3::bigint`. */
+    add(value: unknown, cast?: string): string;
+}
+/** `"t0"."owner_id"`. */
+export declare function columnOf(alias: string, column: string): string;
+/** Hands out table aliases, `t0`, `t1`, …, unique within one statement. */
+export declare class Aliases {
+    private next;
+    take(prefix?: string): string;
+}
+/** `%` and `_` match literally in LIKE patterns built from caller text; `\` is the escape. */
+export declare function escapeLike(text: string): string;