@volter/world-core 3.0.156 → 3.0.157

package/src/derived-core.ts

@@ -25,7 +25,7 @@ import { askApplication, deliverEvents, type ApplicationAnswer, type Application
 import type { RateBudgetDeclaration } from './rateBudget.ts';
 import { handlerCrypto, hmac, ksuidFrom, lettersFrom, sha256, uuidFrom, type HandlerCrypto } from './signing.ts';
 import { hashFieldValue } from './hash.ts';
-import { readResourceBlob, removeResourceBlob, writeResourceBlob } from './resource-blob.ts';
+import { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, writeResourceBlob, writeResourceBlobStream } from './resource-blob.ts';
 import { managedDatabase, unboundDatabase, type ManagedDatabase } from './managed-database.ts';
 import { redisServiceTimes } from './redis/service-times.ts';
 import { execRedisRun, type RedisDialect, type RunItem } from './redis/engine.ts';
@@ -84,6 +84,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: { equals?: unknown; gt?: number; truthy?: boolean; absent?: boolean } }>;
   vendorInitial?: string;
 };
@@ -149,6 +151,8 @@ export type ResourceDecl = {
    *  fields when its stored id is not what the path names (a repository stored as `repo:7` with `owner`
    *  and `name`, addressed as `{owner}/{repo}`): each stored field against a template over the path. */
   parent?: { param?: string; params?: string[]; value?: string; field: string; 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> };
@@ -201,7 +205,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; parentKey?: string; present?: string; absent?: string; unless?: Record<string, unknown>; plus?: number }>;
   /** how the vendor's state of this type is read back into a root (the real-system adapters, "Refresh"): the list that
    *  enumerates it (once per parent, under `parent`; `complete: false` when it is not the whole type; `items`, the answer's
@@ -217,7 +223,7 @@ export type ResourceDecl = {
    *  jurisdictions). A blob read by an `operation` (a GET of the unit's surface, filled from the subject's fields and
    *  its parent's parameters) keeps the bytes in the World's blobs, their key in `field`, and in `headersField` the
    *  answer's headers `keepHeaders` names (a name ending `*` a prefix: `x-amz-meta-*`), both fields private. */
-  refresh?: ({ list: string; unpaginated?: true; keyed?: true; detail?: string; detailMerge?: string; detailWith?: Record<string, string>; complete?: false; items?: string; shape?: RefreshShape; next?: string | Record<string, string>; nextLink?: { header: string; rel: string; query: string; when?: Record<string, string> }; cursor?: string; more?: string } | { get: string; known?: true }) & { params?: Record<string, string>; headers?: Record<string, string>; variants?: ReadonlyArray<{ headers: Record<string, string> }>; blobs?: ReadonlyArray<{ path: string; key: string; resource?: string; fields?: Record<string, string> } | { operation: string; field: string; headers?: Record<string, string>; headersField?: string; keepHeaders?: string[] }>; query?: Record<string, string>; idAs?: string; graphql?: { query: string; variables?: Record<string, unknown>; items: string; pageInfo?: string; cursor?: string } } | { none: string };
+  refresh?: ({ list: string; unpaginated?: true; keyed?: true; detail?: string; detailMerge?: string; detailWith?: Record<string, string>; complete?: false; items?: string; shape?: RefreshShape; next?: string | Record<string, string>; nextLink?: { header: string; rel: string; query: string; when?: Record<string, string> }; cursor?: string; more?: string } | { get: string; known?: true; gone?: { status: number; says: string } }) & { params?: Record<string, string>; headers?: Record<string, string>; variants?: ReadonlyArray<{ headers: Record<string, string> }>; blobs?: ReadonlyArray<{ path: string; key: string; resource?: string; fields?: Record<string, string> } | { operation: string; field: string; headers?: Record<string, string>; headersField?: string; keepHeaders?: string[] }>; query?: Record<string, string>; idAs?: string; graphql?: { query: string; variables?: Record<string, unknown>; items: string; pageInfo?: string; cursor?: string } } | { none: string };
   /** the other resources one create of this one makes, and where its answer names each's id (a JSON path) */
   companions?: Record<string, string>;
   /** the field telling a newer copy of a subject from an older (an `updated_at`): an ingested event older than the
@@ -274,6 +280,11 @@ export type VendorManifest = { vendor: string; discovery?: DerivedManifest['disc
 
 /** `code` as the vendor writes it: a string, or a number (Discord's JSON error codes are integers) */
 export type ErrorSpec = { status: number; message: string; code?: string | number; 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
@@ -300,6 +311,11 @@ 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;
 };
