@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/asas/runner/write.js

@@ -0,0 +1,791 @@
+// One list in one place, so drizzle's callback transaction is kept as it is.
+import { rowsOfField } from '../../mithaq/rows.js';
+import { heldPermissions } from '../../rbac/index.js';
+import { authActor } from '../actor.js';
+import { AfterCommitError, AsasError, denied, invalid, missing } from './errors.js';
+import { defaultKinds } from '../../base/kinds.js';
+import { providerOf } from '../../base/rules.js';
+import { atEffect, defaults, issueRefusal, parse, sealOf, storeSeals, validated, withoutPrototype } from './steps.js';
+import { firstRegisters, running, snapshot } from './runtime.js';
+import { changedColumns, latestVersion, restoreInput, revived, saveVersion } from '../../versions/versions.js';
+import { fileURLs } from '../../storage/storage.js';
+import { combineWhere, operatorList } from '../../mithaq/where.js';
+import { refuseTenantOption, writeTenant } from './tenant.js';
+/** The key of `Options` only the bulk runner sets. */
+export const ontoRow = Symbol('ontoRow');
+const isScalar = (value) => value === null ||
+    ['string', 'boolean'].includes(typeof value) ||
+    (typeof value === 'number' && Number.isFinite(value)) ||
+    (value instanceof Date && Number.isFinite(value.getTime()));
+const known = new Set(operatorList);
+/** A list of operators as a sentence says it: `"a", "b" and "c"`. */
+const and = new Intl.ListFormat('en-GB', { type: 'conjunction' });
+const checkOperatorValue = (said, field, operator, value) => {
+    if (operator === 'exists') {
+        if (typeof value !== 'boolean')
+            throw new Error(`${said} field "${field}" operator "exists" needs a boolean.`);
+        return;
+    }
+    if (operator === 'in' || operator === 'not_in') {
+        if (!Array.isArray(value) || !value.every(isScalar)) {
+            throw new Error(`${said} field "${field}" operator "${operator}" needs scalar array.`);
+        }
+        return;
+    }
+    if ((operator === 'contains' || operator === 'like') && typeof value !== 'string') {
+        throw new Error(`${said} field "${field}" operator "${operator}" needs a string.`);
+    }
+    if (['greater_than', 'greater_than_equal', 'less_than', 'less_than_equal'].includes(operator) && value === null) {
+        throw new Error(`${said} field "${field}" operator "${operator}" cannot compare null.`);
+    }
+    if (!isScalar(value)) {
+        throw new Error(`${said} field "${field}" operator "${operator}" needs a scalar.`);
+    }
+};
+// A second segment is a locale or a related field, never both: `resolve` refuses
+// `localized` beside `relationTo` on the field itself, whatever the kind is named.
+const queryField = ({ kayan, key, said }) => {
+    const parts = key.split('.');
+    const unsupported = `${said} path "${key}" is unsupported. A path is one field, and may then name one related field of what a relationship points at or one locale of a localized field, so it is never more than two segments.`;
+    if (parts.length > 2 || parts.some((part) => !part))
+        throw new Error(unsupported);
+    const field = parts[0];
+    const path = parts[1];
+    const resolved = kayan.fields[field];
+    if (!resolved)
+        throw new Error(`${said} names unknown field "${key}".`);
+    if (!path || resolved.locales?.includes(path))
+        return { field, key, kind: resolved.kind, operators: resolved.operators };
+    if (!resolved.target)
+        throw new Error(unsupported);
+    const target = resolved.target.fields[path];
+    if (!target)
+        throw new Error(`${said} path "${key}" names unknown related field.`);
+    return { field, key, kind: target.kind, operators: target.operators };
+};
+// An access constraint and a screen's `when` share this one grammar.
+export const assertFieldWhere = ({ said, key, kind, operators, value, valued = true }) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${said} field "${key}" must use operators.`);
+    }
+    const fieldWhere = Object.create(null);
+    for (const [operator, operand] of Object.entries(value)) {
+        if (!known.has(operator)) {
+            throw new Error(`${said} field "${key}" uses unsupported operator "${operator}".`);
+        }
+        // A kind that names its operators is held to them and nothing else
+        // as rich text is to the three that search the words of its text.
+        if (operators && !operators.includes(operator)) {
+            throw new Error(`${said} field "${key}" operator "${operator}" is not supported on a field of kind "${kind}"; only ${and.format(operators.map((one) => `"${one}"`))} ${operators.length === 1 ? 'is' : 'are'}.`);
+        }
+        // Every operator here compares one value, so none means anything against a list
+        // column; drizzle's array mapper would throw a 500 first. `exists` asks about the column.
+        if (kind === 'textArray' && operator !== 'exists') {
+            throw new Error(`${said} field "${key}" operator "${operator}" is not supported on a list field; only "exists" is.`);
+        }
+        if (!operators && (operator === 'contains' || operator === 'like') && !['email', 'text'].includes(kind)) {
+            throw new Error(`${said} field "${key}" operator "${operator}" only supports text-like fields.`);
+        }
+        if (!operators &&
+            ['greater_than', 'greater_than_equal', 'less_than', 'less_than_equal'].includes(operator) &&
+            !['date', 'datetime', 'number', 'integer', 'decimal'].includes(kind)) {
+            throw new Error(`${said} field "${key}" operator "${operator}" only supports numeric, date and datetime fields.`);
+        }
+        checkOperatorValue(said, key, operator, operand);
+        // A value an integer or decimal column cannot hold would reach Postgres as a 500.
+        // A caller's own query skips this: its row shape refuses values with a path each.
+        if (valued && (kind === 'integer' || kind === 'decimal') && operator !== 'exists') {
+            for (const one of Array.isArray(operand) ? operand : [operand]) {
+                const read = kind === 'integer' && typeof one === 'string' && /^[+-]?\d+$/.test(one) ? Number(one) : one;
+                if (read !== null && !defaultKinds[kind].accepts(read))
+                    throw new Error(`${said} field "${key}" operator "${operator}" needs a value of kind "${kind}".`);
+            }
+        }
+        fieldWhere[operator] = operand;
+    }
+    if (!Object.keys(fieldWhere).length)
+        throw new Error(`${said} field "${key}" has no operators.`);
+    return fieldWhere;
+};
+export const assertWhere = (kayan, where) => normalizedWhere({ kayan, where, valued: true, said: `Kayan "${kayan.name}" access constraint` });
+// Grammar alone: a caller's values are the row shape's to refuse.
+export const assertWhereGrammar = (kayan, where) => normalizedWhere({ kayan, where, valued: false, said: `Kayan "${kayan.name}" query` });
+const normalizedWhere = ({ kayan, where, valued, said }) => {
+    if (!where || typeof where !== 'object' || Array.isArray(where)) {
+        throw new Error(`${said} is not an object of fields.`);
+    }
+    const entries = Object.entries(where);
+    if (!entries.length)
+        throw new Error(`${said} is empty.`);
+    // No prototype, so `__proto__` is a key like any other.
+    const normalized = Object.create(null);
+    for (const [key, value] of entries) {
+        if (key === 'and' || key === 'or') {
+            if (!Array.isArray(value) || !value.length) {
+                throw new Error(`${said} "${key}" must be a non-empty array.`);
+            }
+            normalized[key] = value.map((one) => normalizedWhere({ kayan, where: one, valued, said }));
+            continue;
+        }
+        const queried = queryField({ kayan, key, said });
+        const fieldWhere = assertFieldWhere({ said, key, kind: queried.kind, operators: queried.operators, value, valued });
+        normalized[queried.key] = { ...normalized[queried.key], ...fieldWhere };
+    }
+    return normalized;
+};
+// `exists` rather than `equals: null`: it asks about the column, which every store
+// answers alike. The access target's reader never asks it, so `buildAsas` refuses the pair.
+export const aliveWhere = (kayan) => kayan.softDelete ? { [kayan.softDelete]: { exists: false } } : undefined;
+// A row made as a draft and never published is read by nothing but a draft read.
+export const publishedWhere = (kayan) => combineWhere(aliveWhere(kayan), kayan.versions?.drafts ? { _status: { equals: 'published' } } : undefined);
+const fieldAccess = async (operation, kayan, data, actor, id, named, doc, kept = []) => {
+    const next = { ...data };
+    const refused = [];
+    let table;
+    for (const field of Object.values(kayan.fields)) {
+        if (operation === 'update' && field.name === 'id')
+            continue;
+        if (!(field.name in next))
+            continue;
+        const access = field.access?.[operation];
+        if (!access)
+            continue;
+        // Asked again on every pass: a step may have changed the value the callback judges.
+        const allowed = !!(await access({ data, doc, id, siblingData: next, user: actor }));
+        if (allowed)
+            continue;
+        // A row-compiled denial is named, not silently dropped. A column carried from a draft
+        // is refused whatever denied it, or the stored value would publish unasked.
+        const source = rowsOfField(access);
+        if (!source && !kept.includes(field.name)) {
+            delete next[field.name];
+            continue;
+        }
+        table ??= source;
+        refused.push(field.name);
+    }
+    if (refused.length) {
+        // The roles go as a list, so a client resolves each against the catalog.
+        const roles = table?.roles(actor) ?? [];
+        throw denied({
+            message: `Forbidden: kayan "${kayan.name}" operation "${named}" for roles "${roles.join(', ')}" cannot write field${refused.length > 1 ? 's' : ''} "${refused.join('", "')}".`,
+            key: 'error.forbidden.field_write',
+            params: { kayan: kayan.name, operation: named, roles, fields: refused },
+        });
+    }
+    return next;
+};
+export const projectReadableFields = async ({ kayan, row, actor, }) => {
+    const next = { ...row };
+    for (const field of Object.values(kayan.fields)) {
+        const access = field.access?.read;
+        if (!access || !(field.name in next))
+            continue;
+        const allowed = await access({ data: row, doc: row, id: row.id, siblingData: row, user: actor });
+        if (!allowed)
+            delete next[field.name];
+    }
+    return next;
+};
+// A stored row the row shape refuses is the data's fault, so a plain `Error` (a masked
+// 500). The message names the fields and id, never a value: a message may quote it.
+const storedRow = async (kayan, schema, row) => {
+    const result = await schema['~standard'].validate(withoutPrototype(row));
+    if (!result.issues)
+        return result.value;
+    const fields = [...new Set(result.issues.map((issue) => {
+            const [first] = issue.path ?? [];
+            return String(typeof first === 'object' ? first.key : first ?? '');
+        }))];
+    const id = 'id' in row && !fields.includes('id') ? ` ${JSON.stringify(row.id)}` : '';
+    throw new Error(`Kayan "${kayan.name}" row${id} is stored with a value that is not of its kind in field${fields.length > 1 ? 's' : ''} "${fields.join('", "')}", so it cannot be read. Repair the stored row.`);
+};
+// Masking deletes from the value, so no schema is composed and any validator can be the schema target.
+export const publicResult = async ({ kayan, row, actor, internalOutput, publicOutput, }) => {
+    const internal = await storedRow(kayan, internalOutput, row);
+    // A custom output is handed the operation's own words beside the proved columns.
+    const value = publicOutput ? { ...row, ...internal } : internal;
+    const visible = await projectReadableFields({ kayan, row: value, actor });
+    // Computed on every read, never stored.
+    if (!publicOutput)
+        return fileURLs({ kayan, stored: internal, visible });
+    const parsed = await validated(publicOutput, visible);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Kayan "${kayan.name}" custom output must return a row object.`);
+    }
+    const final = await projectReadableFields({ kayan, row: parsed, actor });
+    const removed = Object.keys(parsed).filter((key) => !(key in final));
+    if (removed.length) {
+        throw new Error(`Kayan "${kayan.name}" custom output returned protected field "${removed[0]}" after read projection.`);
+    }
+    return fileURLs({ kayan, stored: internal, visible: final });
+};
+// An access callback answering `true` puts no tenancy filter on a per-tenant global, so
+// it would read another tenant's row. Refused by name; a `where` admitting several is not checked.
+export const assertSingleConstrained = (kayan, where) => {
+    if (kayan.single && kayan.tenant && !where) {
+        throw new Error(`Global "${kayan.name}" keeps the tenant field, and the actor's access constrains no rows, so no one row is the tenant's own. Return a Where from its read and update access that constrains the rows to the actor's tenant.`);
+    }
+};
+const loadExisting = async (kayan, store, id, where, tx, rows = aliveWhere(kayan)) => {
+    assertSingleConstrained(kayan, where);
+    const found = await store.find({ kayan: kayan.name, args: {
+            limit: 1,
+            page: 1,
+            lock: 'update',
+            // A write's own look at the row it changes, over a set an id or a constraint already reduced.
+            sort: { field: 'id', direction: 'asc' },
+            // A marked row is not there to change, so a second delete of it is the 404 an absent id gets.
+            where: combineWhere(kayan.single ? where : combineWhere({ id: { equals: id } }, where), rows),
+        }, tx });
+    return found.docs[0];
+};
+// Each related id must be one the target's own read access admits for this actor, and in the
+// written row's organization.
+const validateTenantRelationships = async (kayan, store, data, actor, existing, authorize, admin, tx) => {
+    const own = kayan.tenant;
+    await assertReferences({
+        kayan,
+        store,
+        data,
+        tenant: own ? (data[own] ?? existing?.[own]) : undefined,
+        // Asked with no operation, so no permission key is asked for.
+        access: (target) => authorize({ admin, actor, data: {}, effect: 'read', kayan: target }),
+        tx,
+    });
+};
+/**
+ * Refuses a relationship value naming a row the write may not point at: one of another
+ * organization than the written row's, or one `access` leaves out. A step's own raw write
+ * passes no `access`, so it is held to the organization alone.
+ */
+export const assertReferences = async ({ kayan, store, data, tenant, access, tx }) => {
+    const own = kayan.tenant;
+    // Gathered per target, so two fields at one kayan and a whole `hasMany` set are one read.
+    const targets = new Map();
+    for (const field of Object.values(kayan.fields)) {
+        // The ownership column is the runner's, or was judged above. A join takes no write.
+        if (!field.target || field.name === own || field.kind === 'join')
+            continue;
+        const given = data[field.name];
+        if (given === undefined || given === null)
+            continue;
+        for (const value of field.hasMany ? given : [given]) {
+            if (value === undefined || value === null)
+                continue;
+            targets.set(field.target, [...(targets.get(field.target) ?? []), { field: field.name, value }]);
+        }
+    }
+    for (const [target, sets] of targets) {
+        const far = target.tenant;
+        // A raw write to a shared row names it as it likes; the foreign key holds it.
+        if (!access && !far)
+            continue;
+        // Held whatever the target's own access answers, so no access widens it.
+        const tenanted = tenant !== undefined && tenant !== null && far ? { [far]: { equals: tenant } } : undefined;
+        // A 400: the value is what the caller sent wrong. Absent, hidden and another tenant's
+        // ids are one refusal, so none tells the caller which ids exist.
+        const refuse = (field) => {
+            const params = { kayan: kayan.name, field, target: target.name };
+            return tenanted
+                ? invalid({
+                    message: `"${kayan.name}" field "${field}" must reference a "${target.name}" row in the same tenant.`,
+                    key: 'error.invalid.tenant_reference',
+                    params,
+                })
+                : invalid({
+                    message: `"${kayan.name}" field "${field}" must reference a "${target.name}" row the actor can read.`,
+                    key: 'error.invalid.reference',
+                    params,
+                });
+        };
+        // With no organization and no access to ask, nothing scopes the target, so nothing is admitted.
+        if (!access && !tenanted)
+            throw refuse(sets[0].field);
+        let admits;
+        try {
+            admits = await access?.(target);
+        }
+        catch (thrown) {
+            if (!(thrown instanceof AsasError) || thrown.status !== 403)
+                throw thrown;
+            // Fail closed before the store is asked, so the foreign key cannot tell which ids exist.
+            throw refuse(sets[0].field);
+        }
+        // Postgres answers a uuid in lowercase, so ids are compared in that case.
+        const uuid = target.fields.id?.kind === 'uuid';
+        const keyOf = (value) => (uuid && typeof value === 'string' ? value.toLowerCase() : value);
+        const ids = [...new Set(sets.map(({ value }) => keyOf(value)))];
+        const found = await store.find({ kayan: target.name, args: {
+                limit: ids.length,
+                lock: 'update',
+                page: 1,
+                sort: { field: 'id', direction: 'asc' },
+                where: combineWhere(combineWhere(combineWhere({ id: { in: ids } }, admits), tenanted), 
+                // Nothing a plain read shows may point at a row no plain read shows; a step's own write may.
+                access ? publishedWhere(target) : undefined),
+            }, tx });
+        const admitted = new Set(found.docs.map((row) => keyOf(row.id)));
+        const refused = sets.find(({ value }) => !admitted.has(keyOf(value)));
+        if (refused)
+            throw refuse(refused.field);
+    }
+};
+export const defaultAccess = async (admin, actor) => {
+    if (!admin?.kayan || !admin.access || !actor || authActor(actor)?.collection !== admin.kayan)
+        return false;
+    return admin.access({ user: actor });
+};
+// Asked of the one store that grades this actor. The row answers deny first, so this
+// only narrows; a refusal is a 403, never a 5xx an offline client would retry.
+const assertPermission = (kayan, operation, actor) => {
+    if (operation === undefined)
+        return;
+    const keys = heldPermissions({ access: kayan.access, user: actor });
+    if (keys === undefined || keys === true)
+        return;
+    const key = `${kayan.name}.${operation}`;
+    if (keys.has(key))
+        return;
+    throw denied({
+        message: `Forbidden: "${kayan.name}" operation "${operation}" needs permission "${key}".`,
+        key: 'error.forbidden.permission',
+        params: { kayan: kayan.name, operation },
+    });
+};
+export const defaultAuthorize = async ({ admin, actor, data, effect, kayan, kind, operation: named, }) => {
+    if (effect === 'read') {
+        const access = kayan.access?.read;
+        const result = access
+            ? await access({ id: data.id, slug: kayan.name, user: actor })
+            : await defaultAccess(admin, actor);
+        if (!result)
+            throw denied({ message: `Forbidden: "${kayan.name}" read access denied.`, key: 'error.forbidden.read', params: { kayan: kayan.name } });
+        assertPermission(kayan, named, actor);
+        return result === true ? undefined : assertWhere(kayan, result);
+    }
+    const operation = effect;
+    const access = kayan.access?.[operation];
+    const { id, ...values } = data;
+    const accessData = kind === 'insert' ? data : kind === 'update' ? values : undefined;
+    const result = access
+        ? await access({ data: accessData, id, slug: kayan.name, user: actor })
+        : await defaultAccess(admin, actor);
+    if (operation === 'create') {
+        if (result !== true)
+            throw denied({ message: `Forbidden: "${kayan.name}" create access denied.`, key: 'error.forbidden.create', params: { kayan: kayan.name } });
+        assertPermission(kayan, named, actor);
+        return undefined;
+    }
+    if (!result)
+        throw denied({ message: `Forbidden: "${kayan.name}" ${operation} access denied.`, key: 'error.forbidden.operation', params: { kayan: kayan.name, operation } });
+    assertPermission(kayan, named, actor);
+    return result === true ? undefined : assertWhere(kayan, result);
+};
+// Shared with the bulk runner, so the depth cap, the cross-transaction refusals and the
+// ambient actor rule answer alike for a bulk and the row it is made of.
+export const beginWrite = ({ kayan, operation, store, cap, options, }) => {
+    const outer = running.getStore();
+    const chain = [...(outer?.context.chain ?? []), `${kayan.name}.${operation}`];
+    const depth = (outer?.context.depth ?? 0) + 1;
+    if (depth > cap) {
+        throw new Error(`Write depth ${depth} is past the cap of ${cap}: ${chain.join(' -> ')}.`);
+    }
+    // Frozen, so a step cannot reset `depth` and hand every write under it a spent cap.
+    const context = Object.freeze({
+        source: 'local',
+        ...(outer?.context ?? options?.context),
+        depth,
+        chain,
+    });
+    const open = outer?.transactions ?? new Map();
+    // A nested write joins the outer transaction on the same store, so both commit or roll
+    // back together; another store opens its own. Outside slots carry no transactions.
+    const joined = open.get(store);
+    if (outer?.transactions && !joined) {
+        throw new Error(`Kayan "${kayan.name}" operation "${operation}" cannot write to another store while transaction "${outer.context.chain.at(-1)}" is open.`);
+    }
+    if (joined?.settled) {
+        throw new Error(`Kayan "${kayan.name}" operation "${operation}" joined the transaction "${joined.operation}" opened, which has already settled, so the write that started this one was not awaited. Await every write a step begins.`);
+    }
+    const entry = joined ?? { tx: undefined, operation: `${kayan.name}.${operation}` };
+    const actor = outer?.user ?? options?.actor ?? null;
+    return { actor, context, entry, open };
+};
+// A write from outside the transaction would not roll back with it, or would land after
+// the commit; a step there calls a managed operation, which opens its own.
+const outsideStore = (kayan, operation, slot) => {
+    const refuse = () => {
+        throw new Error(`Kayan "${kayan.name}" operation "${operation}" reached the store from "${slot}", which runs outside the operation's transaction, so the write would not be in it. Write through tools.kayans, which opens its own, or move the step into "steps".`);
+    };
+    return Object.freeze({ insert: refuse, remove: refuse, update: refuse });
+};
+// No transaction is carried, so a managed write here opens its own. An `afterCommit`
+// throw is never an `AsasError`: the write it would refuse has committed.
+export const runOutside = async ({ kayan, tools, slot, list, start, around, }) => {
+    const given = Object.freeze({ ...tools, store: outsideStore(kayan, tools.operation, slot) });
+    return running.run(around, async () => {
+        let ctx = start;
+        try {
+            for (const step of list)
+                ctx = await step(ctx, given);
+        }
+        catch (cause) {
+            if (slot === 'beforeTransaction')
+                throw cause;
+            throw new Error(`Kayan "${kayan.name}" operation "${tools.operation}" threw in afterCommit, which runs after the commit, so the write stands.`, { cause });
+        }
+        return ctx;
+    });
+};
+// One that throws does not silence the rest, since each stands for a committed write;
+// the first error is the one reported.
+export const drain = async (queue) => {
+    // A wrapper, so a thunk that threw a falsy value is still raised.
+    let failure;
+    for (const queued of queue) {
+        try {
+            await queued();
+        }
+        catch (cause) {
+            failure ??= { cause };
+        }
+    }
+    if (failure)
+        throw failure.cause;
+};
+// A shape that names the key answers a probe value with an issue at it. An asynchronous
+// answer names nothing, so its key is refused.
+const namesKey = (schema, key) => {
+    const answer = schema['~standard'].validate({ [key]: Symbol(key) });
+    if (answer instanceof Promise) {
+        answer.catch(() => { });
+        return false;
+    }
+    return !!answer.issues?.some(({ path: [first] = [] }) => String(typeof first === 'object' ? first.key : first) === key);
+};
+export const write = ({ kayan, declaration, tools, store, cap, authorize, admin, tenantOf, }) => async (data = {}, options) => {
+    const list = atEffect(declaration.steps);
+    const { actor, context, entry, open } = beginWrite({ kayan, operation: tools.operation, store, cap, options });
+    // The id reaches the store before the operation's parse, so it is held to the shape at
+    // `id` first: a 400, not the store refusing a value of the wrong type as a 500.
+    if (tools.kind !== 'insert' && !kayan.single) {
+        const { issues = [] } = await tools.schema['~standard'].validate(withoutPrototype(data));
+        const atId = issues.filter(({ path: [first] = [] }) => (typeof first === 'object' ? first.key : first) === 'id');
+        if (atId.length)
+            throw issueRefusal(atId, tools.schema['~standard'].vendor);
+    }
+    refuseTenantOption({ kayan, operation: tools.operation, options });
+    const owner = writeTenant({ kayan, active: tenantOf(actor), effect: tools.effect, data });
+    const versions = kayan.versions;
+    // An operation with its own `input` that changes a row, and each bulk row, lands on the
+    // row as it is: it keeps `_status` and its columns also go into the pending draft.
+    const restoring = list.some((step) => sealOf(step) === 'restoreVersion');
+    const onto = !!versions?.drafts && ((!!declaration.input && tools.kind === 'update' && tools.operation !== 'update' && !restoring) || !!options?.[ontoRow]);
+    const drafts = !!versions?.drafts && !!options?.draft;
+    if (drafts && onto) {
+        throw invalid({
+            message: `Kayan "${kayan.name}" operation "${tools.operation}" writes its 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 },
+        });
+    }
+    // A draft save answers the whole latest draft, so it asks the key a draft read asks.
+    const askDrafts = () => authorize({ admin, actor, data: {}, effect: 'read', kayan, operation: 'findVersions' });
+    const draftsAsked = drafts || (!!versions?.drafts && data._status === 'draft');
+    // What `findVersions` admits for this actor, kept per row; `undefined` without the key.
+    const admits = draftsAsked
+        ? { where: await askDrafts() }
+        : versions?.drafts && tools.kind !== 'insert'
+            ? await askDrafts().then((where) => ({ where }), (thrown) => {
+                if (thrown instanceof AsasError && thrown.status === 403)
+                    return undefined;
+                throw thrown;
+            })
+            : undefined;
+    // Past the rows the actor may read drafts of, a never-published row answers the 404 an
+    // absent id does: a 403 would tell the actor which hidden ids exist.
+    const rowsWhere = !versions?.drafts || tools.kind === 'insert'
+        ? aliveWhere(kayan)
+        : !admits
+            ? publishedWhere(kayan)
+            : combineWhere(aliveWhere(kayan), draftsAsked || !admits.where ? admits.where : { or: [{ _status: { equals: 'published' } }, admits.where] });
+    // The restore's own key is asked before anything is looked up.
+    if (restoring) {
+        await authorize({ admin, actor, data: {}, effect: 'update', kayan, kind: 'update', operation: tools.operation });
+        const asked = Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'id' && !Object.hasOwn(kayan.fields, key)));
+        data = { ...asked, ...await restoreInput({
+                kayan: kayan,
+                store,
+                data,
+                actor,
+                authorize,
+                admin,
+                alive: rowsWhere,
+                seesDrafts: !!admits,
+                admits: admits?.where,
+            }) };
+    }
+    // First-register's own create runs whatever the kayan's create access says, while its table is empty.
+    const accessWhere = context.depth === 1 && firstRegisters.has(entry)
+        ? undefined
+        : await authorize({ admin, actor, data, effect: tools.effect, kayan, kind: tools.kind, operation: tools.operation });
+    // The constant that keeps a global to one row, so a caller's value for it is refused by name.
+    if (kayan.single && 'globalType' in data) {
+        throw denied({
+            message: `Forbidden: kayan "${kayan.name}" operation "${tools.operation}" cannot write field "globalType", which is the constant that keeps a global to one row.`,
+            key: 'error.forbidden.global_type',
+            params: { kayan: kayan.name, operation: tools.operation },
+        });
+    }
+    // Outside the transaction, before it opens: no row is loaded and no lock is held.
+    let values = data;
+    if (declaration.beforeTransaction.length) {
+        const before = await runOutside({
+            kayan,
+            tools,
+            slot: 'beforeTransaction',
+            list: atEffect(declaration.beforeTransaction),
+            start: { kayan, data: { ...data }, actor, user: actor, tx: undefined, context },
+            around: { context, user: actor },
+        });
+        values = before.data;
+    }
+    /** The last `ctx` the transaction ended with, which is what `afterCommit` is handed. */
+    let committed;
+    const run = (tx) => {
+        entry.tx = tx;
+        return running.run({ context, transactions: new Map(open).set(store, entry), user: actor }, async () => {
+            const existing = tools.kind === 'insert' ? undefined : await loadExisting(kayan, store, values.id, accessWhere, tx, rowsWhere);
+            // An actor who may not read this row's drafts writes onto it as it is, so nothing tells
+            // it a draft is pending.
+            const hidesDrafts = !!versions?.drafts && !!existing && (!admits || (!draftsAsked && !!admits.where
+                && !(await store.find({ kayan: kayan.name, args: { limit: 1, page: 1, sort: { field: 'id', direction: 'asc' }, where: combineWhere({ id: { equals: existing.id } }, admits.where) }, tx })).docs.length));
+            const asIs = onto || hidesDrafts;
+            // A row found without the constraint means the caller cannot address it (404); none means
+            // the upsert. A per-tenant global is left out: the unconstrained look would find another tenant's row.
+            if (kayan.single && !kayan.tenant && tools.kind === 'update' && !existing && accessWhere
+                && await loadExisting(kayan, store, values.id, undefined, tx)) {
+                throw missing({
+                    message: `No "${kayan.name}" row the access constraint admits.`,
+                    key: 'error.not_found.global',
+                    params: { kayan: kayan.name },
+                });
+            }
+            // One word decides the rest of the write: defaults, field callbacks, shape and step.
+            const kind = kayan.single && tools.kind === 'update' && !existing ? 'insert' : tools.kind;
+            const fieldOperation = kind === 'insert' ? 'create' : kind === 'update' ? 'update' : undefined;
+            // The row always holds the last published copy; a create still makes the row, as a draft.
+            const drafting = drafts && !!fieldOperation && data._status !== 'published';
+            const autosaving = drafting && versions.autosave && !!options?.autosave;
+            // A caller who named `_status` is judged by its field access like any column.
+            const status = drafting ? 'draft' : data._status ?? (asIs ? existing?._status : undefined) ?? 'published';
+            // A change builds on the row's latest version, so a draft keeps the drafts before it and a
+            // publish publishes them. Publishing a never-published row brings every column it holds.
+            const latest = versions?.drafts && existing
+                ? await latestVersion({ kayan: kayan, store, parent: existing.id, tx })
+                : undefined;
+            // A snapshot's organization is never the row's: the row keeps its own.
+            const newest = latest && { ...revived(kayan, latest.version), ...(kayan.tenant && { [kayan.tenant]: existing[kayan.tenant] }) };
+            const base = (!restoring && newest) || existing;
+            const merged = versions?.drafts && existing && fieldOperation && !restoring && !asIs
+                ? { ...changedColumns({ kayan, snapshot: base, row: existing, whole: !drafting && existing._status !== 'published' }), ...values }
+                : values;
+            // Carried from a draft rather than sent, so field access refuses rather than drops them.
+            const carried = merged === values ? [] : Object.keys(merged).filter((key) => !(key in values));
+            const pending = asIs && newest && !restoring && base?._status === 'draft' ? base : undefined;
+            // A key the operation's own shape would refuse is refused here first, in that shape's words.
+            if (drafting) {
+                const stray = Object.keys(data).find((key) => key !== 'id' && (Object.hasOwn(kayan.fields, key) ? providerOf(kayan.fields[key], fieldOperation) !== 'client' : !declaration.input || !namesKey(tools.schema, key)));
+                if (stray !== undefined)
+                    throw issueRefusal([{ message: `Unrecognized key: "${stray}"`, path: [stray] }], 'mithaq');
+            }
+            // What the caller read: the latest version for a writer who reads drafts, so
+            // `expectedUpdatedAt` holds a draft save, a publish, a delete and a restore alike.
+            const dataBefore = snapshot((!asIs && newest) || existing);
+            const owned = kayan.tenant;
+            const writeWhere = !owned || existing?.[owned] === undefined
+                ? accessWhere
+                : combineWhere(accessWhere, { [owned]: { equals: existing[owned] } });
+            // A global's update lands on the row that was found, never on an id the caller named.
+            const targetId = kayan.single ? existing?.id : values.id;
+            // The id is the runner's on both branches, which is why a global's update shape has none.
+            const given = kayan.single ? { ...values, id: existing?.id } : merged;
+            if (kayan.single && !existing)
+                delete given.id;
+            // The shipped field carries no default: the value is the global's own name.
+            if (kayan.single && !existing)
+                given.globalType = kayan.name;
+            const inputData = fieldOperation
+                ? await fieldAccess(fieldOperation, kayan, given, actor, targetId, tools.operation, existing, carried)
+                : given;
+            // The audit sink writes through the same three, so only the kayan's own writes save versions.
+            const versioned = versions ? kayan : undefined;
+            const own = (name) => versioned && name === kayan.name ? versioned : undefined;
+            const protectedStore = Object.freeze({
+                insert: async ({ tx: heldTx, kayan: name, data: values }) => {
+                    const row = await tools.store.insert({ tx: heldTx, kayan: name, data: values });
+                    const kept = own(name);
+                    if (kept)
+                        await saveVersion({ kayan: kept, store, writes: tools.store, tx: heldTx, row, autosave: autosaving });
+                    return row;
+                },
+                update: async ({ tx: heldTx, kayan: name, id, data: values }) => {
+                    const kept = own(name);
+                    if (drafting && kept) {
+                        const draft = { ...base, ...values, id: targetId };
+                        await saveVersion({ kayan: kept, store, writes: tools.store, tx: heldTx, row: draft, autosave: autosaving });
+                        return draft;
+                    }
+                    const row = await tools.store.update({ tx: heldTx, kayan: name, id: targetId ?? id, data: values, where: writeWhere });
+                    // A never-published row is its own draft, so the draft appended below is its one version.
+                    if (kept && !(pending && status === 'draft'))
+                        await saveVersion({ kayan: kept, store, writes: tools.store, tx: heldTx, row, autosave: false });
+                    // Appended after the row's own, so the draft stays the latest.
+                    if (kept && pending)
+                        await saveVersion({ kayan: kept, store, writes: tools.store, tx: heldTx, row: { ...pending, ...values, id: targetId, _status: 'draft' }, autosave: false });
+                    return row;
+                },
+                // A soft delete keeps the `remove` seal, so the effect, the access answer and the 404 stay
+                // the delete's; the mark is refused as a field any caller supplies.
+                remove: ({ tx: heldTx, kayan: name, id }) => kayan.softDelete
+                    ? tools.store.update({ tx: heldTx, kayan: name, id: targetId ?? id, data: { [kayan.softDelete]: new Date() }, where: writeWhere })
+                    : tools.store.remove({ tx: heldTx, kayan: name, id: targetId ?? id, where: writeWhere }),
+            });
+            // Its absence is a build fault: the partial update shape would make a row without its required fields.
+            if (kind !== tools.kind && !tools.insertSchema) {
+                throw new Error(`Kayan "${kayan.name}" operation "${tools.operation}" has no insert shape, so the row it would make cannot be parsed.`);
+            }
+            const insertSchema = tools.insertSchema;
+            // Copied, so a step writing `ctx.data` in place never changes the caller's object.
+            const runTools = Object.freeze({
+                ...tools,
+                kind,
+                // Read before `defaults` fills, so validation can refuse the caller a key and still let the runner's value through.
+                sent: Object.keys(data),
+                schema: drafting ? tools.draftInput ?? tools.draftWrite ?? tools.draftSchema : kind === tools.kind ? tools.schema : insertSchema,
+                store: protectedStore,
+                where: writeWhere,
+            });
+            let ctx = { kayan, data: { ...inputData }, actor, user: actor, tx, context, dataBefore, dataAfter: dataBefore };
+            // With no `input` the filled row is parsed, so a default reaches a required column; with one,
+            // the caller's strict shape is parsed first. A remove writes no column, so neither runs.
+            const fill = (one) => (fieldOperation ? defaults(one, runTools) : one);
+            ctx = declaration.input
+                ? fill(await parse({ schema: runTools.schema, ctx, tools: runTools }))
+                : await parse({ schema: runTools.schema, ctx: fill(ctx), tools: runTools });
+            // Filled after the parse, from the session alone.
+            if (kind === 'insert' && kayan.tenant)
+                ctx = { ...ctx, data: { ...ctx.data, [kayan.tenant]: owner } };
+            // The guards belong to the store seal, and no slot may hold one.
+            for (const step of atEffect([
+                ...declaration.beforeSteps,
+                ...list,
+                ...declaration.afterSteps,
+            ])) {
+                const seal = sealOf(step);
+                // A restore's step is the row's own update, so it is guarded as one.
+                if (seal && (storeSeals.includes(seal) || seal === 'restoreVersion')) {
+                    // Reads `kind`, so a global's first update still upserts; at the store seal, after the parse
+                    // has refused a malformed id.
+                    if (!existing && kind !== 'insert') {
+                        throw missing({
+                            message: `No "${kayan.name}" row with id ${String(values.id)} to ${kind === 'remove' ? 'delete' : 'update'}.`,
+                            key: 'error.not_found.row',
+                            params: { kayan: kayan.name, id: values.id, operation: kind === 'remove' ? 'delete' : 'update' },
+                        });
+                    }
+                    if (kind !== 'insert' && ctx.data.id !== targetId) {
+                        throw new Error(`Kayan "${kayan.name}" operation "${tools.operation}" cannot change the authorized target id.`);
+                    }
+                    if (fieldOperation) {
+                        ctx = { ...ctx, data: await fieldAccess(fieldOperation, kayan, ctx.data, actor, targetId, tools.operation, existing, carried) };
+                        if (kind !== 'remove')
+                            await validateTenantRelationships(kayan, store, ctx.data, actor, existing, authorize, admin, tx);
+                    }
+                    // A publish holds the row to every `required`, which the partial update shape cannot.
+                    if (versions?.drafts && status === 'published' && kind === 'update') {
+                        const unset = Object.values(kayan.fields).filter((field) => field.rules?.required && field.kind !== 'join' && (field.name in ctx.data ? ctx.data[field.name] : existing?.[field.name]) == null);
+                        if (unset.length)
+                            throw issueRefusal(unset.map((field) => ({ message: `${kayan.name}.${field.name}.required`, path: [field.name] })), 'mithaq');
+                        // A never-published row's create-only columns are asked of the create's field access and
+                        // parsed against the create shape.
+                        if (existing._status !== 'published') {
+                            const left = { ...existing, ...ctx.data };
+                            const made = Object.values(kayan.fields).filter((field) => field.kind !== 'join' && providerOf(field, 'create') === 'client' && left[field.name] != null);
+                            const createOnly = made.filter((field) => providerOf(field, 'update') !== 'client' && !(field.name in ctx.data)).map((field) => field.name);
+                            await fieldAccess('create', kayan, Object.fromEntries(createOnly.map((name) => [name, left[name]])), actor, targetId, tools.operation, existing, createOnly);
+                            await validated(insertSchema, Object.fromEntries(made.map((field) => [field.name, left[field.name]])));
+                        }
+                    }
+                    // A step that wrote a `never` field is the project contradicting its own declaration,
+                    // so a plain `Error`, never an `AsasError` blaming the caller, who cannot reach here.
+                    if (fieldOperation) {
+                        const written = Object.values(kayan.fields).find((field) => providerOf(field, fieldOperation) === 'never' && field.name in ctx.data);
+                        if (written) {
+                            throw new Error(`Kayan "${kayan.name}" operation "${tools.operation}" wrote field "${written.name}", which declares providedBy "never" on ${fieldOperation}, so nothing supplies it.`);
+                        }
+                    }
+                    // Written after the field callbacks: publishing is what a write without `draft` means,
+                    // not a column a role must hold a key for.
+                    if (versions?.drafts && fieldOperation)
+                        ctx = { ...ctx, data: { ...ctx.data, _status: status } };
+                    // After the field callbacks, which deny the field's own update and would refuse the
+                    // runner's value; on insert no create callback would refuse a step's.
+                    if (kayan.single)
+                        ctx = { ...ctx, data: { ...ctx.data, globalType: kayan.name } };
+                }
+                ctx = await step(ctx, runTools);
+            }
+            committed = ctx;
+            // A draft may be short of `required`, so it leaves through the draft shape, which holds it to its kinds alone.
+            const row = ctx.data;
+            return publicResult({
+                kayan,
+                row,
+                actor,
+                internalOutput: drafting || (tools.draftSchema && row._status === 'draft') ? tools.draftSchema : tools.output,
+                publicOutput: tools.publicOutput,
+            });
+        });
+    };
+    // A throw here is `AfterCommitError`: the write has happened, and nothing the caller sent was wrong.
+    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);
+    // Drained by the write that opened the transaction; an outer rollback throws before the drain.
+    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);
+    }
+    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;
+};