@drhomet/mithaq 0.1.1 → 0.2.0

package/dist/asas/runner/write.js

@@ -1,9 +1,10 @@
 // One list in one place, so drizzle's callback transaction is kept as it is.
+import { stepTools } from './store.js';
 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 { AfterCommitError, AsasError, conflict, denied, invalid, missing, retryConflict } from './errors.js';
+import { defaultKinds, isStorableText } 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';
@@ -21,6 +22,9 @@ 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 ([value].flat().some((one) => typeof one === 'string' && !isStorableText(one))) {
+        throw new Error(`${said} field "${field}" operator "${operator}" compares text holding a NUL or half a surrogate pair, which no column holds.`);
+    }
     if (operator === 'exists') {
         if (typeof value !== 'boolean')
             throw new Error(`${said} field "${field}" operator "exists" needs a boolean.`);
@@ -44,25 +48,44 @@ const checkOperatorValue = (said, field, operator, value) => {
 };
 // 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.
+// A json field's path may run past two segments: its keys are no columns, and Payload names them so.
 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 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, or a key at each segment after a json field.`;
     const field = parts[0];
-    const path = parts[1];
     const resolved = kayan.fields[field];
-    if (!resolved)
+    if ((parts.length > 2 && resolved?.kind !== 'json') || parts.some((part) => !part || !isStorableText(part)))
+        throw new Error(unsupported);
+    const path = parts[1];
+    if (!resolved || !Object.hasOwn(kayan.fields, field))
         throw new Error(`${said} names unknown field "${key}".`);
+    if (resolved.kind === 'json')
+        return { field, key, kind: resolved.kind, operators: resolved.operators };
     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)
+    if (!target || !Object.hasOwn(resolved.target.fields, path))
         throw new Error(`${said} path "${key}" names unknown related field.`);
+    // A path into json across a hop would be a third segment, and a json value compared whole has no store answer.
+    if (target.kind === 'json')
+        throw new Error(`${said} path "${key}" reaches json field "${path}" across a relationship, and a json field is filtered on its own kayan alone.`);
     return { field, key, kind: target.kind, operators: target.operators };
 };
+/** Raw store filters keep their adapter's value and empty-filter semantics; only declared paths are checked here. */
+export const assertStoreWhere = (kayan, where) => {
+    for (const [key, value] of Object.entries(where)) {
+        if (key === 'and' || key === 'or') {
+            if (Array.isArray(value))
+                for (const one of value)
+                    assertStoreWhere(kayan, one);
+        }
+        else
+            queryField({ kayan, key, said: `Kayan "${kayan.name}" store filter` });
+    }
+    return where;
+};
 // 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)) {
@@ -92,6 +115,13 @@ export const assertFieldWhere = ({ said, key, kind, operators, value, valued = t
             throw new Error(`${said} field "${key}" operator "${operator}" only supports numeric, date and datetime fields.`);
         }
         checkOperatorValue(said, key, operator, operand);
+        if (!valued && Array.isArray(operand) && operand.length > whereLimits.values) {
+            throw new Error(`${said} field "${key}" operator "${operator}" lists at most ${whereLimits.values} values.`);
+        }
+        // Each word of a `like` is a pattern the store matches, so its words are held to the same count.
+        if (!valued && operator === 'like' && typeof operand === 'string' && operand.trim().split(/\s+/).length > whereLimits.values) {
+            throw new Error(`${said} field "${key}" operator "like" holds at most ${whereLimits.values} words.`);
+        }
         // 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') {
@@ -110,7 +140,13 @@ export const assertFieldWhere = ({ said, key, kind, operators, value, valued = t
 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 }) => {
+/**
+ * How large a caller's `where` may be: the values one `in` or `not_in` lists, and the fields, `and`s and
+ * `or`s it holds in all, however nested. Each is a condition the store runs, so past these a read is
+ * refused before it reaches the store rather than holding it for minutes.
+ */
+export const whereLimits = { values: 1000, nodes: 200 };
+const normalizedWhere = ({ kayan, where, valued, said, nodes = { left: whereLimits.nodes } }) => {
     if (!where || typeof where !== 'object' || Array.isArray(where)) {
         throw new Error(`${said} is not an object of fields.`);
     }
@@ -120,11 +156,14 @@ const normalizedWhere = ({ kayan, where, valued, said }) => {
     // No prototype, so `__proto__` is a key like any other.
     const normalized = Object.create(null);
     for (const [key, value] of entries) {
+        // An access constraint is the project's own to size; a caller's is held to the limits.
+        if (!valued && --nodes.left < 0)
+            throw new Error(`${said} holds at most ${whereLimits.nodes} fields, "and"s and "or"s.`);
         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 }));
+            normalized[key] = value.map((one) => normalizedWhere({ kayan, where: one, valued, said, nodes }));
             continue;
         }
         const queried = queryField({ kayan, key, said });
@@ -138,6 +177,111 @@ const normalizedWhere = ({ kayan, where, valued, said }) => {
 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);
+/** Every field of `kayans` whose `onDelete` keeps a row of `target` while it names it. */
+export const restrictingPointers = (kayans, target) => kayans.flatMap((kayan) => Object.values(kayan.fields)
+    .filter((field) => field.kind !== 'join' && field.target?.name === target.name && field.rules?.onDelete === 'restrict')
+    .map((field) => ({ kayan, field })));
+/** How many of the rows that still name a row the refusal names by title; its count says the rest. */
+const namedUses = 5;
+const byId = { field: 'id', direction: 'asc' };
+/**
+ * The ids of the rows of each kayan that name `id` through `pointers`, a row whose latest version
+ * names it among them, since the foreign key holds live rows alone and a pending draft would
+ * otherwise keep an id nothing answers for. A pointing kayan that is tenant-owned is read within
+ * `tenant` when one is given, so a count never reaches another organization's rows.
+ */
+export const referencingIds = async ({ id, pointers, store, tenant, tx }) => {
+    const uses = new Map();
+    for (const { kayan, field } of pointers) {
+        const ids = uses.get(kayan) ?? new Set();
+        const within = (path) => (kayan.tenant && tenant !== undefined ? { [path]: { equals: tenant } } : undefined);
+        const rows = await store.find({ kayan: kayan.name, args: { limit: 0, page: 1, sort: byId, where: combineWhere({ [field.name]: { equals: id } }, within(kayan.tenant)) }, tx });
+        for (const row of rows.docs)
+            ids.add(String(row.id));
+        if (kayan.versions) {
+            // ponytail: `version.<field>` is read with no index, a scan of the versions table per delete;
+            // index it once a delete is measured slow.
+            const versions = await store.find({ kayan: kayan.versions.table, args: { limit: 0, page: 1, sort: byId, where: combineWhere({ and: [{ latest: { equals: true } }, { [`version.${field.name}`]: { equals: id } }] }, within(`version.${kayan.tenant}`)) }, tx });
+            for (const version of versions.docs)
+                ids.add(String(version.parent));
+        }
+        if (ids.size)
+            uses.set(kayan, ids);
+    }
+    return uses;
+};
+/**
+ * Refuses the delete while a live row or the latest version of a row names it, in the delete's own
+ * transaction. The delete holds the row `FOR UPDATE`, and a write naming it holds it `FOR KEY SHARE`
+ * in `assertReferences`, a draft save included. The two conflict, so no new reference lands between
+ * this count and the delete. An update holds its own row as `rowLock` says, which `FOR KEY SHARE` passes
+ * unless the update names a unique column. The refusal counts the actor's own
+ * organization's rows and names by title only those the actor reads; a row another organization's
+ * rows name is refused with no count at all.
+ */
+const refuseReferenced = async ({ kayan, existing, pointers, store, tenant, tx, authorize, admin, actor }) => {
+    const counted = async (within) => {
+        const found = await referencingIds({ id: existing.id, pointers, store, tenant: within, tx });
+        // A row that names itself goes with itself; read off the stored row, since the caller's id may differ in case.
+        found.get(kayan)?.delete(String(existing.id));
+        return { found, total: [...found.values()].reduce((sum, ids) => sum + ids.size, 0) };
+    };
+    // Every organization's rows gate the delete, since the foreign key holds no draft; only the
+    // actor's own are counted and named to it.
+    const all = await counted(undefined);
+    if (!all.total)
+        return;
+    const own = tenant === undefined ? all : await counted(tenant);
+    if (own.total !== all.total) {
+        throw conflict({
+            message: `A "${kayan.name}" row is still named by rows this caller does not see, so it is not deleted.`,
+            key: 'error.conflict.referenced',
+            params: { kayan: kayan.name },
+        });
+    }
+    const uses = [];
+    for (const [one, ids] of own.found) {
+        if (ids.size)
+            uses.push({ by: one.name, count: ids.size, ...(await titlesOf({ kayan: one, ids: [...ids], store, tx, authorize, admin, actor })) });
+    }
+    throw conflict({
+        message: `A "${kayan.name}" row is still named by ${uses.map(({ by, count }) => `${count} "${by}" row${count === 1 ? '' : 's'}`).join(' and ')}, so it is not deleted.`,
+        key: 'error.conflict.referenced',
+        params: { kayan: kayan.name, by: uses[0].by, uses },
+    });
+};
+/**
+ * The titles of the rows among `ids` this actor finds and whose title field it reads, a draft only
+ * where it reads drafts. A title that points at another row is its raw id, so such rows are
+ * counted alone; a moment is sent as a value, marked so the screen formats it.
+ */
+const titlesOf = async ({ kayan, ids, store, tx, authorize, admin, actor }) => {
+    const title = Object.values(kayan.targets ?? {}).map((target) => target?.useAsTitle).find((one) => typeof one === 'string');
+    const field = title && Object.hasOwn(kayan.fields, title) ? kayan.fields[title] : undefined;
+    if (!field || field.target || field.kind === 'join')
+        return { titles: [] };
+    const asked = (operation) => authorize({ admin, actor, data: {}, effect: 'read', kayan, operation }).then((where) => ({ where }), (thrown) => {
+        if (thrown instanceof AsasError && thrown.status === 403)
+            return undefined;
+        throw thrown;
+    });
+    const readable = await asked('find');
+    if (!readable)
+        return { titles: [] };
+    const drafts = kayan.versions?.drafts ? await asked('findVersions') : undefined;
+    const shown = kayan.versions?.drafts && drafts
+        ? combineWhere(aliveWhere(kayan), drafts.where && { or: [{ _status: { equals: 'published' } }, drafts.where] })
+        : publishedWhere(kayan);
+    const sort = field.rules?.localized ? byId : { field: field.name, direction: 'asc' };
+    const found = await store.find({ kayan: kayan.name, args: { limit: namedUses, page: 1, sort, where: { and: [{ id: { in: ids } }, readable.where, shown].filter(Boolean) } }, tx });
+    const titles = [];
+    for (const row of found.docs) {
+        const visible = await projectReadableFields({ kayan, row, actor });
+        if (Object.hasOwn(visible, field.name))
+            titles.push(visible[field.name]);
+    }
+    return { titles, ...(field.kind === 'date' || field.kind === 'datetime' ? { titleKind: field.kind } : {}) };
+};
 const fieldAccess = async (operation, kayan, data, actor, id, named, doc, kept = []) => {
     const next = { ...data };
     const refused = [];
@@ -227,12 +371,29 @@ export const assertSingleConstrained = (kayan, 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)) => {
+/**
+ * The lock a write holds on a row it changes, as Postgres's own statement takes it: `FOR UPDATE` for a
+ * delete, or for an update naming a column of a unique index, which holds off a write naming the row
+ * `FOR KEY SHARE`, and `FOR NO KEY UPDATE` for any other update, which that write passes. A soft delete
+ * is an update of its mark, and asks no rows naming its row, so it has no reference to hold off. Taken
+ * whole when the row loads, before any value is compared: an UPDATE raising its lock later would wait on
+ * a writer that named the row in between while that writer waits on it, a deadlock.
+ *
+ * ponytail: publishing a latest draft's unique column can still raise this lock; take `update` for every
+ * non-draft update on a kayan with drafts and a unique index if that path needs to be covered.
+ * ponytail: an update step can raise its own row's lock by writing a unique column or hard-deleting the
+ * row; take `update` at load for an operation whose steps may do either if that path needs to be covered.
+ */
+export const rowLock = ({ kayan, kind, data }) => {
+    const written = kind === 'remove' || kind === 'deleteMany' ? (kayan.softDelete ? [kayan.softDelete] : undefined) : Object.keys(data);
+    return !written || kayan.indexes.some((index) => index.unique && index.fields.some((name) => written.includes(name))) ? 'update' : 'noKeyUpdate';
+};
+const loadExisting = async ({ kayan, store, id, where, tx, rows = aliveWhere(kayan), lock }) => {
     assertSingleConstrained(kayan, where);
     const found = await store.find({ kayan: kayan.name, args: {
             limit: 1,
             page: 1,
-            lock: 'update',
+            lock,
             // 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.
@@ -251,6 +412,11 @@ const validateTenantRelationships = async (kayan, store, data, actor, existing,
         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 }),
+        // A field's `filterOptions` holds a save to what its picker offers, as Payload's does.
+        offered: async (field) => {
+            const answer = await field.filterOptions?.({ user: actor, tx });
+            return answer === undefined || answer === true ? undefined : answer === false ? { id: { in: [] } } : assertWhere(field.target, answer);
+        },
         tx,
     });
 };
@@ -259,9 +425,12 @@ const validateTenantRelationships = async (kayan, store, data, actor, existing,
  * 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 }) => {
+// Postgres answers a uuid in lowercase, so ids are compared in that case.
+const keyIn = (kayan) => (value) => kayan.fields.id?.kind === 'uuid' && typeof value === 'string' ? value.toLowerCase() : value;
+export const assertReferences = async ({ kayan, store, data, tenant, access, offered, tx }) => {
     const own = kayan.tenant;
-    // Gathered per target, so two fields at one kayan and a whole `hasMany` set are one read.
+    // Gathered per target, so two fields at one kayan and a whole `hasMany` set are one read; a
+    // field whose options are its own is read apart.
     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.
@@ -270,13 +439,16 @@ export const assertReferences = async ({ kayan, store, data, tenant, access, tx
         const given = data[field.name];
         if (given === undefined || given === null)
             continue;
+        const key = offered && field.filterOptions ? field : field.target;
         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 }]);
+            const held = targets.get(key) ?? { target: field.target, sets: [] };
+            held.sets.push({ field: field.name, value });
+            targets.set(key, held);
         }
     }
-    for (const [target, sets] of targets) {
+    for (const [key, { 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)
@@ -312,18 +484,19 @@ export const assertReferences = async ({ kayan, store, data, tenant, access, tx
             // 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 keyOf = keyIn(target);
         const ids = [...new Set(sets.map(({ value }) => keyOf(value)))];
         const found = await store.find({ kayan: target.name, args: {
                 limit: ids.length,
-                lock: 'update',
+                // The lock a foreign key takes: it holds off the row's delete, and never another write naming the
+                // row or a plain update of its other columns, so those neither wait on it nor deadlock with it.
+                // See "Create, update and delete" in packages/mithaq/README.md for checks that need a stronger lock.
+                lock: 'keyShare',
                 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),
+                combineWhere(access ? publishedWhere(target) : undefined, key === target ? undefined : await offered(key))),
             }, tx });
         const admitted = new Set(found.docs.map((row) => keyOf(row.id)));
         const refused = sets.find(({ value }) => !admitted.has(keyOf(value)));
@@ -418,17 +591,19 @@ 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 });
+    return Object.freeze({ find: refuse, hold: refuse, upsert: refuse, sum: refuse, 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) });
+    const given = stepTools({ ...tools, store: outsideStore(kayan, tools.operation, slot) });
+    // Read before the first step, which is handed `start` itself and may rewrite it in place.
+    const { tenant } = start;
     return running.run(around, async () => {
         let ctx = start;
         try {
             for (const step of list)
-                ctx = await step(ctx, given);
+                ctx = { ...(await step(ctx, given)), tenant };
         }
         catch (cause) {
             if (slot === 'beforeTransaction')
@@ -464,7 +639,7 @@ const namesKey = (schema, key) => {
     }
     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) => {
+export const write = ({ kayan, declaration, tools, store, cap, authorize, admin, tenantOf, pointers = [], }) => 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
@@ -546,7 +721,7 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
             tools,
             slot: 'beforeTransaction',
             list: atEffect(declaration.beforeTransaction),
-            start: { kayan, data: { ...data }, actor, user: actor, tx: undefined, context },
+            start: { kayan, data: { ...data }, actor, user: actor, tx: undefined, context, tenant: owner },
             around: { context, user: actor },
         });
         values = before.data;
@@ -556,7 +731,7 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
     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);
+            const existing = tools.kind === 'insert' ? undefined : await loadExisting({ kayan, store, id: values.id, where: accessWhere, tx, rows: rowsWhere, lock: rowLock({ kayan, kind: tools.kind, data: values }) });
             // 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
@@ -565,7 +740,7 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
             // 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)) {
+                && await loadExisting({ kayan, store, id: values.id, where: undefined, tx, lock: 'noKeyUpdate' })) {
                 throw missing({
                     message: `No "${kayan.name}" row the access constraint admits.`,
                     key: 'error.not_found.global',
@@ -593,7 +768,7 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
                 : 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;
+            let 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)));
@@ -619,38 +794,83 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
             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.
+            // The audit sink writes through the same three, so only the kayan's own writes save versions,
+            // through the store itself: a versions table is no kayan, and the seal refuses it to a step.
             const versioned = versions ? kayan : undefined;
             const own = (name) => versioned && name === kayan.name ? versioned : undefined;
+            // The row this write authorized, which alone takes its access, versions and soft delete, in
+            // whatever case the caller sent its uuid. A step naming any other id writes that row.
+            const keyOf = keyIn(kayan);
+            const ownRow = (name, id) => kind !== 'insert' && name === kayan.name && (keyOf(id) === keyOf(targetId) || (existing !== undefined && id === existing.id));
+            // And a raw write of this kayan never reaches the authorized row, however its id is spelled.
+            const elsewhere = (args) => kind !== 'insert' && args.kayan === kayan.name && targetId !== undefined ? { ...args, where: combineWhere(args.where, { id: { not_equals: targetId } }) } : args;
             const protectedStore = Object.freeze({
+                find: tools.store.find,
+                hold: tools.store.hold,
+                sum: tools.store.sum,
+                upsert: async (args) => {
+                    const kept = own(args.kayan);
+                    if (drafting && kept)
+                        throw invalid({ message: "An upsert writes stored rows, not this operation's draft snapshot. Use update for that draft.", key: 'error.invalid.value', params: { kayan: args.kayan } });
+                    const row = await tools.store.upsert(args);
+                    const current = ownRow(args.kayan, row.id);
+                    if (kept && !(current && pending && status === 'draft'))
+                        await saveVersion({ kayan: kept, store, writes: store, tx: args.tx, row, autosave: false });
+                    if (kept && current && pending) {
+                        pending = { ...pending, ...Object.fromEntries(Object.keys(args.data).map((field) => [field, row[field]])), id: targetId, _status: 'draft' };
+                        await saveVersion({ kayan: kept, store, writes: store, tx: args.tx, row: pending, autosave: false });
+                    }
+                    return row;
+                },
                 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 });
+                        await saveVersion({ kayan: kept, store, writes: store, tx: heldTx, row, autosave: autosaving });
                     return row;
                 },
-                update: async ({ tx: heldTx, kayan: name, id, data: values }) => {
+                update: async (args) => {
+                    const { tx: heldTx, kayan: name, id, data: values } = args;
+                    // Any other row is the step's own raw write, held by the tenant seal alone.
+                    if (!ownRow(name, id))
+                        return tools.store.update(elsewhere(args));
                     const kept = own(name);
+                    const incremented = Object.keys(values).filter((field) => kayan.fields[field]?.kind !== 'json' && values[field] && typeof values[field] === 'object' && '$inc' in values[field]);
+                    if (drafting && kept && incremented.length)
+                        throw invalid({ message: 'An increment writes a stored integer field, not a draft snapshot.', key: 'error.invalid.value', params: { kayan: name } });
                     if (drafting && kept) {
                         const draft = { ...base, ...values, id: targetId };
-                        await saveVersion({ kayan: kept, store, writes: tools.store, tx: heldTx, row: draft, autosave: autosaving });
+                        await saveVersion({ kayan: kept, store, writes: 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 });
+                    const row = await tools.store.update({ tx: heldTx, kayan: name, id: targetId, 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 });
+                        await saveVersion({ kayan: kept, store, writes: 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 });
+                    if (kept && pending) {
+                        pending = { ...pending, ...values, ...Object.fromEntries(incremented.map((field) => [field, row[field]])), id: targetId, _status: 'draft' };
+                        await saveVersion({ kayan: kept, store, writes: store, tx: heldTx, row: pending, 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 }),
+                remove: async (args) => {
+                    const { tx: heldTx, kayan: name, id } = args;
+                    if (!ownRow(name, id))
+                        return tools.store.remove(elsewhere(args));
+                    if (kayan.softDelete)
+                        return tools.store.update({ tx: heldTx, kayan: name, id: targetId, data: { [kayan.softDelete]: new Date() }, where: writeWhere });
+                    // A marked row is kept, so only a delete that removes it answers to the rows naming it.
+                    // An update step can remove its own row, so exclude new references before counting them.
+                    // This raises its lock; the upgrade path is taking `update` at load for such an operation.
+                    if (pointers.length && existing && kind !== 'remove')
+                        await store.find({ kayan: name, args: { limit: 1, page: 1, lock: 'update', sort: byId, where: { id: { equals: existing.id } } }, tx: heldTx });
+                    if (pointers.length && existing)
+                        await refuseReferenced({ kayan, existing, pointers, store, tenant: kayan.tenant ? existing[kayan.tenant] : tenantOf(actor), tx: heldTx, authorize, admin, actor });
+                    return tools.store.remove({ tx: heldTx, kayan: name, id: targetId, 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) {
@@ -667,13 +887,14 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
                 store: protectedStore,
                 where: writeWhere,
             });
-            let ctx = { kayan, data: { ...inputData }, actor, user: actor, tx, context, dataBefore, dataAfter: dataBefore };
+            const publicTools = stepTools(runTools);
+            let ctx = { kayan, data: { ...inputData }, actor, user: actor, tx, context, dataBefore, dataAfter: dataBefore, tenant: owner };
             // 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);
+            const fill = (one) => (fieldOperation ? defaults(one, publicTools) : one);
             ctx = declaration.input
-                ? fill(await parse({ schema: runTools.schema, ctx, tools: runTools }))
-                : await parse({ schema: runTools.schema, ctx: fill(ctx), tools: runTools });
+                ? fill(await parse({ schema: runTools.schema, ctx, tools: publicTools }))
+                : await parse({ schema: runTools.schema, ctx: fill(ctx), tools: publicTools });
             // Filled after the parse, from the session alone.
             if (kind === 'insert' && kayan.tenant)
                 ctx = { ...ctx, data: { ...ctx.data, [kayan.tenant]: owner } };
@@ -696,7 +917,11 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
                         });
                     }
                     if (kind !== 'insert' && ctx.data.id !== targetId) {
-                        throw new Error(`Kayan "${kayan.name}" operation "${tools.operation}" cannot change the authorized target id.`);
+                        throw conflict({
+                            message: `Kayan "${kayan.name}" operation "${tools.operation}" cannot change the authorized target id.`,
+                            key: 'error.conflict.target',
+                            params: { kayan: kayan.name, operation: tools.operation },
+                        });
                     }
                     if (fieldOperation) {
                         ctx = { ...ctx, data: await fieldAccess(fieldOperation, kayan, ctx.data, actor, targetId, tools.operation, existing, carried) };
@@ -735,7 +960,7 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
                     if (kayan.single)
                         ctx = { ...ctx, data: { ...ctx.data, globalType: kayan.name } };
                 }
-                ctx = await step(ctx, runTools);
+                ctx = { ...(await step(ctx, publicTools)), tenant: owner };
             }
             committed = ctx;
             // A draft may be short of `required`, so it leaves through the draft shape, which holds it to its kinds alone.
@@ -774,6 +999,9 @@ export const write = ({ kayan, declaration, tools, store, cap, authorize, admin,
     try {
         result = await store.transaction(run);
     }
+    catch (thrown) {
+        throw retryConflict(thrown);
+    }
     finally {
         entry.settled = true;
     }

package/dist/auth/better-auth/access.d.ts

@@ -6,6 +6,20 @@ export type BetterAuthAccessOptions<Roles extends SystemRoles, Table extends Row
         statements: Readonly<Record<string, readonly string[]>>;
     }>>;
 };
+/**
+ * The access target over Better Auth's own `member.role` and nothing else: a member holds the system
+ * roles its membership row names in that organization, comma-separated, and there is no custom role
+ * and no assignment table. It suits a project whose roles are the provider's owner, admin and member.
+ * The row is read from the store for the organization asked about, never off the session, so a
+ * membership elsewhere grants nothing here.
+ *
+ * A `member.role` slug is one a tenant's admin can mint, since the provider's dynamic access control
+ * is on, so `roles` holds only slugs a tenant may hold, or `rolesOf` drops the rest: a backoffice role
+ * named in it would otherwise grant its keys inside the tenant.
+ */
+export declare const memberRoleTarget: <const Roles extends SystemRoles, const Table extends RowTable, Actor>({ roles, rolesOf, access, }: Omit<AccessOptions<Roles, Table, Actor>, 'kayan'>) => AccessTarget<Roles, Table, Actor> & {
+    readonly type: 'memberRole';
+};
 /**
  * The access target over Better Auth's store: a custom role is an `organizationRole` row.
  * Read directly, not through `hasPermission`, whose cache never invalidates a narrowed role.

package/dist/auth/better-auth/access.js

@@ -29,6 +29,38 @@ const readPermission = (value) => {
     }
     return parsed;
 };
+/**
+ * The access target over Better Auth's own `member.role` and nothing else: a member holds the system
+ * roles its membership row names in that organization, comma-separated, and there is no custom role
+ * and no assignment table. It suits a project whose roles are the provider's owner, admin and member.
+ * The row is read from the store for the organization asked about, never off the session, so a
+ * membership elsewhere grants nothing here.
+ *
+ * A `member.role` slug is one a tenant's admin can mint, since the provider's dynamic access control
+ * is on, so `roles` holds only slugs a tenant may hold, or `rolesOf` drops the rest: a backoffice role
+ * named in it would otherwise grant its keys inside the tenant.
+ */
+export const memberRoleTarget = ({ roles, rolesOf, access, }) => ({
+    capability: 'access',
+    type: 'memberRole',
+    roles,
+    ...(rolesOf ? { rolesOf } : {}),
+    access: (access ?? {}),
+    // Better Auth's own model and columns.
+    reads: ['member'],
+    resolve: async ({ store, tenant, member, actor }) => {
+        // A read without a tenant would be every tenant's; the actor still goes through `rolesOf`, which
+        // answers backoffice staff, who have no active organization, their backoffice roles.
+        const found = scoped(tenant) && scoped(member)
+            ? await allRows({ store, kayan: 'member', where: { and: [{ organizationId: { equals: tenant } }, { userId: { equals: member } }] } })
+            : { docs: [] };
+        // Split the way the provider's own owner checks split it: exact, untrimmed, so ` owner` is no owner.
+        const slugs = [...new Set(found.docs.flatMap((row) => (typeof row.role === 'string' ? row.role.split(',').filter(Boolean) : [])))];
+        const held = heldSlugs({ roles, rolesOf, slugs, actor });
+        const { everything, keys } = systemKeys(roles, held);
+        return { permissions: everything ? '*' : [...keys], roles: held };
+    },
+});
 /**
  * The access target over Better Auth's store: a custom role is an `organizationRole` row.
  * Read directly, not through `hasPermission`, whose cache never invalidates a narrowed role.

package/dist/auth/better-auth/generate.d.ts

@@ -8,9 +8,11 @@ export declare const header = "// Written by `mithaq generate auth` from the Bet
  * Writes one kayan file per Better Auth table, and one barrel beside them. With `check`, writes
  * nothing and returns the files a run would change or delete. A file without the header is never touched.
  */
-export declare const generateAuth: ({ options, directory, check, provider, providers, screens, schemaName, }: {
+export declare const generateAuth: ({ options, directory, language, check, provider, providers, screens, schemaName, }: {
     options: Parameters<typeof getAuthTables>[0];
     directory: URL;
+    /** The module each generated kayan imports `defineKayan` from: `generate.language`, as given. */
+    language: string;
     check?: boolean;
     /** The Postgres schema every kayan of this instance is built in, from its `providers` entry. */
     schemaName?: string;