@volter/world-core 3.0.156 → 3.0.158

package/dist/src/derived-core.d.ts

@@ -68,6 +68,8 @@ export type Transition = {
 export type StateField = {
     initial: string | boolean;
     transitions: Transition[];
+    /** Plain updates may repeat the current representation without another state move. */
+    unchanged?: 'allow';
     derive?: Array<{
         state: string;
         when: {
@@ -139,6 +141,8 @@ export type ResourceDecl = {
         resource: string;
         allowDeleted?: boolean;
         where?: Record<string, string>;
+        /** Global subject paths omit the collection's parent labels; tenancy still applies. */
+        whenNamed?: true;
         /** private fields a child observed under its parent keeps from the parent's parameters (`_jurisdiction:
          *  '{jurisdiction}'`), where the child's own read names none and a later read under it needs one ("Refresh") */
         keep?: Record<string, string>;
@@ -215,7 +219,9 @@ export type ResourceDecl = {
      *  holds this one's id (or vendor `parentKey`), only those with `present` set or `absent` unset when named and without
      *  any matching `unless` field, plus `plus` (a customer's
      *  `next_invoice_sequence` is one past its numbered invoices). `by` may be a dot path; exact field names take
-     *  precedence. The kernel keeps each whenever a child is written. */
+     *  precedence. The kernel keeps each whenever a child is written, the parent it left too when the write moves it; `of`
+     *  may name a bookkeeping type no resource declares, written with `ctx.record`. A count is kept by the lane that
+     *  declares it: a child another lane writes is not counted there. */
     counts?: Record<string, {
         of: string;
         by: string;
@@ -261,6 +267,10 @@ export type ResourceDecl = {
     } | {
         get: string;
         known?: true;
+        gone?: {
+            status: number;
+            says: string;
+        };
     }) & {
         params?: Record<string, string>;
         headers?: Record<string, string>;
@@ -376,6 +386,17 @@ export type ErrorSpec = {
     param?: string;
     kind?: string;
 };
+/** How a form value outside its spec's list is refused (DerivedOperation.enums): the error, its message filled with
+ *  `{param}` (the bracket name) and `{values}` (the values it takes); `documented`, values the vendor documents outside
+ *  its spec, by operation and path; `version`, the header naming the API version a request is made at and the version
+ *  the spec is, so a request pinned to another version, whose lists the pack does not hold, is not checked. */
+export type EnumRefusal = ErrorSpec & {
+    documented?: Record<string, Record<string, string[]>>;
+    version?: {
+        header: string;
+        served: string;
+    };
+};
 /** A vendor screen a World serves (docs/contributing/architecture.md, "Screens"). A `flow` is a hosted
  *  page an application sends its user through, held to its documented round trip; a `workspace` is a
  *  screen people work in. `demand` says who reaches it; `controls` names what a person acts on, the
@@ -401,6 +422,14 @@ export type ScreenDecl = {
      *  takes, with its demand (an upload bucket a page posts a lease's form to: Reddit's S3 hosts) (architecture, "A page
      *  at a World's place") */
     takes?: ReadonlyArray<'POST'>;
+    /** a workspace page that shows one record: the stored type and the path parameter its id fills (a pull request's
+     *  page, `{number}`); `?show=<type>:<id>` asked of the pack's workspaces opens it (architecture, "Workspace") */
+    shows?: {
+        type: string;
+        param: string;
+    };
+    /** the stored types a workspace page lists, where `?show=` lands for a record no page shows by itself */
+    lists?: ReadonlyArray<string>;
     /** the vendor's documentation of the round trip or the screen */
     source: string;
 };
@@ -443,6 +472,7 @@ export type DerivedManifest = {
     body: {
         form?: {
             coerce: boolean;
+            enumRefusal?: EnumRefusal;
         };
         json?: 'always';
         validation?: {
@@ -458,6 +488,7 @@ export type DerivedManifest = {
             unknown: string;
             type: string;
             range: string;
+            arrays?: Record<string, 'string'>;
         };
     };
     /** `acceptProvided`: a create that names its own `id` keeps it (a vendor that seeds by id). The template counts
@@ -469,6 +500,13 @@ export type DerivedManifest = {
     };
     /** operations the derived core must not claim though their resource is declared: a gap until someone models them */
     unmodeled?: string[];
+    /** documented variants of a served operation that no demand asks for, by operation: each a parameter present
+     *  (`pause_collection`), present on any item of a list (`items[].price_data`), or with a value
+     *  (`payment_method_data.type=sepa_debit`, `payment_method_types[]=sepa_debit`), or holding one entry of a comma-separated
+     *  value (`tweet.fields~=geo`; a parameter whose name holds a dot is read by that name). A request asking one is answered the
+     *  manifest's gap before its handler runs, as an operation no handler serves is (architecture, "Creating a pack",
+     *  step 7), so no pack line answers it */
+    variants?: Record<string, string[]>;
     /** operations that only read though nothing in the spec says so (a POST that returns data):
      *  a read-only twin answers them */
     reads?: string[];
@@ -506,6 +544,9 @@ export type DerivedManifest = {
     readOnly: ErrorSpec;
     /** what a body labelled JSON that does not parse answers; absent, a 400 in the vendor's error body */
     malformedBody?: ErrorSpec;
+    /** the vendor's front merges repeated slashes in a path before it routes (nginx's default `merge_slashes`): a request
+     *  to `//r/x//about` is `/r/x/about`, merged on arrival before a door, a screen or an operation is matched */
+    mergeSlashes?: boolean;
     /** a request header that selects the vendor's API version, and the answer to a malformed one
      *  (`{value}` in its message is the header's value) */
     version?: {
@@ -702,7 +743,13 @@ export type DerivedManifest = {
         method: string;
         path: string;
         note?: string;
+        redactBody?: string[];
     }>;
+    /** REST refresh binds observed tenant metadata through the root account identity endpoint. */
+    refreshIdentity?: {
+        operation: string;
+        field: string;
+    };
     /** The vendor's GraphQL API beside its REST one (`semantics/graphql.ts` over `generated/graphql-sdl.gen.json`): the
      *  paths it is POSTed to, and the answer to a query selecting a field nothing models (`{field}`, `{type}`). */
     graphql?: {
@@ -939,8 +986,6 @@ export type SemanticsContext = {
     /** A mail the vendor sends a person, over SMTP to the route its settings name (smtp.ts), under the World's egress rule;
      *  throws when it cannot be delivered. */
     mail(route: SmtpRoute, mail: Mail, headers?: Record<string, string>): Promise<void>;
-    /** who is calling, when the manifest says how to tell */
-    actor: string | undefined;
     now(): unknown;
     /** Render a stored row or vendor view using its resource declaration, retaining the stored subject id fallback. */
     render(row: Record<string, unknown>, resource?: string): Record<string, unknown>;
@@ -985,12 +1030,16 @@ export type SemanticsContext = {
     /** Allocate a stored occurrence and append its fields under one action lock. The optional field factory is pure. */
     create(resource: string, fields: Record<string, unknown> | ((id: string) => Record<string, unknown>), operation: string): Promise<Record<string, unknown>>;
     /** Create under declared unique keys and the action lock; a collision returns the existing own-field view without a write. */
-    createUnique(resource: string, fields: Record<string, unknown> | ((id: string) => Record<string, unknown>), operation: string): Promise<{
+    createUnique(resource: string, fields: Record<string, unknown> | ((id: string) => Record<string, unknown>), operation: string, options?: {
+        input: 'omit';
+    }): Promise<{
         created: boolean;
         row: Record<string, unknown>;
     }>;
     /** Decide an update from the current live stored row under the action lock; undefined leaves it unchanged. */
-    change(resource: string, id: string, decide: (row: Record<string, unknown>) => Record<string, unknown> | undefined, operation: string): Promise<Record<string, unknown> | undefined>;
+    change(resource: string, id: string, decide: (row: Record<string, unknown>) => Record<string, unknown> | undefined, operation: string, options?: {
+        input: 'omit';
+    }): Promise<Record<string, unknown> | undefined>;
     write(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<Record<string, unknown>>;
     /**
      * One command's writes as one group (S2 R17; docs/contributing/architecture.md, "A command's writes as one group").
@@ -1126,6 +1175,16 @@ export type SemanticsContext = {
         put(key: string, bytes: Uint8Array): Promise<void>;
         get(key: string): Promise<Uint8Array | null>;
         remove(key: string): Promise<void>;
+        /** a body written as it arrives (a request's own stream), kept only when `accept` holds for its size and SHA-256:
+         *  an upload of a large object never held whole. True when kept */
+        putStream(key: string, body: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, accept: (written: {
+            size: number;
+            sha256: string;
+        }) => boolean): Promise<boolean>;
+        /** a blob's length, or null when there is none: a large object is answered without loading it */
+        size(key: string): Promise<number | null>;
+        /** the bytes `start`..`endInclusive` of a blob (a ranged read where the store has one), or null when there is none */
+        range(key: string, start: number, endInclusive: number): Promise<Uint8Array | null>;
     };
     /** A body's fields checked against the operation's declared ones under the manifest's `body.strict`: the fields, or
      *  the vendor's refusal of the first that is unknown, of another type or out of its bounds. */
@@ -1155,10 +1214,17 @@ export type HandlerContext = Omit<SemanticsContext, 'now' | 'core' | 'atomically
 export type WriteHookContext = Omit<HandlerContext, 'write' | 'batch' | 'create' | 'createUnique' | 'change' | 'issue' | 'record' | 'accumulate' | 'at' | 'over'>;
 /** A derived pack's handler: one operation, by its operationId, over the contract's context. */
 export type Handler = (ctx: HandlerContext) => Promise<Response>;
-/** The context the kernel opens for a call (a handler's, a door's, a screen's). Kernel-internal: packs are given it. */
 export declare function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext>;
 /** A pack's semantics handlers as the dispatch's handlers. */
 export declare function bindSemantics(m: DerivedManifest, handlers: Record<string, Semantics>, scope?: CoreScope): Record<string, DerivedHandler>;
+/** 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 declare function valueOutside(params: Record<string, unknown>, enums: Readonly<Record<string, ReadonlyArray<string>>>): {
+    param: string;
+    values: ReadonlyArray<string>;
+} | undefined;
+/** Whether a request's parameters ask one of the operation's undemanded variants (DerivedManifest.variants). */
+export declare function variantAsked(params: Record<string, unknown>, variants: readonly string[], headers?: Headers): boolean;
 /** The derived core as the dispatch's core: it owns every operation on a resource the manifest declares. */
 export declare function coreFor(m: DerivedManifest, scope?: CoreScope): {
     owns: (o: DerivedOperation) => boolean;

package/dist/src/derived-core.js

@@ -22,7 +22,7 @@ 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";
@@ -73,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))) {
@@ -303,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. */
@@ -692,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 ?? {} };
@@ -711,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) {
@@ -741,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
@@ -766,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;
@@ -1133,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);
@@ -1226,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) };
@@ -1286,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;
@@ -1295,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)
@@ -1359,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);
@@ -1400,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) => {
@@ -1425,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() {
@@ -1437,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');
@@ -1451,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])
@@ -1546,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) => {
@@ -1702,7 +1745,105 @@ async function writeGroup(m, call, writes, params, root, occurredAt) {
 /** 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) => { const ctx = await contextFor(m, call, scope); redisServiceTimes.lap('6c the handler\'s own context opened'); return h(ctx); }]));
+    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 = {}) {