@drhomet/mithaq 0.1.1 → 0.2.0

package/dist/asas/http/orpc.js

@@ -4,9 +4,9 @@ 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 } from '../runner/errors.js';
+import { AfterCommitError, AsasError, afterCommitHeader, codes, retryConflict } from '../runner/errors.js';
 import { issueRefusal, withoutPrototype } from '../runner/steps.js';
-import { decodeJson, draftOptions } from './fetch.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
@@ -16,120 +16,138 @@ const boundaryRefusal = (thrown) => thrown instanceof ORPCError && thrown.code =
  * 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 = ({ rpc = '/api/rpc', api = '/api', context, onError, } = {}) => (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.
-            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 }) => {
+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 {
-                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;
+                onError(thrown);
             }
-            catch (thrown) {
-                if (!(thrown instanceof AfterCommitError))
-                    throw thrown;
-                report(thrown.cause);
-                const warning = warnings.getStore();
-                if (warning)
-                    warning.said = 'failed';
-                return thrown.result;
+            catch {
+                // Deliberately empty: reporting may not change what is reported.
             }
-        });
-    }
-    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;
-            // Built before any procedure runs, so a throw here is outside the middleware;
-            // it still reaches `onError`.
-            let held;
+        };
+        // 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 {
-                const who = await actor();
-                held = context ? await context(request, who) : { actor: who };
+                return await next();
             }
             catch (thrown) {
-                if (!(thrown instanceof AsasError))
+                // 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;
-            }
-            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;
+                    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,
+                });
             }
-            return null;
-        },
+        });
+        // 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

@@ -1,4 +1,4 @@
-import { type ResolvedOperation, type WriteTools } from './steps.ts';
+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';

package/dist/asas/runner/bulk.js

@@ -1,11 +1,12 @@
 // 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 { AfterCommitError, AsasError, invalid } from './errors.js';
+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, runOutside } from './write.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.
@@ -21,7 +22,7 @@ export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit:
     }
     const { actor, context, entry, open } = beginWrite({ kayan, operation: tools.operation, store, cap, options });
     refuseTenantOption({ kayan, operation: tools.operation, options });
-    writeTenant({ kayan, active: tenantOf(actor), effect: tools.effect, data: given?.data });
+    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,
@@ -42,7 +43,7 @@ export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit:
             tools,
             slot: 'beforeTransaction',
             list: atEffect(declaration.beforeTransaction),
-            start: { kayan, data: { ...given }, actor, user: actor, tx: undefined, context },
+            start: { kayan, data: { ...given }, actor, user: actor, tx: undefined, context, tenant: owner },
             around: { context, user: actor },
         });
         values = before.data;
@@ -69,11 +70,12 @@ export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit:
         }
         // 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));
-        // `lock: 'update'` holds every matched row until commit; the limit is the ceiling,
-        // and `totalDocs` counts the whole matched set without reading it.
+        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: 'update', sort: { field: 'id', direction: 'asc' }, where },
+            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
@@ -85,7 +87,6 @@ export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit:
                 params: { kayan: kayan.name, operation: tools.operation, matched: found.totalDocs, ceiling },
             });
         }
-        const values = (data.data ?? {});
         const docs = [];
         // In order, not in parallel: each write joins this transaction, which is one connection.
         for (const row of found.docs) {
@@ -117,15 +118,16 @@ export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit:
         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) });
-            let ctx = { kayan, data: { ...values }, actor, user: actor, tx, context };
+            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: runTools });
+            ctx = await parse({ schema: runTools.schema, ctx, tools: publicTools });
             for (const step of atEffect([
                 ...declaration.beforeSteps,
                 ...list,
                 ...declaration.afterSteps,
             ]))
-                ctx = await step(ctx, runTools);
+                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.
@@ -174,6 +176,9 @@ export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit:
     try {
         result = await store.transaction(run);
     }
+    catch (thrown) {
+        throw retryConflict(thrown);
+    }
     finally {
         entry.settled = true;
     }

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