@@ -335,13 +351,20 @@ export type DerivedManifest = {
   /** `strict`: a vendor that refuses a body field its operation does not declare, a value of another type, or a number
    *  outside the spec's bounds (a NestJS validation pipe: Supabase's "property x should not exist"), with its messages;
    *  `{name}`, `{type}` (`a string`, `an integer`), `{min}` and `{max}` are filled. `ctx.fields` checks a body so. */
-  body: { form?: { coerce: boolean }; json?: 'always'; validation?: { operations?: ReadonlyArray<string>; status: number; missing: unknown; type: unknown; range: unknown }; strict?: { status: number; code?: string; unknown: string; type: string; range: string } };
+  body: { form?: { coerce: boolean; enumRefusal?: EnumRefusal }; json?: 'always'; validation?: { operations?: ReadonlyArray<string>; status: number; missing: unknown; type: unknown; range: unknown }; strict?: { status: number; code?: string; 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
    *  (`{prefix}_{n}`), or is `{uuid}` for a vendor whose ids are UUIDs: the next is derived from the resource and its
    *  count, so a World mints the same ids every run */
   ids: { template: string; acceptProvided?: boolean };
   /** 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[];
@@ -370,6 +393,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?: { header: string; pattern: string; error: ErrorSpec };
@@ -475,7 +501,9 @@ export type DerivedManifest = {
   };
   /** The World's doors (architecture, "Doors, screens and the gap"): each a method and a path under `/_twin/` (with
    *  `{param}` segments), answered by the export of `semantics/doors.ts` its id names, over the contract's context. */
-  doors?: Array<{ id: string; method: string; path: string; note?: string }>;
+  doors?: Array<{ id: string; 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?: { paths: ReadonlyArray<string>; unmodeled: { message: string; type?: string; status?: number } };
@@ -568,12 +596,13 @@ export function strictFields(m: DerivedManifest, operation: DerivedOperation, bo
     const field = declared.get(name);
     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))) {
       return refuse(strict.range, { name, min: field.minimum ?? null, max: field.maximum ?? null });
@@ -779,12 +808,20 @@ function parentField(row: unknown, path: string): unknown {
   return value;
 }
 
-function missingParent(m: DerivedManifest, resource: string, call: DerivedCall, root?: string): Response | undefined {
-  const parent = m.resources[resource]?.parent;
+function parentOfCall(decl: ResourceDecl | undefined, call: DerivedCall): ResourceDecl['parent'] {
+  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: DerivedManifest, resource: string, call: DerivedCall, root?: string, tenant?: string): Response | undefined {
+  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))] as const);
-  const found = (r: TwinResource): boolean => (where.length ? where.every(([field, v]) => String(parentField(r, field)) === v) : r.id === id);
+  const found = (r: TwinResource): boolean => (where.length ? where.every(([field, v]) => String(parentField(r, field)) === v) : r.id === id)
+    && (!m.tenant || m.resources[parent.resource]?.shared || (r as Record<string, unknown>)[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));
 }
 
@@ -1168,7 +1205,11 @@ function recordedInput(m: DerivedManifest, call: DerivedCall, merged: Record<str
   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 ?? {}) as { query?: unknown; variables?: unknown; operationName?: unknown };
     return { ...activity, graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
@@ -1186,34 +1227,33 @@ const requestOfCall = new WeakMap<DerivedCall, Request>();
 
 async function writeDetailed(m: DerivedManifest, call: DerivedCall, resource: string, id: string, fields: Record<string, unknown>, operation: string, params: Record<string, unknown>, root: string | undefined, occurredAt: string, checks?: StateChecks): Promise<{ body: Record<string, unknown>; id: string; vendorData?: unknown }> {
   const before = stateBeforeWrite(m, resource, id, root);
+  const prior = counted(m, resource) ? stored(m, resource, root).find((r) => r.id === id) as Record<string, unknown> | undefined : undefined;
   const withFiles = async (input: Record<string, unknown>): Promise<Record<string, unknown>> => { 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) } : {}) } },
