@volter/world-core 3.0.155 → 3.0.157

package/dist/src/derived-core.js

@@ -5,8 +5,9 @@ import { parseExactJson, compareExactNumbers, exactInteger, isExactIntegerValue
 // how lists page, how errors read, which fields are state and how they move). From those two this
 // serves CRUD generically and applies declared transitions, over the kernel's tree and write path.
 // Nothing here knows a vendor: every vendor difference is a manifest value.
-import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from "./serve.js";
-import { copyResource, ownFields, parentStamp, subjectHistory, treeChangesSince, treeStamp } from "./log.js";
+import { applyTwinWrite, applyTwinWriteAtomic, applyTwinWrites, twinResources } from "./serve.js";
+import { copyResource, foldLocalWrite, heldSubject, ownFields, parentStamp, subjectHistory, treeChangesSince, treeResources, treeStamp } from "./log.js";
+import { performsAtHeadNow } from "./head.js";
 import { getActiveWorldStore } from "./world-store.js";
 import { getActiveBlobStore } from "./blob-store.js";
 import { worldPaths } from "./storage.js";
@@ -21,8 +22,9 @@ import { MACHINE_POOL, poolFor, guardedMachinePool } from "./machines.js";
 import { askApplication, deliverEvents } from "./events.js";
 import { handlerCrypto, hmac, ksuidFrom, lettersFrom, sha256, uuidFrom } from "./signing.js";
 import { hashFieldValue } from "./hash.js";
-import { readResourceBlob, removeResourceBlob, writeResourceBlob } from "./resource-blob.js";
+import { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, writeResourceBlob, writeResourceBlobStream } from "./resource-blob.js";
 import { managedDatabase, unboundDatabase } from "./managed-database.js";
+import { redisServiceTimes } from "./redis/service-times.js";
 import { execRedisRun } from "./redis/engine.js";
 import { sendMail } from "./smtp.js";
 import { ownField, parseBracketForm } from "./form.js";
@@ -71,12 +73,13 @@ export function strictFields(m, operation, body) {
         if (!field)
             return refuse(strict.unknown, { name });
         const { type } = field;
-        const fits = value === null
+        const fits = (value === null && !(type === 'array' && strict.arrays?.[name]))
             || (type === 'boolean' && typeof value === 'boolean')
             || (type === 'integer' && isExactIntegerValue(value))
             || (type === 'number' && (typeof value === 'number' || isExactIntegerValue(value)))
             || (type === 'string' && typeof value === 'string')
-            || !['boolean', 'integer', 'number', 'string'].includes(type);
+            || (type === 'array' && Array.isArray(value) && (!strict.arrays?.[name] || value.every(item => typeof item === strict.arrays[name])))
+            || !['boolean', 'integer', 'number', 'string', 'array'].includes(type);
         if (!fits)
             return refuse(strict.type, { name, type: type === 'integer' ? 'an integer' : `a ${type}` });
         if ((typeof value === 'number' || isExactIntegerValue(value)) && ((field.minimum !== undefined && compareExactNumbers(value, field.minimum) < 0) || (field.maximum !== undefined && compareExactNumbers(value, field.maximum) > 0))) {
@@ -263,14 +266,16 @@ export function resourcesOfType(service, type, root) {
         }
         held.stamp = delta.stamp;
     }
-    else if (!held || held.stamp !== treeStamp(service, root)) {
-        // the stamp is read before the fold, so a write between them can only leave a newer fold under an older stamp
+    else {
+        // the stamp is read once, before the fold, so a write between them can only leave a newer fold under an older stamp
         const stamp = treeStamp(service, root);
-        const byType = new Map();
-        for (const r of twinResources(service, root))
-            (byType.get(r.type) ?? byType.set(r.type, new Map()).get(r.type)).set(`${r.type}:${r.id}`, r);
-        held = { stamp, byType };
-        indexes.set(key, held);
+        if (!held || held.stamp !== stamp) {
+            const byType = new Map();
+            for (const r of twinResources(service, root))
+                (byType.get(r.type) ?? byType.set(r.type, new Map()).get(r.type)).set(`${r.type}:${r.id}`, r);
+            held = { stamp, byType };
+            indexes.set(key, held);
+        }
     }
     return [...(held.byType.get(type)?.values() ?? [])].map(copyResource);
 }
@@ -299,13 +304,20 @@ function parentField(row, path) {
         value = value && typeof value === 'object' ? value[key] : undefined;
     return value;
 }
-function missingParent(m, resource, call, root) {
-    const parent = m.resources[resource]?.parent;
+function parentOfCall(decl, call) {
+    const parent = decl?.parent;
+    const names = parent?.params ?? (parent?.param === undefined ? [] : [parent.param]);
+    return parent?.whenNamed && names.length && !names.some((name) => Object.hasOwn(call.params, name))
+        ? undefined : parent;
+}
+function missingParent(m, resource, call, root, tenant) {
+    const parent = parentOfCall(m.resources[resource], call);
     if (!parent)
         return undefined;
     const id = parentValue(parent, call.params);
     const where = Object.entries(parent.where ?? {}).map(([field, template]) => [field, String(fill(template, call.params))]);
-    const found = (r) => (where.length ? where.every(([field, v]) => String(parentField(r, field)) === v) : r.id === id);
+    const found = (r) => (where.length ? where.every(([field, v]) => String(parentField(r, field)) === v) : r.id === id)
+        && (!m.tenant || m.resources[parent.resource]?.shared || r[m.tenant.field] === tenant);
     return id !== undefined && stored(m, parent.resource, root, { withDeleted: parent.allowDeleted === true }).some(found) ? undefined : notFound(m, parent.resource, String(id), parent.param ?? parent.params?.at(-1));
 }
 /** The vendor's view of a stored subject: its own fields, bookkeeping (`_`) left out. */
@@ -688,7 +700,11 @@ function recordedInput(m, call, merged) {
     const id = call.operation.id;
     const sent = sentOf.get(call);
     const activity = call.request.headers.get('x-volter-world-activity') === 'provisioning' ? { activity: 'provisioning' } : {};
-    const asSent = sent ? { ...activity, path: sent.path, query: sent.query, body: sent.body, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { ...activity, path: call.params, body: merged };
+    const door = m.doors?.find(d => d.id === id);
+    const body = sent?.body ?? merged;
+    const safeBody = door?.redactBody?.length && body && typeof body === 'object' && !Array.isArray(body)
+        ? Object.fromEntries(Object.entries(body).filter(([key]) => !door.redactBody.includes(key))) : body;
+    const asSent = sent ? { ...activity, path: sent.path, query: sent.query, body: safeBody, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { ...activity, path: call.params, body: safeBody };
     if (id === 'graphql') {
         const b = (sent?.body ?? {});
         return { ...activity, graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
@@ -707,28 +723,27 @@ const scopeOfCall = new WeakMap();
 const requestOfCall = new WeakMap();
 async function writeDetailed(m, call, resource, id, fields, operation, params, root, occurredAt, checks) {
     const before = stateBeforeWrite(m, resource, id, root);
+    const prior = counted(m, resource) ? stored(m, resource, root).find((r) => r.id === id) : undefined;
     const withFiles = async (input) => { const files = input.operationId ? await keptFiles(m, call, root) : undefined; return files ? { ...input, files } : input; };
     const { resource: row, result } = await applyTwinWrite(m.service, 
-    // who made it: the login the pack's identity reads off the request, when it declares one, so a subject's
-    // history can say who did each thing
     // a vendor's own move (ctx.asVendor, the clock) is the World's, as the clock's writes are: no API call a head performs
     inVendorMove()
         ? { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: { clock: true }, occurredAt, actor: { kind: 'system' } }
-        : { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: await withFiles(recordedInput(m, call, params)), occurredAt, actor: { kind: 'agent', ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) } }, root);
+        : { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: await withFiles(recordedInput(m, call, params)), occurredAt, actor: { kind: 'agent' } }, root);
     observeStateWrite(m, result, before, root, checks);
-    return finishWrite(m, call, resource, row, result, operation, params, root, occurredAt);
+    return finishWrite(m, call, resource, row, result, operation, params, root, occurredAt, prior && { ...prior });
 }
-async function atomicWrite(m, call, resource, decide, operation, params, root, occurredAt, unchangedId, checks) {
-    const input = recordedInput(m, call, params);
-    const files = input.operationId ? await keptFiles(m, call, root) : undefined;
+async function atomicWrite(m, call, resource, decide, operation, params, root, occurredAt, unchangedId, checks, omitInput = false) {
+    const input = omitInput ? undefined : recordedInput(m, call, params);
+    const files = input?.operationId ? await keptFiles(m, call, root) : undefined;
     let before;
     const committed = await applyTwinWriteAtomic(m.service, (snapshot) => {
         const selected = decide(snapshot);
-        if (selected && transitionObserver)
+        if (selected && (transitionObserver || counted(m, resource)))
             before = snapshot.find((r) => r.type === storedType(m, resource) && r.id === selected.id);
         return selected ? { kind: 'write', value: selected.id, write: {
                 operation, subjectType: storedType(m, resource), subjectId: selected.id, fields: selected.fields,
-                input: files ? { ...input, files } : input, occurredAt, actor: { kind: 'agent', ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) },
+                ...(input ? { input: files ? { ...input, files } : input } : {}), occurredAt, actor: { kind: 'agent', ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) },
             } } : { kind: 'skip', value: undefined };
     }, root);
     if (!committed.result || !committed.value) {
@@ -737,10 +752,10 @@ async function atomicWrite(m, call, resource, decide, operation, params, root, o
     }
     observeStateWrite(m, committed.result, before, root, checks);
     const row = resourcesOfType(m.service, storedType(m, resource), root).find((r) => r.id === resolveSubjectId(m.service, storedType(m, resource), committed.value, root));
-    return (await finishWrite(m, call, resource, row, committed.result, operation, params, root, occurredAt)).body;
+    return (await finishWrite(m, call, resource, row, committed.result, operation, params, root, occurredAt, before)).body;
 }
-async function finishWrite(m, call, resource, row, result, operation, params, root, occurredAt) {
-    await keepCounts(m, call, resource, row, params, root, occurredAt);
+async function finishWrite(m, call, resource, row, result, operation, params, root, occurredAt, prior) {
+    await keepCounts(m, call, resource, row, params, root, occurredAt, prior);
     const body = view(m, resource, row);
     // the write's own context for its hooks, in the scope the call was served in (a walk's application answers, a tenant,
     // the managed database), at the write's moment
@@ -762,27 +777,30 @@ async function finishWrite(m, call, resource, row, result, operation, params, ro
 }
 /** The declared counts a written subject is a child in (a resource's `counts`), each kept on its parent: written when
  *  the count moved, through the write path, so the parent's history says when. */
-async function keepCounts(m, call, resource, row, params, root, occurredAt) {
+async function keepCounts(m, call, resource, row, params, root, occurredAt, prior) {
     for (const [parent, decl] of Object.entries(m.resources)) {
         for (const [field, c] of Object.entries(decl.counts ?? {})) {
             if (storedType(m, c.of) !== storedType(m, resource))
                 continue;
-            const parentId = parentField(row, c.by);
-            if (parentId === undefined || parentId === null)
-                continue;
-            const pid = String(parentId);
-            const held = stored(m, parent, root).find((r) => String(c.parentKey ? ownFields(r)[c.parentKey] : r.id) === pid);
-            if (!held)
-                continue;
-            const n = stored(m, c.of, root).filter((r) => {
-                const x = r;
-                return String(parentField(x, c.by)) === pid && (c.present === undefined || (x[c.present] !== undefined && x[c.present] !== null)) && (c.absent === undefined || parentField(ownFields(r), c.absent) === undefined || parentField(ownFields(r), c.absent) === null) && Object.entries(c.unless ?? {}).every(([key, value]) => ownFields(r)[key] !== value);
-            }).length + (c.plus ?? 0);
-            if (held[field] !== n)
-                await writeDetailed(m, call, parent, String(held.id), { [field]: n }, `${storedType(m, parent)}.counted`, params, root, occurredAt);
+            // the parent the subject is under now, and the one it left when the write moved it: both counts changed
+            const pids = new Set([parentField(row, c.by), prior === undefined ? undefined : parentField(prior, c.by)].filter((v) => v !== undefined && v !== null).map(String));
+            for (const pid of pids) {
+                const held = stored(m, parent, root).find((r) => String(c.parentKey ? ownFields(r)[c.parentKey] : r.id) === pid);
+                if (!held)
+                    continue;
+                const n = stored(m, c.of, root).filter((r) => {
+                    const x = r;
+                    return String(parentField(x, c.by)) === pid && (c.present === undefined || (x[c.present] !== undefined && x[c.present] !== null)) && (c.absent === undefined || parentField(ownFields(r), c.absent) === undefined || parentField(ownFields(r), c.absent) === null) && Object.entries(c.unless ?? {}).every(([key, value]) => ownFields(r)[key] !== value);
+                }).length + (c.plus ?? 0);
+                if (held[field] !== n)
+                    await writeDetailed(m, call, parent, String(held.id), { [field]: n }, `${storedType(m, parent)}.counted`, params, root, occurredAt);
+            }
         }
     }
 }
+/** Whether any resource counts this one (`counts`): only then does a write read the subject as it stood, for the parent
+ *  it may leave. */
+const counted = (m, resource) => Object.values(m.resources).some((d) => Object.values(d.counts ?? {}).some((c) => storedType(m, c.of) === storedType(m, resource)));
 /** An answer in the vendor's success envelope, under the operation's key, when the vendor has one. */
 function envelope(m, op, body) {
     return m.success && op.answers?.key ? { ...m.success, [op.answers.key]: body } : body;
@@ -1129,16 +1147,16 @@ export async function serveCore(m, call, scope = {}) {
     // the body is read from a copy, so the call's own request is still unread for the write hook's context
     const params = await boundaryParams(m, { ...call, request: call.request.clone() }, root);
     const idParam = subjectOf(m, resource, call);
-    const orphan = missingParent(m, resource, call, root);
-    if (orphan)
-        return { served: orphan };
-    const parent = decl.parent;
+    const parent = parentOfCall(decl, call);
     const parentId = parent ? parentValue(parent, call.params) : undefined;
     // the caller's tenant, when the vendor has tenancy and the resource is not shared by every tenant
     const tenantField = m.tenant && !decl.shared ? m.tenant.field : undefined;
     const tenant = tenantField && scope.tenant ? await scope.tenant(await contextFor(m, { ...call, request: call.request.clone() }, scope)) : undefined;
     if (tenantField && tenant === undefined)
         return { unmodeled: `the caller names no tenant (semantics/tenant.ts) for ${resource}` };
+    const orphan = missingParent(m, resource, call, root, tenant);
+    if (orphan)
+        return { served: orphan };
     const underParent = (r) => (!parent || r[parent.field] === parentId)
         && (!tenantField || r[tenantField] === tenant);
     const paths = expandPaths(m, params);
@@ -1222,6 +1240,10 @@ export async function serveCore(m, call, scope = {}) {
                 const requested = op.class === 'update' ? data[field] : undefined;
                 if (op.class === 'update' && requested === undefined)
                     continue;
+                if (op.class === 'update' && sdecl.unchanged === 'allow' && stateOf(sdecl, current[field]) === stateOf(sdecl, requested)) {
+                    changes[field] = requested;
+                    continue;
+                }
                 const { move, refusal } = transitionFor(field, sdecl, op.id, current[field], requested, hit.id);
                 if (refusal)
                     return { served: vendorError(m, refusal) };
@@ -1282,6 +1304,12 @@ export function sse(m, events, operationId) {
     return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache' } });
 }
 /** The context the kernel opens for a call (a handler's, a door's, a screen's). Kernel-internal: packs are given it. */
+/** A media type whose body the core reads for a context (and records with a write): JSON, a form, multipart, text,
+ *  or none named. */
+const coreReadsBody = (type) => {
+    const media = (type ?? '').split(';')[0].trim().toLowerCase();
+    return media === '' || media === 'application/json' || media.endsWith('+json') || media === 'application/x-www-form-urlencoded' || media.startsWith('multipart/') || media.startsWith('text/');
+};
 export async function contextFor(m, call, scope) {
     const root = scope.root;
     const asAsked = call;
@@ -1291,8 +1319,10 @@ export async function contextFor(m, call, scope) {
     // the guard's parse when it made one (taken once), else this context's own
     // a body that is its payload's bytes (S3's PutObject) is never read as JSON, whatever its label
     const payload = bytesPayload(call.operation);
-    const parsed = payload ? undefined : takeParsedBody(call.request);
-    const text = await bodyTextOf(call.request.clone()).catch(() => '');
+    // a screen's body the core does not read (an upload's bytes) is left to its handler, unread (DerivedCall.streamed)
+    const opaque = call.streamed === true && !coreReadsBody(call.request.headers.get('content-type'));
+    const parsed = payload || opaque ? undefined : takeParsedBody(call.request);
+    const text = opaque ? '' : await bodyTextOf(call.request.clone()).catch(() => '');
     let body = parsed?.value;
     if (!parsed) {
         if (payload)
@@ -1336,7 +1366,7 @@ export async function contextFor(m, call, scope) {
         rawResources.set(row, name ?? resource);
         return row;
     };
-    return {
+    const context = {
         call,
         params,
         id: Object.values(call.params).at(-1),
@@ -1355,7 +1385,6 @@ export async function contextFor(m, call, scope) {
             return { store: new GitObjectStore(getActiveBlobStore(), `${plane}/repos/${name}`), refs: new GitRefs(getActiveWorldStore(), `${plane}/repos/${name}`) };
         },
         mail: (route, mail, headers) => sendMail(route, mail, headers),
-        actor: m.identity ? m.identity(call.request.headers.get('authorization'), root) : undefined,
         now: () => now(m, at),
         render: (row, resource) => {
             const raw = rawResources.has(row);
@@ -1396,11 +1425,17 @@ export async function contextFor(m, call, scope) {
         record: async (type, fields, id, operation) => {
             if (!type.startsWith('_'))
                 throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
+            // a bookkeeping subject a resource counts (`counts` naming it: sentry's issue users) keeps that count as any
+            // child does, the parent it left recounted too
+            const keeps = counted(m, type);
             if (id !== undefined) {
                 const before = operation ? stateBeforeWrite(m, type, id, root) : undefined;
-                const { result } = await applyTwinWrite(m.service, { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } }, root);
+                const prior = keeps ? resourcesOfType(m.service, type, root).find((r) => r.id === id) : undefined;
+                const { resource: row, result } = await applyTwinWrite(m.service, { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } }, root);
                 if (operation)
                     observeStateWrite(m, result, before, root, stateChecks);
+                if (keeps)
+                    await keepCounts(m, call, type, row, params, root, at, prior && { ...prior });
                 return id;
             }
             const { value, result } = await applyTwinWriteAtomic(m.service, (resources) => {
@@ -1421,6 +1456,9 @@ export async function contextFor(m, call, scope) {
             }, root, () => resourcesOfType(m.service, type, root));
             if (operation && result)
                 observeStateWrite(m, result, undefined, root, stateChecks);
+            const made = keeps && value !== undefined ? resourcesOfType(m.service, type, root).find((r) => r.id === value) : undefined;
+            if (made)
+                await keepCounts(m, call, type, made, params, root, at);
             return value;
         },
         get machines() {
@@ -1433,7 +1471,9 @@ export async function contextFor(m, call, scope) {
             const id = mintId(m, resource, root, at, snapshot);
             return { id, fields: typeof fields === 'function' ? fields(id) : fields };
         }, operation, params, root, at, undefined, stateChecks).then((row) => row),
-        createUnique: async (resource, fields, operation) => {
+        createUnique: async (resource, fields, operation, options) => {
+            if (options?.input === 'omit' && !resource.startsWith('_'))
+                throw new Error('only bookkeeping writes may omit request input');
             const rules = m.resources[resource]?.unique;
             if (!rules?.length)
                 throw new Error('createUnique requires declared unique keys');
@@ -1447,16 +1487,20 @@ export async function contextFor(m, call, scope) {
                     return undefined;
                 }
                 return { id, fields: selected };
-            }, operation, params, root, at, undefined, stateChecks);
+            }, operation, params, root, at, undefined, stateChecks, options?.input === 'omit');
             return existing ? { created: false, row: existing } : { created: true, row: row };
         },
-        change: (resource, id, decide, operation) => atomicWrite(m, call, resource, (snapshot) => {
-            const row = snapshot.find((r) => r.type === storedType(m, resource) && r.id === id && r.deleted !== true);
-            if (!row)
-                return undefined;
-            const fields = decide(row);
-            return fields === undefined ? undefined : { id, fields };
-        }, operation, params, root, at, id, stateChecks),
+        change: (resource, id, decide, operation, options) => {
+            if (options?.input === 'omit' && !resource.startsWith('_'))
+                throw new Error('only bookkeeping writes may omit request input');
+            return atomicWrite(m, call, resource, (snapshot) => {
+                const row = snapshot.find((r) => r.type === storedType(m, resource) && r.id === id && r.deleted !== true);
+                if (!row)
+                    return undefined;
+                const fields = decide(row);
+                return fields === undefined ? undefined : { id, fields };
+            }, operation, params, root, at, id, stateChecks, options?.input === 'omit');
+        },
         write: (resource, id, fields, operation) => write(m, call, resource, id, fields, operation, params, root, at, stateChecks),
         accumulate: async (resource, id, deltas, operation) => {
             if (!resource.startsWith('_') || !m.resources[resource])
@@ -1542,8 +1586,11 @@ export async function contextFor(m, call, scope) {
         live: liveAccess({ rows: (type) => resourcesOfType(m.service, type, root), blob: (key) => readResourceBlob(m.service, key, root) }, call.request),
         blobs: {
             put: (key, bytes) => writeResourceBlob(m.service, key, bytes, root),
+            putStream: (key, body, accept) => writeResourceBlobStream(m.service, key, body, accept, root),
             get: (key) => readResourceBlob(m.service, key, root),
             remove: (key) => removeResourceBlob(m.service, key, root),
+            size: (key) => resourceBlobSize(m.service, key, root),
+            range: (key, start, endInclusive) => readResourceBlobRange(m.service, key, start, endInclusive, root),
         },
         merge: (resource, prior, next) => mergeField(m.resources[resource]?.update, prior, next),
         conflict: (resource, fields, except) => {
@@ -1563,12 +1610,240 @@ export async function contextFor(m, call, scope) {
         over: (other) => contextFor(other, { ...asAsked, request: asAsked.request.clone() }, { ...scope, clock: () => at }),
         core: async () => { const out = await serveCore(m, { ...call, request: pristine.clone() }, { ...scope, clock: () => at }); return 'served' in out ? out.served : undefined; },
         own: (row) => ownFields(row),
+        batch: (fn) => fn(),
+    };
+    if (batchable(m, root))
+        bindBatch(m, call, context, params, root, at, rawRow);
+    return context;
+}
+/**
+ * Whether a call's writes may be grouped (`ctx.batch`) with nothing about them changing: every effect a write has
+ * besides its action and the tree (write hooks, events, sockets, a parent's counts, a state observer, a head that
+ * performs it, an alias a read resolves through) is one the grouped path would move, so where any is present the
+ * writes land one at a time, as they always have.
+ */
+function batchable(m, root) {
+    return !m.onWrite && !m.events && !m.sockets?.length && !transitionObserver
+        && !Object.values(m.resources).some((decl) => decl.counts && Object.keys(decl.counts).length > 0)
+        && !performsAtHeadNow(m.service, root) && subjectAliases(m.service, root).size === 0;
+}
+/** The members of a context that read the tree other than `row`/`rowsRaw`: refused while writes are staged. */
+const BATCH_REFUSED_READS = ['get', 'rows', 'tree', 'history', 'find', 'list', 'expand', 'mint', 'conflict', 'ownerRow', 'render'];
+/** The members that write, or wait on writes, or answer as another context: each lands the staged writes first. */
+const BATCH_LANDING_MEMBERS = ['create', 'createUnique', 'change', 'accumulate', 'writeDetailed', 'record', 'atomically', 'remove', 'issue', 'at', 'over', 'core', 'awaitWrite', 'awaitCondition',
+    // a World's seed and signing keys are written when first asked (worldSeed, worldSigningKey, as a vendor's move)
+    'secret', 'signingKey'];
+/** `ctx.batch` over a context whose writes may be grouped (see `batchable`). */
+function bindBatch(m, call, context, params, root, at, rawRow) {
+    let staged;
+    // each staged subject as it will stand, by `type:id`, in the order first written
+    const subjects = new Map();
+    const land = async () => {
+        if (!staged?.length)
+            return;
+        const writes = staged;
+        staged = [];
+        subjects.clear();
+        await writeGroup(m, call, writes, params, root, at);
     };
+    const ctx = context;
+    for (const name of BATCH_LANDING_MEMBERS) {
+        const plain = ctx[name];
+        if (typeof plain !== 'function')
+            continue;
+        ctx[name] = async (...args) => { await land(); return plain(...args); };
+    }
+    for (const name of BATCH_REFUSED_READS) {
+        const plain = ctx[name];
+        if (typeof plain !== 'function')
+            continue;
+        ctx[name] = (...args) => {
+            if (staged?.length)
+                throw new Error(`ctx.${name} reads the tree while ctx.batch holds staged writes: only row and rowsRaw see them`);
+            return plain(...args);
+        };
+    }
+    const plainWrite = context.write, plainRow = context.row, plainRowsRaw = context.rowsRaw;
+    context.write = async (resource, id, fields, operation) => {
+        // a vendor's own move (ctx.asVendor) is the clock's write, recorded as the system's: it lands alone, in its place
+        if (!staged || inVendorMove()) {
+            await land();
+            return plainWrite(resource, id, fields, operation);
+        }
+        const type = storedType(m, resource), key = `${type}:${id}`;
+        // the one subject, as the memoized tree holds it (readTreeMap would copy the whole tree on every staged write)
+        const subject = foldLocalWrite(subjects.get(key) ?? heldSubject(m.service, type, id, root), type, id, fields, at);
+        subjects.set(key, subject);
+        staged.push({ resource, id, fields, operation });
+        return view(m, resource, treeResources(new Map([[key, subject]]))[0]);
+    };
+    // the stored rows of a resource's type with the staged subjects folded over them, filtered as `stored` filters
+    const overlaid = (resource, opts) => {
+        if (!staged?.length)
+            return undefined;
+        const type = storedType(m, resource), prefix = `${type}:`;
+        const mine = [...subjects].filter(([key]) => key.startsWith(prefix));
+        if (!mine.length)
+            return undefined;
+        const replaced = new Map(mine.map(([key, subject]) => [key, treeResources(new Map([[key, subject]]))[0]]));
+        const base = resourcesOfType(m.service, type, root);
+        // a subject the tree holds stays where it stands; one new to it goes to the end, in the order first written
+        const rows = base.map((row) => replaced.get(`${prefix}${row.id}`) ?? row);
+        const held = new Set(base.map((row) => `${prefix}${row.id}`));
+        for (const [key, row] of replaced)
+            if (!held.has(key))
+                rows.push(row);
+        const when = Object.entries(m.resources[resource]?.readableWhen ?? {});
+        return rows.filter((r) => (opts?.withDeleted || r.deleted !== true) && when.every(([k, v]) => r[k] === v));
+    };
+    context.row = (resource, id, opts) => {
+        const rows = overlaid(resource, opts);
+        if (!rows)
+            return plainRow(resource, id, opts);
+        const row = rows.find((r) => r.id === id);
+        return row ? rawRow(resource, row) : undefined;
+    };
+    context.rowsRaw = (resource, opts) => {
+        const rows = overlaid(resource, opts);
+        return rows ? rows.map((row) => rawRow(resource, row)) : plainRowsRaw(resource, opts);
+    };
+    context.batch = async (fn) => {
+        // a batch inside a batch is the outer one's
+        if (staged !== undefined)
+            return fn();
+        staged = [];
+        try {
+            return await fn();
+        }
+        finally {
+            // every write `write` answered lands, whether fn returned or threw: an ordered insert's prefix stays written
+            try {
+                await land();
+            }
+            finally {
+                staged = undefined;
+                subjects.clear();
+            }
+        }
+    };
+}
+/**
+ * A command's staged writes landed as one group: each recorded with the request as `writeDetailed` records it (one
+ * recordedInput, the same for every write of the call), the call's moment and actor, in order, under one lock and one
+ * append (serve.ts applyTwinWrites); then a held read on each written type is told, as each write tells it.
+ */
+async function writeGroup(m, call, writes, params, root, occurredAt) {
+    const input = recordedInput(m, call, params);
+    const files = input.operationId ? await keptFiles(m, call, root) : undefined;
+    const recorded = files ? { ...input, files } : input;
+    const actor = { kind: 'agent', ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) };
+    await applyTwinWrites(m.service, writes.map((write) => ({ operation: write.operation, subjectType: storedType(m, write.resource),
+        subjectId: write.id, fields: write.fields, input: recorded, occurredAt, actor })), root);
+    for (const type of new Set(writes.map((write) => storedType(m, write.resource))))
+        heldReadsWrite(m.service, root, type);
 }
 /** A pack's semantics handlers as the dispatch's handlers. */
 export function bindSemantics(m, handlers, scope = {}) {
     prepareViewOmissions(m);
-    return Object.fromEntries(Object.entries(handlers).map(([id, h]) => [id, async (call) => h(await contextFor(m, call, scope))]));
+    return Object.fromEntries(Object.entries(handlers).map(([id, h]) => [id, async (call) => {
+            const ctx = await contextFor(m, call, scope);
+            redisServiceTimes.lap('6c the handler\'s own context opened');
+            // an operation's own variants, else the ones every operation shares (`'*'`)
+            const variants = m.variants?.[id] ?? m.variants?.['*'];
+            if (variants && variantAsked(ctx.params, variants, call.request.headers))
+                return variantGap(m, call.request);
+            const outside = enumRefused(m, call, ctx.params);
+            return outside ?? h(ctx);
+        }]));
+}
+/** The first of a request's form parameters whose value is not one its spec lists (DerivedOperation.enums), with the
+ *  bracket name a form gives it (`spending_controls[spending_limits][0][interval]`) and the values it takes. */
+export function valueOutside(params, enums) {
+    const at = (value, path, name, values) => {
+        if (value === undefined || value === null)
+            return undefined;
+        if (!path.length)
+            return typeof value === 'object' || values.includes(String(value)) ? undefined : { param: name, values };
+        const [head, ...rest] = path;
+        if (head === '[]') {
+            const items = Array.isArray(value) ? value.map((v, i) => [String(i), v]) : value && typeof value === 'object' ? Object.entries(value) : [];
+            for (const [i, v] of items) {
+                const found = at(v, rest, `${name}[${i}]`, values);
+                if (found)
+                    return found;
+            }
+            return undefined;
+        }
+        return value && typeof value === 'object' && !Array.isArray(value) ? at(value[head], rest, `${name}[${head}]`, values) : undefined;
+    };
+    for (const [path, values] of Object.entries(enums)) {
+        const [first, ...rest] = path.split('.');
+        const found = at(params[first], rest, first, values);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** The manifest's refusal of a form value outside the operation's spec lists (and the values documented beside
+ *  them), unless the request names an API version other than the one the spec is. */
+function enumRefused(m, call, params) {
+    const refusal = m.body.form?.enumRefusal;
+    if (!refusal || !call.operation.enums)
+        return undefined;
+    const pinned = refusal.version ? call.request.headers.get(refusal.version.header) : null;
+    if (pinned && pinned !== refusal.version.served)
+        return undefined;
+    const documented = refusal.documented?.[call.operation.id] ?? {};
+    const enums = Object.fromEntries(Object.entries(call.operation.enums).map(([path, values]) => [path, [...values, ...(documented[path] ?? [])]]));
+    const outside = valueOutside(params, enums);
+    if (!outside)
+        return undefined;
+    const { documented: _d, version: _v, ...error } = refusal;
+    return vendorError(m, { ...error, param: outside.param, message: error.message.replace(/\{param\}/g, outside.param).replace(/\{values\}/g, oneOfList(outside.values)) });
+}
+/** A list of values as a sentence names them: `a, b, or c`. */
+const oneOfList = (values) => (values.length < 2 ? values.join('') : `${values.slice(0, -1).join(', ')}, or ${values[values.length - 1]}`);
+/** Whether a request's parameters ask one of the operation's undemanded variants (DerivedManifest.variants). */
+export function variantAsked(params, variants, headers) {
+    const valuesAt = (value, path) => {
+        if (!path.length)
+            return value === undefined ? [] : [value];
+        const [head, ...rest] = path;
+        // `!name` is the field left out: the value itself where it has none (`items[].!id`, an item naming no id)
+        if (head.startsWith('!'))
+            return value && typeof value === 'object' && value[head.slice(1)] === undefined ? [value] : [];
+        const list = head.endsWith('[]');
+        const key = list ? head.slice(0, -2) : head;
+        const next = value && typeof value === 'object' ? value[key] : undefined;
+        if (!list)
+            return valuesAt(next, rest);
+        const items = Array.isArray(next) ? next : next && typeof next === 'object' ? Object.values(next) : [];
+        return items.flatMap((item) => valuesAt(item, rest));
+    };
+    // a variant joined with `&` is its parts asked together (`trial_end=now&items`): the combination, not either alone;
+    // a part led by `!` is a parameter left out (`items[].price&!items[].id`, an item added rather than changed)
+    return variants.some((variant) => variant.split('&').every((part) => {
+        const absent = part.startsWith('!');
+        // `name~=value` is one entry of a comma-separated value (`tweet.fields~=geo`, X's fields lists); `name=value` the whole
+        const body = absent ? part.slice(1) : part;
+        const listed = body.includes('~=');
+        const [path, wanted] = listed ? body.split('~=') : body.split('=');
+        // a part led by `@` names a request header (`@stripe-account&application_fee_amount`, a charge made on a connected
+        // account with the platform's fee)
+        const header = path.startsWith('@') ? headers?.get(path.slice(1)) : undefined;
+        // a parameter whose own name holds a dot (X's `tweet.fields`) is read by that name before the path is walked
+        const found = path.startsWith('@') ? (header === null || header === undefined ? [] : [header])
+            : Object.hasOwn(params, path) ? (params[path] === undefined ? [] : [params[path]]) : valuesAt(params, path.split('.'));
+        const asked = wanted === undefined ? found.length > 0
+            : found.some((value) => (listed ? String(value).split(',').map((entry) => entry.trim()).includes(wanted) : String(value) === wanted));
+        return absent ? !asked : asked;
+    }));
+}
+/** The manifest's gap, as a variant is answered: the unknown-request refusal (else its not-found). */
+function variantGap(m, request) {
+    const nf = m.notFound;
+    const gap = m.gap ?? { status: nf.status, message: nf.message, ...(nf.code !== undefined ? { code: nf.code } : {}), ...(nf.kind !== undefined ? { kind: nf.kind } : {}) };
+    return vendorError(m, { ...gap, message: gap.message.replace(/\{method\}/g, request.method).replace(/\{path\}/g, new URL(request.url).pathname) });
 }
 /** The derived core as the dispatch's core: it owns every operation on a resource the manifest declares. */
 export function coreFor(m, scope = {}) {