@@ -4,6 +4,7 @@ export declare const codes: {
     readonly 403: 'FORBIDDEN';
     readonly 404: 'NOT_FOUND';
     readonly 409: 'CONFLICT';
+    readonly 413: 'PAYLOAD_TOO_LARGE';
     readonly 429: 'TOO_MANY_REQUESTS';
     readonly 503: 'SERVICE_UNAVAILABLE';
 };
@@ -48,10 +49,12 @@ export declare const invalid: ({ message, key, params, cause }: Refusal) => Asas
  */
 export declare const missing: ({ message, key, params, cause }: Refusal) => AsasError;
 /**
- * The write collides with a row already there, as a 409 so an offline client
- * does not retry it. It never says which column or whose row it hit.
+ * 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;

package/dist/asas/runner/errors.js

@@ -5,6 +5,7 @@ export const codes = {
     403: 'FORBIDDEN',
     404: 'NOT_FOUND',
     409: 'CONFLICT',
+    413: 'PAYLOAD_TOO_LARGE',
     429: 'TOO_MANY_REQUESTS',
     503: 'SERVICE_UNAVAILABLE',
 };
@@ -48,10 +49,25 @@ export const invalid = ({ message, key, params, cause }) => new AsasError(messag
  */
 export const missing = ({ message, key, params, cause }) => new AsasError(message, 404, key, params, cause);
 /**
- * The write collides with a row already there, as a 409 so an offline client
- * does not retry it. It never says which column or whose row it hit.
+ * 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 const conflict = ({ message, key, params, cause }) => new AsasError(message, 409, key, params, cause);
+/** A transaction the database rolled back may be retried, without exposing its query or rows. */
+export const retryConflict = (thrown) => {
+    if (thrown instanceof AsasError || thrown instanceof AfterCommitError)
+        return thrown;
+    const seen = new Set();
+    for (let cause = thrown; cause && typeof cause === 'object' && !seen.has(cause); cause = cause.cause) {
+        if (cause instanceof AfterCommitError)
+            return thrown;
+        seen.add(cause);
+        if (['40P01', '40001'].includes(String(cause.code))) {
+            return conflict({ message: 'The transaction conflicted with another write. Try again.', key: 'error.conflict.retry', cause: thrown });
+        }
+    }
+    return thrown;
+};
 // Shared by the read layer, which answers the caller with a 400, and the drizzle
 // store, which throws at the access callback that built the query.
 export const localizedQuery = ({ kayan, field, what, locales = [], }) => what === 'sort'

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

@@ -2,7 +2,7 @@ import { type Authorize, type ManagedAdmin, type ReadOptions } from './write.ts'
 import { type Where } from '../../mithaq/where.ts';
 import { type AuditHandler, type ReadTools, type ResolvedOperation } from './steps.ts';
 import type { StandardSchemaV1 } from '../../mithaq/standard-schema.ts';
-import { type ResolvedKayan } from '../../mithaq/types.ts';
+import { type ResolvedField, type ResolvedKayan } from '../../mithaq/types.ts';
 import type { Store } from '../../mithaq/language.ts';
 import { type TenantScope } from './tenant.ts';
 /** What a `find` list takes where it declares no input of its own. */
@@ -45,7 +45,7 @@ export declare const assertReadableWhere: <Actor>({ kayan, where, actor, authori
 }) => Promise<Where | undefined>;
 /** The caller's own `where`, refused as a 400 where its grammar is malformed or a value is not of its column's kind. */
 export declare const checkedWhere: (kayan: ResolvedKayan, where: unknown) => Promise<Where>;
