@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/asas/http/fetch.js

@@ -0,0 +1,178 @@
+import { AfterCommitError, AsasError, afterCommitHeader, codes, retryConflict } from '../runner/errors.js';
+// The walk enters objects, arrays and the wrappers `unwrap()` opens, and nothing else.
+const datesFromJson = (value, schema) => {
+    if (schema.type === 'date' && typeof value === 'string') {
+        // Date.parse normalizes February 30, which the declared z.date must refuse.
+        const day = value.slice(0, 10);
+        if (/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?(?:Z|[+-]\d\d:\d\d)$/.test(value)
+            && Number(value.slice(11, 13)) < 24) {
+            const parsed = new Date(value);
+            const midnight = new Date(`${day}T00:00:00Z`);
+            if (!Number.isNaN(parsed.getTime()) && !Number.isNaN(midnight.getTime()) && midnight.toISOString().slice(0, 10) === day)
+                return parsed;
+        }
+    }
+    if (['optional', 'nullable', 'default', 'prefault', 'nonoptional', 'readonly'].includes(schema.type ?? '')) {
+        return schema.unwrap ? datesFromJson(value, schema.unwrap()) : value;
+    }
+    if (schema.type === 'array' && Array.isArray(value) && schema.element) {
+        return value.map((one) => datesFromJson(one, schema.element));
+    }
+    if (schema.type === 'object' && value !== null && typeof value === 'object' && !Array.isArray(value) && schema.shape) {
+        const result = { ...value };
+        for (const [name, child] of Object.entries(schema.shape)) {
+            if (Object.hasOwn(result, name))
+                result[name] = datesFromJson(result[name], child);
+        }
+        return result;
+    }
+    return value;
+};
+/** The Zod input decides which JSON strings represent dates on either HTTP plug. */
+export const decodeJson = (value, schema) => schema['~standard'].vendor === 'zod' ? datesFromJson(value, schema) : value;
+// `?draft=true` saves or reads a draft, and `?autosave=true` beside it lets the
+// save overwrite an autosave. `?tenant=` is a read's reach, which the runner judges.
+export const draftOptions = (request) => {
+    const query = new URL(request.url).searchParams;
+    return {
+        ...(query.get('draft') === 'true' ? { draft: true } : {}),
+        ...(query.get('autosave') === 'true' ? { autosave: true } : {}),
+        ...(query.has('tenant') ? { tenant: query.get('tenant') } : {}),
+    };
+};
+/**
+ * The largest request body a plug reads, which a project names as `maxBodyBytes`: room for a
+ * json field's `defaultJsonMaxBytes` written in any script. A file never comes this way.
+ */
+export const defaultMaxBodyBytes = 4 * 1024 * 1024;
+/**
+ * The body, or the answer that refuses it: 413 once it passes `limit` bytes, and 499 to a client
+ * that went away mid-body, which is no fault of the server's. Counted as it arrives, since a
+ * `content-length` may be absent or wrong, and the rest is never read.
+ */
+export const boundedBody = async (request, limit) => {
+    const reader = request.body?.getReader();
+    const refused = () => {
+        // Not awaited: a clone's cancel settles only once its twin is cancelled too, which the
+        // caller does after this returns.
+        reader?.cancel().catch(() => { });
+        return tooLarge(limit);
+    };
+    if (Number(request.headers.get('content-length')) > limit)
+        return refused();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        let read;
+        try {
+            read = (await reader?.read()) ?? { done: true, value: undefined };
+        }
+        catch (thrown) {
+            if (request.signal.aborted)
+                return new Response(null, { status: 499 });
+            throw thrown;
+        }
+        if (read.done)
+            return new Blob(chunks);
+        size += read.value.byteLength;
+        if (size > limit)
+            return refused();
+        chunks.push(read.value);
+    }
+};
+/** Refused by name, since core holds no limit of its own. */
+export const assertMaxBodyBytes = (owner, value) => {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${owner} names no "maxBodyBytes", the largest request body in bytes it reads, as a whole number above 0. Name the project's own, such as defaultMaxBodyBytes from mithaq.`);
+    }
+};
+/** Refused by name, as `auth.onError` and `storage.onError` are: core reports no fault of its own. */
+export const assertOnError = (owner, value) => {
+    if (typeof value !== 'function') {
+        throw new Error(`${owner} names no "onError" function, which it hands every error that is no refusal before it answers 500. Name the project's own, such as console.error.`);
+    }
+};
+export const tooLarge = (limit) => Response.json({ code: codes[413], message: `The request body holds at most ${limit} bytes.` }, { status: 413 });
+/**
+ * The default HTTP plug: `POST /api/<kayan>/<operation>` with a JSON body, over
+ * `Request` and `Response` alone. The runner parses each operation's input.
+ */
+export const fetchHttp = (options) => {
+    // Read off `options?`, since a JavaScript caller may hand nothing, and is refused by name.
+    assertMaxBodyBytes('fetchHttp', options?.maxBodyBytes);
+    assertOnError('fetchHttp', options.onError);
+    const { context, onError, maxBodyBytes } = options;
+    return (operations) => {
+        const table = new Map(operations.map((one) => [`${one.kayan}/${one.name}`, one]));
+        return {
+            name: 'fetch',
+            // The operation table is the routes, already published as `asas.operations`.
+            router: undefined,
+            handle: async (request, actor) => {
+                if (request.method !== 'POST')
+                    return null;
+                // Two segments under `/api` and no more, so another plug's three-segment prefix
+                // falls through. `null`, not a 404, so a host keeps its own routes.
+                const [api, kayan, name, ...rest] = new URL(request.url).pathname.split('/').slice(1);
+                if (api !== 'api' || !kayan || !name || rest.length > 0)
+                    return null;
+                const operation = table.get(`${kayan}/${name}`);
+                if (!operation)
+                    return null;
+                const read = await boundedBody(request, maxBodyBytes);
+                if (read instanceof Response)
+                    return read;
+                const body = await read.text();
+                // Keyless: refused before any operation, and the key names an operation's refusal.
+                const undecodable = (message) => Response.json({ code: codes[400], message }, { status: 400 });
+                let input = {};
+                if (body) {
+                    try {
+                        input = JSON.parse(body);
+                    }
+                    catch {
+                        return undecodable('The request body is not JSON.');
+                    }
+                    // The runner reads fields off the input, so a body of `null` or `1` would be a
+                    // 500 a caller provoked; every caller-provoked refusal is a 4xx.
+                    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+                        return undecodable('The request body is not a JSON object.');
+                    }
+                }
+                try {
+                    // Resolved after the match, so a host's own routes cost no session lookup.
+                    const decoded = decodeJson(input, operation.input);
+                    const who = await actor();
+                    const result = await operation.call(decoded, { actor: who, context: await context?.(request, who), ...draftOptions(request) });
+                    // Only a write says so, because the browser clears its banner on this value alone.
+                    return Response.json(result, operation.effect === 'read' ? undefined : { headers: { [afterCommitHeader]: 'ok' } });
+                }
+                catch (thrown) {
+                    if (thrown instanceof AfterCommitError) {
+                        try {
+                            onError(thrown.cause);
+                        }
+                        catch {
+                            // Reporting cannot change a committed result.
+                        }
+                        return Response.json(thrown.result, { headers: { [afterCommitHeader]: 'failed' } });
+                    }
+                    thrown = retryConflict(thrown);
+                    if (thrown instanceof AsasError) {
+                        // The cause is never serialized: a conflict's driver error names the column and
+                        // value the refusal's message withholds.
+                        return Response.json({ code: codes[thrown.status], data: { key: thrown.key, params: thrown.params }, message: thrown.message }, { status: thrown.status });
+                    }
+                    try {
+                        onError(thrown);
+                    }
+                    catch {
+                        // Deliberately empty: reporting may not change what is reported.
+                    }
+                    // Not an `AsasError` is the project's own fault, so its message is replaced.
+                    return Response.json({ code: 'INTERNAL_SERVER_ERROR', message: 'Internal server error' }, { status: 500 });
+                }
+            },
+        };
+    };
+};