+      : { 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: DerivedManifest, call: DerivedCall, resource: string,
   decide: (snapshot: readonly TwinResource[]) => { id: string; fields: Record<string, unknown> } | undefined,
-  operation: string, params: Record<string, unknown>, root: string | undefined, occurredAt: string, unchangedId?: string, checks?: StateChecks,
+  operation: string, params: Record<string, unknown>, root: string | undefined, occurredAt: string, unchangedId?: string, checks?: StateChecks, omitInput = false,
 ): Promise<Record<string, unknown> | undefined> {
-  const input = recordedInput(m, call, params);
-  const files = input.operationId ? await keptFiles(m, call, root) : undefined;
+  const input = omitInput ? undefined : recordedInput(m, call, params);
+  const files = input?.operationId ? await keptFiles(m, call, root) : undefined;
   let before: TwinResource | undefined;
   const committed = await applyTwinWriteAtomic(m.service, (snapshot) => {
     const selected = decide(snapshot);
-    if (selected && transitionObserver) before = snapshot.find((r) => r.type === storedType(m, resource) && r.id === selected.id);
+    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' as const, ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) },
+      ...(input ? { input: files ? { ...input, files } : input } : {}), occurredAt, actor: { kind: 'agent' as const, ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) },
     } } : { kind: 'skip', value: undefined };
   }, root);
   if (!committed.result || !committed.value) {
@@ -1222,14 +1262,14 @@ async function atomicWrite(m: DerivedManifest, call: DerivedCall, resource: stri
   }
   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 as unknown as Record<string, unknown> | undefined)).body;
 }
 
 async function finishWrite(m: DerivedManifest, call: DerivedCall, resource: string, row: TwinResource,
   result: { externalId?: string; vendorData?: unknown }, operation: string, params: Record<string, unknown>,
-  root: string | undefined, occurredAt: string,
+  root: string | undefined, occurredAt: string, prior?: Record<string, unknown>,
 ): Promise<{ body: Record<string, unknown>; id: string; vendorData?: unknown }> {
-  await keepCounts(m, call, resource, row as unknown as Record<string, unknown>, params, root, occurredAt);
+  await keepCounts(m, call, resource, row as unknown as Record<string, unknown>, 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
@@ -1250,24 +1290,30 @@ async function finishWrite(m: DerivedManifest, call: DerivedCall, resource: stri
 
 /** 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: DerivedManifest, call: DerivedCall, resource: string, row: Record<string, unknown>, params: Record<string, unknown>, root: string | undefined, occurredAt: string): Promise<void> {
+async function keepCounts(m: DerivedManifest, call: DerivedCall, resource: string, row: Record<string, unknown>, params: Record<string, unknown>, root: string | undefined, occurredAt: string, prior?: Record<string, unknown>): Promise<void> {
   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) as Record<string, unknown> | undefined;
-      if (!held) continue;
-      const n = stored(m, c.of, root).filter((r) => {
-        const x = r as Record<string, unknown>;
-        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) as Record<string, unknown> | undefined;
+        if (!held) continue;
+        const n = stored(m, c.of, root).filter((r) => {
+          const x = r as Record<string, unknown>;
+          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: DerivedManifest, resource: string): boolean =>
+  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: DerivedManifest, op: DerivedOperation, body: Record<string, unknown>): Record<string, unknown> {
   return m.success && op.answers?.key ? { ...m.success, [op.answers.key]: body } : body;
@@ -1600,14 +1646,14 @@ export async function serveCore(m: DerivedManifest, call: DerivedCall, scope: Co
   // 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: TwinResource): boolean => (!parent || (r as Record<string, unknown>)[parent.field] === parentId)
     && (!tenantField || (r as Record<string, unknown>)[tenantField] === tenant);
   const paths = expandPaths(m, params);
@@ -1681,6 +1727,7 @@ export async function serveCore(m: DerivedManifest, call: DerivedCall, scope: Co
       for (const [field, sdecl] of Object.entries(decl.state ?? {})) {
         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) };
         if (!move) {
@@ -1768,8 +1815,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>;
@@ -1808,9 +1853,9 @@ 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<{ created: boolean; row: Record<string, unknown> }>;
+  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").
@@ -1909,7 +1954,16 @@ export type SemanticsContext = {
   parts(): Promise<MultipartPart[]>;
   /** The pack's resource blobs (an object's bytes), by key, on the World's branch: they branch with the World, and a
    *  read falls back to an ancestor's. The row that names a blob is the pack's; the bytes are here. */
-  blobs: { put(key: string, bytes: Uint8Array): Promise<void>; get(key: string): Promise<Uint8Array | null>; remove(key: string): Promise<void> };
+  blobs: {
+    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. */
   fields(body: Record<string, unknown>): { fields: Record<string, unknown> } | { refused: Response };
@@ -1937,6 +1991,12 @@ export type WriteHookContext = Omit<HandlerContext, 'write' | 'batch' | 'create'
 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. */
+/** 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: string | null): boolean => {
+  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: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext> {
   const root = scope.root;
   const asAsked = call;
@@ -1946,8 +2006,10 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
   // 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: unknown = parsed?.value;
   if (!parsed) { if (payload) body = text || undefined; else { try { body = text ? parseExactJson(text) : undefined; } catch { body = text; } } }
   // the request as it came, before the core's parameter merge and alias adoption: what a write records, so a perform
@@ -1996,7 +2058,6 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
       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);
@@ -2033,10 +2094,15 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     secret: async (label) => hmac(await worldSeed(m.service, root, at), label, 'base64url'),
     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 as unknown as Record<string, unknown>, params, root, at, prior && { ...prior } as Record<string, unknown>);
         return id;
       }
       const { value, result } = await applyTwinWriteAtomic(m.service, (resources) => {
@@ -2054,6 +2120,8 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
         return { kind: 'write', value: subject, write: { operation: operation ?? `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' } } };
       }, 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 as unknown as Record<string, unknown>, params, root, at);
       return value;
     },
     get machines() {
@@ -2066,7 +2134,8 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
       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');
       let existing: Record<string, unknown> | undefined;
@@ -2076,15 +2145,18 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
         const hit = snapshot.find((r) => r.type === storedType(m, resource) && r.deleted !== true && rules.some((rule) => rule.fields.every((f) => selected[f] !== undefined && view(m, resource, r)[f] === selected[f])));
         if (hit) { existing = view(m, resource, hit); 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) => {
+    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 as Record<string, unknown>);
       return fields === undefined ? undefined : { id, fields };
-    }, operation, params, root, at, id, stateChecks),
+    }, 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]) throw new Error('accumulate requires a declared bookkeeping resource');
@@ -2166,8 +2238,11 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     live: liveAccess({ rows: (type) => resourcesOfType(m.service, type, root) as unknown as Array<Record<string, unknown>>, 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) => {
@@ -2309,7 +2384,96 @@ async function writeGroup(m: DerivedManifest, call: DerivedCall, writes: readonl
 /** A pack's semantics handlers as the dispatch's handlers. */
 export function bindSemantics(m: DerivedManifest, handlers: Record<string, Semantics>, scope: CoreScope = {}): Record<string, DerivedHandler> {
   prepareViewOmissions(m);
-  return Object.fromEntries(Object.entries(handlers).map(([id, h]) => [id, async (call: DerivedCall) => { 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: DerivedCall) => {
+    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 as Record<string, unknown>, variants, call.request.headers)) return variantGap(m, call.request);
+    const outside = enumRefused(m, call, ctx.params as Record<string, unknown>);
+    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: Record<string, unknown>, enums: Readonly<Record<string, ReadonlyArray<string>>>): { param: string; values: ReadonlyArray<string> } | undefined {
+  const at = (value: unknown, path: string[], name: string, values: ReadonlyArray<string>): { param: string; values: ReadonlyArray<string> } | undefined => {
+    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] as const) : 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 as Record<string, unknown>)[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: DerivedManifest, call: DerivedCall, params: Record<string, unknown>): Response | undefined {
+  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: ReadonlyArray<string>): string => (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: Record<string, unknown>, variants: readonly string[], headers?: Headers): boolean {
+  const valuesAt = (value: unknown, path: string[]): unknown[] => {
+    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 as Record<string, unknown>)[head!.slice(1)] === undefined ? [value] : [];
+    const list = head!.endsWith('[]');
+    const key = list ? head!.slice(0, -2) : head!;
+    const next = value && typeof value === 'object' ? (value as Record<string, unknown>)[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: DerivedManifest, request: Request): Response {
+  const nf = m.notFound;
+  const gap: ErrorSpec = 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. */