-export declare const readers: <Actor>({ kayan, store, cap, defaultLimit, joinLimit, admin, authorize, kayans, of, audit, catalog, openTenant, }: {
+export declare const readers: <Actor>({ kayan, store, cap, defaultLimit, joinLimit, admin, authorize, kayans, of, audit, catalog, openTenant, tenantOf, pickers, }: {
     kayan: ResolvedKayan;
     store: Store;
     cap: number;
@@ -65,4 +65,8 @@ export declare const readers: <Actor>({ kayan, store, cap, defaultLimit, joinLim
         reach: unknown;
         kayan: ResolvedKayan;
     }) => Promise<TenantScope | undefined>;
+    /** The organization the actor's session names, which a step reads as `ctx.tenant`. */
+    tenantOf: (actor: unknown) => string | undefined;
+    /** Every relationship field pointing at this kayan, by `<kayan>.<field>`, which a picker's read names as `for`. */
+    pickers?: Readonly<Record<string, ResolvedField>>;
 }) => ReaderMap<Actor>;

package/dist/asas/runner/read.js

@@ -1,4 +1,4 @@
-import { aliveWhere, assertSingleConstrained, assertWhereGrammar, publicResult, publishedWhere } from './write.js';
+import { aliveWhere, assertSingleConstrained, assertWhere, assertWhereGrammar, publicResult, publishedWhere } from './write.js';
 import { combineWhere } from '../../mithaq/where.js';
 import { atEffect, issueRefusal, parse } from './steps.js';
 import { sortableFields, unsortable } from '../../mithaq/types.js';
@@ -55,7 +55,8 @@ const protectedField = async (kayan, field, actor, authorize, admin, what = 'fil
     // A locale is one column of the root field: no hop, and read access is per field, so
     // the check over the root is the whole security surface.
     const locale = relatedField && root?.locales?.includes(relatedField) ? relatedField : undefined;
-    const hop = locale ? undefined : relatedField;
+    // A json field's path stays inside its own value, so the field's read access is the whole of it.
+    const hop = locale || root?.kind === 'json' ? undefined : relatedField;
     const found = hop ? root?.target?.fields[hop] : root;
     if (!root || !found)
         throw invalid({ message: `Kayan "${kayan.name}" query names unknown field "${field}".`, key: 'error.invalid.unknown_field', params: { kayan: kayan.name, field } });
@@ -160,6 +161,9 @@ const isoMoment = /^\d{4}-\d{2}-\d{2}(?:[T ](?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d
 const coerced = (kind, value) => {
     if (typeof value !== 'string')
         return value;
+    // Lower-cased, as the parse lower-cases a uuid, so a store comparing text finds the row too.
+    if (kind === 'uuid')
+        return value.toLowerCase();
     if (kind === 'checkbox')
         return value.toLowerCase() === 'true' ? true : value.toLowerCase() === 'false' ? false : value;
     if ((kind === 'number' || kind === 'integer') && value.trim() !== '' && Number.isFinite(Number(value)))
@@ -178,6 +182,9 @@ const whereIssues = async (kayan, where, at) => {
         }
         const [name, second] = key.split('.');
         const field = kayan.fields[name];
+        // A value inside a json field is any scalar, which no column of a kind holds.
+        if (field.kind === 'json')
+            continue;
         // A hop compares a column of the kayan the field points at, and a set of
         // many named alone compares that kayan's id; a locale is a column of this one.
         const hop = !!field.target && (second ? !field.locales?.includes(second) : !!field.hasMany);
@@ -277,7 +284,7 @@ const sortOf = async (kayan, sort, actor, authorize, admin) => {
     await protectedField(kayan, field, actor, authorize, admin, 'sort');
     return { field, direction };
 };
-export const readers = ({ kayan, store, cap, defaultLimit, joinLimit, admin, authorize, kayans, of, audit, catalog = [], openTenant, }) => {
+export const readers = ({ kayan, store, cap, defaultLimit, joinLimit, admin, authorize, kayans, of, audit, catalog = [], openTenant, tenantOf, pickers = {}, }) => {
     // Every managed read reaches the store here, so the soft-delete filter is put on once.
     const alive = aliveWhere(kayan);
     // A draft read reads published rows and the drafts `findVersions` admits, so no actor
@@ -377,10 +384,23 @@ export const readers = ({ kayan, store, cap, defaultLimit, joinLimit, admin, aut
         }
         return judged;
     };
+    // A picker's read for one relationship field holds to what that field's `filterOptions` offers the
+    // actor, ANDed beside the read's own access, so it narrows and never widens.
+    const offeredFor = async (named, actor) => {
+        if (named === undefined)
+            return undefined;
+        const field = typeof named === 'string' && Object.hasOwn(pickers, named) ? pickers[named] : undefined;
+        if (!field)
+            throw invalid({ message: `Managed read option "for" names ${JSON.stringify(named)}, which is no relationship field pointing at kayan "${kayan.name}".`, key: 'error.invalid.read_option', params: { option: 'for' } });
+        const offered = await field.filterOptions?.({ user: actor });
+        if (offered === undefined || offered === true)
+            return undefined;
+        return offered === false ? { id: { in: [] } } : assertWhere(kayan, offered);
+    };
     const fetchList = async (input, actor, granted, drafts) => {
         const accessWhere = granted ? granted.where : await readAccess(kayan, actor, authorize, admin);
         const callerWhere = await judgedWhere(input.where, actor, accessWhere);
-        const where = combineWhere(callerWhere, accessWhere);
+        const where = combineWhere(combineWhere(callerWhere, accessWhere), await offeredFor(input.for, actor));
         const limit = integerOption('limit', input.limit, defaultLimit, 0);
         const page = integerOption('page', input.page, 1, 1);
         const [first, ...rest] = judges(actor, accessWhere);
@@ -515,14 +535,16 @@ export const readers = ({ kayan, store, cap, defaultLimit, joinLimit, admin, aut
             },
         });
         const tx = currentTx();
-        let ctx = { kayan, data: { ...data }, actor, user: actor, tx, context };
+        // A reach past one organization names none; a global is its active organization's row under any reach.
+        const owner = kayan.tenant && (!tenant || kayan.single) ? tenantOf(actor) : undefined;
+        let ctx = { kayan, data: { ...data }, actor, user: actor, tx, context, tenant: owner };
         const run = async () => {
             // A read fills no default: it writes no column.
             ctx = await parse({ schema: input, ctx, tools });
             // `strictFunctionTypes` checks the actor contravariantly, hence the one cast. A read runs
             // no service-target list: it opens no transaction, and `audit` is taken only by naming it.
             for (const step of atEffect([...list, ...declaration.afterSteps]))
-                ctx = await step(ctx, tools);
+                ctx = { ...(await step(ctx, tools)), tenant: owner };
         };
         await running.run(around, run);
         // A total carries no column, so nothing to mask.

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

@@ -2,7 +2,7 @@ import type { StandardSchemaIssue, StandardSchemaV1 } from '../../mithaq/standar
 import type { BoundOf } from './write.ts';
 import type { Where } from '../../mithaq/where.ts';
 import type { ResolvedKayan, RuntimeField, ServiceOf } from '../../mithaq/types.ts';
-import type { Store } from '../../mithaq/language.ts';
+import type { RawStepStore, StepStore, Store } from '../../mithaq/language.ts';
 /**
  * What the caller passed, plus the three keys the runner keeps. `Extra` is the service target's
  * `context`, so a project reads its own keys typed. Held in an `AsyncLocalStorage`, so nested writes are counted.
@@ -31,6 +31,13 @@ export type Ctx<Data = Record<string, unknown>, Actor = unknown, Tx = unknown, E
     /** The store's transaction. Every write in the list goes through it. */
     tx: Tx;
     context: Context<Extra>;
+    /**
+     * The active organization the operation is scoped to, for a step that keeps something per
+     * organization. `undefined` on a shared kayan, under a read's `tenant` option, which reaches
+     * past one organization, and where the language has no tenant target. Only a copy: the runner
+     * puts it back after every step and scopes from the session, so rewriting it moves nothing.
+     */
+    readonly tenant?: string;
 };
 /** The keys the project put on the service target's `context`, or the open record where it put none. */
 export type ContextOf<Service> = Service extends {
@@ -85,8 +92,8 @@ export type WriteTools<Kayans = unknown, Actor = unknown, Tx = unknown> = Common
     kind: 'deleteMany' | 'insert' | 'remove' | 'update' | 'updateMany';
     /** One kayan's bound operations, found and typed by the declaration handed in, so a step imports the kayan it calls. */
     of: BoundOf<'write'>;
-    /** The store's three writes, each bound, and the store itself is not here. */
-    store: Pick<Store, 'insert' | 'remove' | 'update'>;
+    /** Bound store calls, sealed to the active organization; no adapter or client is exposed. */
+    store: StepStore;
     /** Access constraint already granted for this operation, if access returned one. */
     where?: Where;
     /** The keys the caller's own object carried, read before any step ran, so validation can tell the runner's values from the caller's. */
@@ -113,6 +120,10 @@ export type BulkResult<Doc = Record<string, unknown>> = {
         message: string;
     }[];
 };
+/** The runner keeps string names on its side of the step boundary; adapters never receive declarations. */
+export type RuntimeWriteTools<Kayans = unknown, Actor = unknown, Tx = unknown> = Omit<WriteTools<Kayans, Actor, Tx>, 'store'> & {
+    store: RawStepStore;
+};
 export type Tools = ReadTools | WriteTools;
 /** The positions `resolve` checks: the store and read steps, each named after the `Store` method it calls. */
 export type Seal = 'audit' | 'count' | 'defaults' | 'deleteMany' | 'find' | 'findOne' | 'insert' | 'remove' | 'update' | 'updateMany' | 'validate' | 'findVersions' | 'findVersionByID' | 'restoreVersion';
@@ -215,6 +226,8 @@ Extra extends Record<string, unknown> = Record<string, unknown>> = {
     afterCommit?: SlotSteps<Given, Extra>;
     /** A public output contract, parsed after field masking. */
     output?: RowOutput | ((schemas: Schemas) => RowOutput);
+    /** On a bulk operation, the kayan's single-row operation it runs on each matched row, handed `data` and the row's id. Without it, `update` or `delete`. */
+    each?: string;
     /** One entry per target with something to say about this operation, by the target's name: `targets.<screen>` is what that screen's button asks for. */
     targets?: Readonly<Record<string, OperationScreen<Input> | undefined>>;
 };
@@ -235,6 +248,7 @@ export type AnyOperation = {
     afterSteps?: OperationSteps<never, never> | ((defaults: never) => OperationSteps<never, never>);
     afterCommit?: OperationSteps<never, never> | ((defaults: never) => OperationSteps<never, never>);
     output?: RowOutput | ((schemas: never) => RowOutput);
+    each?: string;
     targets?: Readonly<Record<string, OperationScreen | undefined>>;
 };
 export type Operations<Given = Lists, Schemas = DerivedShapes, Locale extends string = string, Input = never> = {
@@ -255,11 +269,15 @@ export type ResolvedOperation = {
     mode?: ReadMode;
     /** Always a schema: an `output` written as a function is resolved at build. */
     output?: RowOutput;
+    /** On a bulk operation, the single-row operation it runs per row. */
+    each?: string;
     /** What each target says about this operation, as the declaration wrote it. */
     targets?: Readonly<Record<string, OperationScreen | undefined>>;
 };
 /** What position this step holds, or nothing at all for a step of the app's own. */
 export declare const sealOf: (step: OperationStep<never>) => Seal | undefined;
+/** Where the other copy of mithaq that sealed this step was loaded from, if one did. */
+export declare const foreignCopyOf: (step: OperationStep<never>) => string | undefined;
 /** Hold an operation's `output` function until `build` has the derived shapes. */
 export declare const holdOutput: (operation: ResolvedOperation, of: (schemas: never) => RowOutput) => void;
 /** The schema function this operation's `output` carries, or nothing for a bare schema. */
@@ -396,5 +414,5 @@ export type LanguageSlots = {
     afterSteps?: readonly ProjectStep[];
     afterCommit?: readonly ProjectStep[];
 };
-export declare const resolveOperations: (declared: DeclaredOperations | ((defaults: never) => DeclaredOperations) | undefined, slots?: LanguageSlots) => Record<string, AnyOperation>;
+export declare const resolveOperations: (declared: DeclaredOperations | undefined, slots?: LanguageSlots) => Record<string, AnyOperation>;
 export {};