package/dist/asas/http/orpc.d.ts

@@ -0,0 +1,45 @@
+import type { Procedure, Schema } from '@orpc/server';
+import type { OperationTable } from '../build.ts';
+/** The context every procedure is handed, which defaults to the actor alone. */
+export type OrpcContext = {
+    actor: unknown;
+} & Record<string, unknown>;
+export type OrpcHttpOptions = {
+    /** Where the typed protocol answers. */
+    rpc?: `/${string}`;
+    /** Where plain HTTP answers, one route per operation. */
+    api?: `/${string}`;
+    /**
+     * Builds the context a procedure receives, once per request. The default is `{ actor }`;
+     * the `actor` it returns is the one the call runs as.
+     */
+    context?: (request: Request, actor: unknown) => Promise<OrpcContext> | OrpcContext;
+    /**
+     * Handed every error that is not an `AsasError`, before it is rethrown with its message replaced.
+     * A host's own deliberate `ORPCError` reaches it too, so a host logging only faults filters on the code. Required.
+     */
+    onError: (error: unknown) => void;
+    /** The largest body a call takes, answered 413 past it: `defaultMaxBodyBytes` or the project's own. Required. */
+    maxBodyBytes: number;
+};
+type OrpcProcedure<Method> = Method extends (...args: infer Args) => Promise<infer Answer> ? Procedure<OrpcContext, OrpcContext, Schema<Args[0], Args[0]>, Schema<Answer, Answer>, Record<never, never>, Record<never, never>> : never;
+/** The router, typed from the operation table: kayan, then operation. `RouterClient` over it needs no generated code. */
+export type OrpcRouter<View> = {
+    [Kayan in keyof View]: {
+        [Name in keyof View[Kayan]]: OrpcProcedure<View[Kayan][Name]>;
+    };
+};
+/**
+ * The oRPC plug: one procedure per operation, served over both the typed RPC protocol
+ * and plain HTTP. Needs `@orpc/server` and `@orpc/openapi`.
+ */
+export declare const orpcHttp: (options: OrpcHttpOptions) => <View>(operations: OperationTable<View>) => {
+    name: string;
+    router: OrpcRouter<View>;
+    /**
+     * `null` when neither prefix matched, so a host keeps its own routes. The path is matched
+     * before the actor thunk is called, so a host's own route runs no strategy.
+     */
+    handle: (request: Request, actor: () => Promise<unknown>) => Promise<Response | null>;
+};
+export {};

package/dist/asas/http/orpc.js

@@ -0,0 +1,153 @@
+// The only file that imports oRPC, so it is its own entry and oRPC stays an
+// optional peer a project that serves no HTTP never installs.
+import { OpenAPIHandler } from '@orpc/openapi/fetch';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ORPCError, ValidationError, os } from '@orpc/server';
+import { RPCHandler } from '@orpc/server/fetch';
+import { AfterCommitError, AsasError, afterCommitHeader, codes, retryConflict } from '../runner/errors.js';
+import { issueRefusal, withoutPrototype } from '../runner/steps.js';
+import { assertMaxBodyBytes, assertOnError, boundedBody, decodeJson, draftOptions } from './fetch.js';
+// Matched on the `ValidationError` cause, not the shape of `data`, so a host's own
+// `BAD_REQUEST` keeps its message and data.
+const boundaryRefusal = (thrown) => thrown instanceof ORPCError && thrown.code === 'BAD_REQUEST' && thrown.cause instanceof ValidationError
+    ? issueRefusal(thrown.cause.issues)
+    : undefined;
+/**
+ * The oRPC plug: one procedure per operation, served over both the typed RPC protocol
+ * and plain HTTP. Needs `@orpc/server` and `@orpc/openapi`.
+ */
+export const orpcHttp = (options) => {
+    // Read off `options?`, since a JavaScript caller may hand nothing, and is refused by name.
+    assertMaxBodyBytes('orpcHttp', options?.maxBodyBytes);
+    assertOnError('orpcHttp', options.onError);
+    const { rpc = '/api/rpc', api = '/api', context, onError, maxBodyBytes } = options;
+    return (operations) => {
+        // A reporter that throws must not replace the error the host has to see.
+        const report = (thrown) => {
+            try {
+                onError(thrown);
+            }
+            catch {
+                // Deliberately empty: reporting may not change what is reported.
+            }
+        };
+        // Per request, because a procedure's handler cannot read the request itself.
+        const warnings = new AsyncLocalStorage();
+        // The one place a refusal becomes a wire error, so both handlers share it.
+        const base = os.$context().use(async ({ next }) => {
+            try {
+                return await next();
+            }
+            catch (thrown) {
+                // oRPC validates the bound input inside this middleware, so its own refusal is
+                // re-emitted in the runner's shape: one shape answers every 400 a procedure raises.
+                thrown = retryConflict(thrown);
+                const held = thrown instanceof AsasError ? thrown : boundaryRefusal(thrown);
+                if (!held) {
+                    report(thrown);
+                    throw thrown;
+                }
+                throw new ORPCError(codes[held.status], {
+                    message: held.message,
+                    data: { key: held.key, params: held.params },
+                    // Never serialize the cause: a conflict's driver error names the column and value
+                    // on its `detail`. It stays in process only because oRPC's `toJSON` never emits `cause`.
+                    cause: held,
+                });
+            }
+        });
+        // No prototype, so a kayan or operation named `constructor` or `__proto__` is an own key.
+        const router = Object.create(null);
+        for (const operation of operations) {
+            const kayan = (router[operation.kayan] ??= Object.create(null));
+            const input = operation.input;
+            const zod = input['~standard'].vendor === 'zod';
+            // The published shape stays for the OpenAPI contract; only validation is skipped,
+            // because the runner parses every input before any store seal, and a draft against the draft shape.
+            const wireInput = Object.assign(Object.create(input), {
+                '~standard': {
+                    ...input['~standard'],
+                    validate: (value, options) => {
+                        const decoded = zod ? withoutPrototype(decodeJson(value, input)) : value;
+                        const object = decoded !== null && typeof decoded === 'object' && !Array.isArray(decoded);
+                        return warnings.getStore()?.options.draft && object ? { value: decoded } : input['~standard'].validate(decoded, options);
+                    },
+                },
+            });
+            kayan[operation.name] = base
+                .input(wireInput)
+                .handler(async ({ context: held, input }) => {
+                try {
+                    const { actor, ...rest } = held;
+                    const result = await operation.call(input, { actor, context: context ? rest : undefined, ...warnings.getStore()?.options });
+                    const warning = warnings.getStore();
+                    if (warning && operation.effect !== 'read')
+                        warning.said = 'ok';
+                    return result;
+                }
+                catch (thrown) {
+                    if (!(thrown instanceof AfterCommitError))
+                        throw thrown;
+                    report(thrown.cause);
+                    const warning = warnings.getStore();
+                    if (warning)
+                        warning.said = 'failed';
+                    return thrown.result;
+                }
+            });
+        }
+        const handlers = [
+            [rpc, new RPCHandler(router)],
+            [api, new OpenAPIHandler(router)],
+        ];
+        return {
+            name: 'orpc',
+            router: router,
+            /**
+             * `null` when neither prefix matched, so a host keeps its own routes. The path is matched
+             * before the actor thunk is called, so a host's own route runs no strategy.
+             */
+            handle: async (request, actor) => {
+                const { pathname } = new URL(request.url);
+                const under = (prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`);
+                if (!handlers.some(([prefix]) => under(prefix)))
+                    return null;
+                // Read here, so oRPC's own reader never holds a body past the limit. Off a clone, so a plug
+                // after this one reads the body of a route oRPC does not answer.
+                if (request.body) {
+                    const read = await boundedBody(request.clone(), maxBodyBytes);
+                    if (read instanceof Response) {
+                        // The clone's twin, so the source stream is cancelled rather than left to the server.
+                        request.body.cancel().catch(() => { });
+                        return read;
+                    }
+                    request = new Request(request.url, { method: request.method, headers: request.headers, body: read, signal: request.signal });
+                }
+                // Built before any procedure runs, so a throw here is outside the middleware;
+                // it still reaches `onError`.
+                let held;
+                try {
+                    const who = await actor();
+                    held = context ? await context(request, who) : { actor: who };
+                }
+                catch (thrown) {
+                    if (!(thrown instanceof AsasError))
+                        report(thrown);
+                    throw thrown;
+                }
+                for (const [prefix, handler] of handlers) {
+                    if (!under(prefix))
+                        continue;
+                    const warning = { options: draftOptions(request) };
+                    const answered = await warnings.run(warning, () => handler.handle(request, { context: held, prefix }));
+                    if (answered.matched) {
+                        if (warning.said)
+                            answered.response.headers.set(afterCommitHeader, warning.said);
+                        return answered.response;
+                    }
+                }
+                return null;
+            },
+        };
+    };
+};

package/dist/asas/runner/bulk.d.ts

@@ -0,0 +1,20 @@
+import { type ResolvedOperation, type RuntimeWriteTools as WriteTools } from './steps.ts';
+import { type Authorize, type ManagedAdmin, type Options } from './write.ts';
+import type { ResolvedKayan } from '../../mithaq/types.ts';
+import type { Store } from '../../mithaq/language.ts';
+export type SingleWrite<Actor> = (data: Record<string, unknown>, options?: Options<Actor>) => Promise<unknown>;
+export declare const bulk: <Actor = unknown>({ kayan, declaration, tools, store, single, cap, bulkLimit: ceiling, authorize, admin, tenantOf, }: {
+    kayan: ResolvedKayan;
+    declaration: ResolvedOperation;
+    tools: WriteTools<unknown, Actor>;
+    store: Store;
+    single: SingleWrite<Actor>;
+    cap: number;
+    /**
+     * The most rows one call may match, the service target's `bulkLimit`.
+     */
+    bulkLimit: number;
+    authorize: Authorize;
+    admin?: ManagedAdmin<Actor>;
+    tenantOf: (actor: unknown) => string | undefined;
+}) => (given: Record<string, unknown>, options?: Options<Actor>) => Promise<Record<string, unknown>>;

package/dist/asas/runner/bulk.js

@@ -0,0 +1,196 @@
+// One transaction for every row: a row that cannot be written rolls the whole call
+// back, because a bulk that half happened is a state no client can undo.
+import { stepTools } from './store.js';
+import { AfterCommitError, AsasError, invalid, retryConflict } from './errors.js';
+import { assertReadableWhere, checkedWhere } from './read.js';
+import { running } from './runtime.js';
+import { refuseTenantOption, writeTenant } from './tenant.js';
+import { atEffect, parse, validated } from './steps.js';
+import { aliveWhere, beginWrite, drain, ontoRow, projectReadableFields, publishedWhere, rowLock, runOutside } from './write.js';
+import { combineWhere } from '../../mithaq/where.js';
+// The bulk's own key is asked once, then each row goes through the single-row
+// write, which asks its own key and field access: no key grants more through a bulk.
+export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit: ceiling, authorize, admin, tenantOf, }) => async (given, options) => {
+    const list = atEffect(declaration.steps);
+    // Each row lands on the row as it is, so `{ draft: true }` is refused rather than published.
+    if (kayan.versions?.drafts && options?.draft) {
+        throw invalid({
+            message: `Kayan "${kayan.name}" operation "${tools.operation}" writes each row as it is, so it saves no draft. Call it without draft.`,
+            key: 'error.invalid.draft_operation',
+            params: { kayan: kayan.name, operation: tools.operation },
+        });
+    }
+    const { actor, context, entry, open } = beginWrite({ kayan, operation: tools.operation, store, cap, options });
+    refuseTenantOption({ kayan, operation: tools.operation, options });
+    const owner = writeTenant({ kayan, active: tenantOf(actor), effect: tools.effect, data: given?.data });
+    // Asked once, before `beforeTransaction`, so a refused actor runs no outside step.
+    const accessWhere = await authorize({
+        admin,
+        actor,
+        data: {},
+        effect: tools.effect,
+        kayan,
+        kind: tools.kind,
+        operation: tools.operation,
+    });
+    // Checked before the transaction opens, so a value a column refuses is a 400 no store was asked for.
+    if (given?.where !== undefined)
+        await checkedWhere(kayan, given.where);
+    let values = given;
+    if (declaration.beforeTransaction.length) {
+        const before = await runOutside({
+            kayan,
+            tools,
+            slot: 'beforeTransaction',
+            list: atEffect(declaration.beforeTransaction),
+            start: { kayan, data: { ...given }, actor, user: actor, tx: undefined, context, tenant: owner },
+            around: { context, user: actor },
+        });
+        values = before.data;
+    }
+    let committed;
+    const many = async (data, tx) => {
+        const callerWhere = await assertReadableWhere({ kayan, where: data.where, actor, authorize, admin });
+        // Required here: a bulk with no `where` would be every row the access admits.
+        if (!callerWhere) {
+            throw invalid({
+                message: `Kayan "${kayan.name}" operation "${tools.operation}" needs a "where", because a bulk write with none would change every row the access admits.`,
+                key: 'error.invalid.bulk_where',
+                params: { kayan: kayan.name, operation: tools.operation },
+            });
+        }
+        // An update naming no column would move each row's `updatedAt` and keep a version
+        // for no edit. Asked after the steps, since a step may fill `data`.
+        if (tools.kind === 'updateMany' && !Object.keys((data.data ?? {})).length) {
+            throw invalid({
+                message: `Kayan "${kayan.name}" operation "${tools.operation}" was handed no "data", so there is nothing to change.`,
+                key: 'error.invalid.empty_update',
+                params: { kayan: kayan.name, operation: tools.operation },
+            });
+        }
+        // The rows a plain read shows, so a bulk never reaches a draft that was never published.
+        const where = combineWhere(combineWhere(callerWhere, accessWhere), publishedWhere(kayan));
+        const values = (data.data ?? {});
+        // Holds every matched row until commit, as each row's own write then holds it; the limit is the
+        // ceiling, and `totalDocs` counts the whole matched set without reading it.
+        const found = await store.find({
+            kayan: kayan.name,
+            args: { limit: ceiling, page: 1, lock: rowLock({ kayan, kind: tools.kind, data: values }), sort: { field: 'id', direction: 'asc' }, where },
+            tx,
+        });
+        // Refused rather than written in part: a caller could not tell which rows a partial
+        // bulk wrote. The caller narrows its `where` instead.
+        if (found.totalDocs > ceiling) {
+            throw invalid({
+                message: `Kayan "${kayan.name}" operation "${tools.operation}" matched ${found.totalDocs} rows, and a bulk write holds at most ${ceiling} in one transaction. Narrow the "where" and run it again.`,
+                key: 'error.invalid.bulk_limit',
+                params: { kayan: kayan.name, operation: tools.operation, matched: found.totalDocs, ceiling },
+            });
+        }
+        const docs = [];
+        // In order, not in parallel: each write joins this transaction, which is one connection.
+        for (const row of found.docs) {
+            // Onto the row as it is, never its pending draft.
+            docs.push((await single({ ...values, id: row.id }, { actor: actor ?? undefined, [ontoRow]: true })));
+        }
+        // Unpublished rows the `where` names are left alone and reported under `errors`, so a
+        // person who ticked one is told; only to an actor who may read drafts, and only rows its answer admits.
+        const admits = kayan.versions?.drafts
+            ? await authorize({ admin, actor, data: {}, effect: 'read', kayan, operation: 'findVersions' }).then((where) => ({ where }), (thrown) => {
+                if (thrown instanceof AsasError && thrown.status === 403)
+                    return undefined;
+                throw thrown;
+            })
+            : undefined;
+        const unpublished = admits
+            ? (await store.find({
+                kayan: kayan.name,
+                args: { limit: ceiling, page: 1, sort: { field: 'id', direction: 'asc' }, where: combineWhere(combineWhere(callerWhere, accessWhere), combineWhere(aliveWhere(kayan), combineWhere({ _status: { not_equals: 'published' } }, admits.where))) },
+                tx,
+            })).docs
+            : [];
+        return {
+            docs,
+            errors: unpublished.map((row) => ({ id: row.id, message: `Kayan "${kayan.name}" row is not published, so operation "${tools.operation}" left it as it is. Publish it first.` })),
+        };
+    };
+    const run = (tx) => {
+        entry.tx = tx;
+        return running.run({ context, transactions: new Map(open).set(store, entry), user: actor }, async () => {
+            const runTools = Object.freeze({ ...tools, many: (data) => many(data, tx) });
+            const publicTools = stepTools(runTools);
+            let ctx = { kayan, data: { ...values }, actor, user: actor, tx, context, tenant: owner };
+            // No defaults here: each row's single-row write fills its own.
+            ctx = await parse({ schema: runTools.schema, ctx, tools: publicTools });
+            for (const step of atEffect([
+                ...declaration.beforeSteps,
+                ...list,
+                ...declaration.afterSteps,
+            ]))
+                ctx = { ...(await step(ctx, publicTools)), tenant: owner };
+            committed = ctx;
+            // Each document already passed its single-row output and read mask.
+            // The bulk contract validates the envelope after the steps have run.
+            if (!tools.publicOutput)
+                return ctx.data;
+            const parsed = await validated(tools.publicOutput, ctx.data);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error(`Kayan "${kayan.name}" custom bulk output must return an object.`);
+            }
+            const result = parsed;
+            if ('docs' in result) {
+                if (!Array.isArray(result.docs))
+                    throw new Error(`Kayan "${kayan.name}" custom bulk output must return docs as an array.`);
+                for (const doc of result.docs) {
+                    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+                        throw new Error(`Kayan "${kayan.name}" custom bulk output must return row objects.`);
+                    const visible = await projectReadableFields({ kayan, row: doc, actor });
+                    const protectedField = Object.keys(doc).find((key) => !(key in visible));
+                    if (protectedField)
+                        throw new Error(`Kayan "${kayan.name}" custom bulk output returned protected field "${protectedField}" after read projection.`);
+                }
+            }
+            return result;
+        });
+    };
+    const afterCommit = async () => {
+        if (!declaration.afterCommit.length || !committed)
+            return;
+        await runOutside({
+            kayan,
+            tools,
+            slot: 'afterCommit',
+            list: atEffect(declaration.afterCommit),
+            start: { ...committed, tx: undefined },
+            around: { context, user: actor },
+        });
+    };
+    const joined = open.get(store);
+    if (joined) {
+        const result = await run(joined.tx);
+        if (declaration.afterCommit.length)
+            joined.afterCommit = [...(joined.afterCommit ?? []), afterCommit];
+        return result;
+    }
+    let result;
+    try {
+        result = await store.transaction(run);
+    }
+    catch (thrown) {
+        throw retryConflict(thrown);
+    }
+    finally {
+        entry.settled = true;
+    }
+    try {
+        await drain([...(entry.afterCommit ?? []), afterCommit]);
+    }
+    catch (cause) {
+        // Only the outermost operation answers with what it committed; under an outer one
+        // the failure climbs as a plain `Error`.
+        if (running.getStore())
+            throw cause;
+        throw new AfterCommitError(result, cause);
+    }
+    return result;
+};

package/dist/asas/runner/errors.d.ts

@@ -0,0 +1,63 @@
+export declare const codes: {
+    readonly 400: 'BAD_REQUEST';
+    readonly 401: 'UNAUTHORIZED';
+    readonly 403: 'FORBIDDEN';
+    readonly 404: 'NOT_FOUND';
+    readonly 409: 'CONFLICT';
+    readonly 413: 'PAYLOAD_TOO_LARGE';
+    readonly 429: 'TOO_MANY_REQUESTS';
+    readonly 503: 'SERVICE_UNAVAILABLE';
+};
+/**
+ * A refusal the caller caused, with the HTTP status, a message `key` a client
+ * translates, and the `params` the message names. The English message is for logs.
+ */
+export declare class AsasError extends Error {
+    readonly status: 400 | 403 | 404 | 409;
+    readonly key: MessageKey;
+    readonly params: Readonly<Record<string, unknown>>;
+    constructor(message: string, status: 400 | 403 | 404 | 409, key: MessageKey, params?: Record<string, unknown>, cause?: unknown);
+}
+/** A write committed, but one or more callbacks that followed it failed. */
+export declare class AfterCommitError extends Error {
+    readonly committed = true;
+    readonly result: unknown;
+    constructor(result: unknown, cause: unknown);
+}
+/** Something a project is told that is expected rather than a failure, handed to the same `onError`. */
+export declare class Notice extends Error {
+    name: string;
+}
+/** A generic wire signal; callback details remain in the server reporter. */
+export declare const afterCommitHeader = "x-mithaq-after-commit";
+/** A refusal's key in the message namespace. */
+export type MessageKey = `error.${'conflict' | 'forbidden' | 'invalid' | 'not_found'}.${string}`;
+/** What every refusal takes: the English a log reads, the key a client translates, the values it names, and the cause. */
+export type Refusal = {
+    message: string;
+    key: MessageKey;
+    params?: Record<string, unknown>;
+    cause?: unknown;
+};
+/** The caller may not do this. */
+export declare const denied: ({ message, key, params, cause }: Refusal) => AsasError;
+/** The caller sent something the schema or the shape refuses. */
+export declare const invalid: ({ message, key, params, cause }: Refusal) => AsasError;
+/**
+ * The row the caller addressed is not there. An absent row and one access
+ * excludes answer alike, so a 404 never says which.
+ */
+export declare const missing: ({ message, key, params, cause }: Refusal) => AsasError;
+/**
+ * The write cannot complete, as a 409. Its key says whether trying again can help.
+ * It never says which column or whose row it hit.
+ */
+export declare const conflict: ({ message, key, params, cause }: Refusal) => AsasError;
+/** A transaction the database rolled back may be retried, without exposing its query or rows. */
+export declare const retryConflict: (thrown: unknown) => unknown;
+export declare const localizedQuery: ({ kayan, field, what, locales, }: {
+    kayan: string;
+    field: string;
+    what: 'filter' | 'sort';
+    locales?: readonly string[];
+}) => string;