@volter/world-core 2.0.0

package/src/derived-core.ts

@@ -0,0 +1,1004 @@
+// THE DERIVED CORE — what a derived pack does for an operation it declares no handler for
+// (docs/contributing/architecture.md, "Protocol 3"). The generated surface says what the
+// vendor's operations are; the pack's manifest says the vendor facts no spec carries (how ids look,
+// 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, type TwinResource } from './serve.ts';
+import { copyResource, ownFields, parentStamp, subjectHistory, treeChangesSince, treeStamp } from './log.ts';
+import { getActiveWorldStore } from './world-store.ts';
+import { worldNow } from './world-clock.ts';
+import { createHash } from 'node:crypto';
+import { hashFieldValue } from './hash.ts';
+import { resolveSubjectId, subjectAliases } from './actions.ts';
+import { packReferences } from './references.ts';
+import type { SubjectFields } from './hash.ts';
+import { twinPublicBase } from './twin-fetch.ts';
+import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.ts';
+
+// ── the manifest ─────────────────────────────────────────────────────────────────────────────
+
+/** How a stored field gets its value when the server assigns it. `now` is the world clock in the
+ *  manifest's time format; `id` the subject's id; a `value` is stored as given. */
+export type FieldRule = { now: true } | { id: true } | { value: unknown } | { template: string };
+
+/** A move of one state field, as data. `operation` is the operationId that causes it (an update
+ *  that requests `to` when absent); `from` the values it leaves; `effects` the other fields it writes;
+ *  `refusal` what the vendor answers when `from` does not hold. */
+/** Who moves a state: a caller of the API (the default), the person on a vendor's hosted page or
+ *  another outside party (`external`), the vendor on its own (`vendor`), or time (`time`). A move
+ *  that is not the API's never answers an API call's legality. */
+export type Actor = 'api' | 'external' | 'vendor' | 'time';
+
+export type Transition = {
+  operation?: string;
+  actor?: Actor;
+  from: string[] | '*';
+  /** the value it moves to; absent, the value stays (a guard that moves nothing) */
+  to?: string;
+  effects?: Record<string, FieldRule>;
+  /** placeholders `{from}`, `{to}`, `{field}`, `{id}` */
+  refusal?: { status: number; code?: string; message: string };
+  /** a refusal of its own for a particular current value (an invoice already `paid`) */
+  refusals?: Record<string, { status: number; code?: string; message: string }>;
+  /** where the rule comes from: a docs URL, the SDK's types, or a recording */
+  source: string;
+};
+
+/** A state field's machine. Values compare as strings, so a boolean field reads `'true'`/`'false'`, and
+ *  a field that is absent reads as `initial`. `derive` names states a stored value only implies (a
+ *  timestamp that is 0 until something happens), tried in order. `vendorInitial` is where the vendor
+ *  starts a subject when the twin starts it elsewhere. */
+export type StateField = {
+  initial: string | boolean;
+  transitions: Transition[];
+  derive?: Array<{ state: string; when: { equals?: unknown; gt?: number; truthy?: boolean; absent?: boolean } }>;
+  vendorInitial?: string;
+};
+
+/** What a move to `to` stores in the field: a boolean field's value is a boolean, and a derived field's
+ *  value is written by the move's effects (a state name is not a timestamp), so it stores nothing itself. */
+export function storedState(decl: StateField, to: string | undefined): unknown {
+  if (to === undefined || decl.derive?.length) return undefined;
+  return typeof decl.initial === 'boolean' ? to === 'true' : to;
+}
+
+/** The state a stored value is in, by the field's machine. */
+export function stateOf(decl: StateField, value: unknown): string {
+  for (const d of decl.derive ?? []) {
+    const w = d.when;
+    if (w.absent !== undefined && (value === undefined || value === null) === w.absent) return d.state;
+    if (w.equals !== undefined && value === w.equals) return d.state;
+    if (w.gt !== undefined && typeof value === 'number' && value > w.gt) return d.state;
+    if (w.truthy !== undefined && Boolean(value) === w.truthy) return d.state;
+  }
+  return value === undefined || value === null ? String(decl.initial) : String(value);
+}
+
+export type ResourceDecl = {
+  /** the tree's subject type, when it differs from the resource name */
+  storedAs?: string;
+  idPrefix: string;
+  /** fields the server assigns on create */
+  assigned?: Record<string, FieldRule>;
+  state?: Record<string, StateField>;
+  /** state candidates the manifest rules are not state */
+  notState?: string[];
+  /** id-holding fields a caller may ask to receive embedded, and the resource each holds */
+  embeds?: Record<string, string>;
+  /** this resource's deletion answer, when it is not the manifest's (`vector_store.deleted`) */
+  deleted?: unknown;
+  /** a child addressed under its parent: the path parameter naming the parent, the stored field that
+   *  holds it, and the parent resource, whose not-found answers a missing parent */
+  /** `param` is the path parameter naming the parent, or `params` several with `value` the template
+   *  that joins them into what `field` stores (`{owner}/{repo}`). `where` finds the parent by its stored
+   *  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> };
+  /** a number the resource counts per parent (a repository's issue numbers, a thread's messages):
+   *  the stored field, set on create to one past the highest among its siblings */
+  number?: { field: string };
+  /** how this resource renders a stored subject, when it differs from the pack's; it sees the subject's
+   *  address, which a stored shape may not carry */
+  view?: (body: Record<string, unknown>, subject: { id: string; type: string }) => Record<string, unknown>;
+  /** an update replaces the fields it names (`replace`) or merges nested objects into them (`merge`, the default) */
+  update?: 'merge' | 'replace';
+  /** the stored subject id when it is not the path's last parameter: a template over the path
+   *  parameters (`{vector_store_id}::{file_id}`) */
+  key?: string;
+  /** only subjects whose stored fields match are readable (a resource stored for every call but
+   *  answered only when asked to be kept) */
+  readableWhen?: Record<string, unknown>;
+  /** this resource's not-found answer when it is not the manifest's: a message (`{id}`), or an
+   *  error code (an RPC vendor's `channel_not_found`) */
+  notFound?: string | { code: string; message?: string };
+  /** query parameters of the list operation that filter on the same-named field */
+  filters?: string[];
+  order?: { field: string; direction: 'asc' | 'desc' };
+};
+
+export type ErrorSpec = { status: number; message: string; code?: string; param?: string; kind?: 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
+ *  vendor's way, each a (screen, control) cell. */
+export type ScreenDecl = {
+  id: string;
+  kind: 'flow' | 'workspace';
+  host: string;
+  path: string;
+  demand: string;
+  status: 'done' | 'todo';
+  controls?: string[];
+  /** the vendor's documentation of the round trip or the screen */
+  source: string;
+};
+
+export type DerivedManifest = {
+  vendor: string;
+  /** the kernel service the pack writes */
+  service: string;
+  /** `json: 'always'` reads a body as JSON whatever its content type (GitHub does) */
+  body: { form?: { coerce: boolean }; json?: 'always' };
+  /** `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: served by
+   *  the pack's existing code, or a gap, until someone models them */
+  unmodeled?: 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[];
+  time: 'unix' | 'iso';
+  /** the vendor's error body, with `{message}`, `{code}`, `{param}`, `{kind}` placeholders; a
+   *  placeholder with no value is left out when `errorOmitsAbsent` */
+  error: unknown;
+  errorOmitsAbsent?: boolean;
+  /** the `{kind}` an error takes when it names none */
+  defaultKind?: string;
+  /** what a write to a read-only twin answers */
+  readOnly: ErrorSpec;
+  /** what a body labelled JSON that does not parse answers; absent, a 400 in the vendor's error body */
+  malformedBody?: ErrorSpec;
+  /** 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 };
+  /** `withParam`: the error names the path parameter that held the unknown id */
+  notFound: { status: number; message: string; code?: string; kind?: string; withParam?: boolean };
+  /** the list envelope (placeholders `{data}`, `{has_more}`, `{url}`, `{first_id}`, `{last_id}`),
+   *  its page size, its cursors, and where an unknown cursor starts: the first page or past the end */
+  list: {
+    style: 'envelope';
+    envelope: unknown;
+    limit: { param: string; default: number; max: number };
+    after?: string;
+    before?: string;
+    unknownCursor?: 'start' | 'end';
+    /** an opaque cursor over positions (`{next_cursor}` in the envelope; empty on the last page),
+     *  in place of id cursors: `base64-offset` is base64 of `{"o":<offset>}` */
+    cursor?: { param: string; encoding: 'base64-offset' };
+    /** numbered pages (1-based `page`, the size in `limit.param`), with the vendor's `Link` header
+     *  naming the first, previous, next and last pages */
+    page?: { param: string; link: boolean };
+    /** offset paging: `param` names how many items to skip; the page sits under the operation's envelope key beside the
+     *  envelope, whose `{total_count}` is the count before paging (Tremendous's `{ orders: [...], total_count }`) */
+    offset?: { param: string };
+    /** page sizes by operationId, where a vendor's lists differ from `limit` (Tremendous: orders 10/500, invoices 10/10) */
+    limits?: Record<string, { default: number; max: number }>;
+    /** envelopes by operationId, where a vendor's lists differ from `envelope` (Tremendous gives `total_count` on orders,
+     *  rewards and invoices, and none on campaigns, funding sources or webhooks) */
+    envelopes?: Record<string, unknown>;
+  };
+  /** an RPC vendor's success envelope, merged into every answer, with the resource under the
+   *  operation's envelope key (`{ ok: true, channel: {...} }`) */
+  success?: Record<string, unknown>;
+  /** who is calling, from the request's credential (and the tree, where the vendor keeps tokens) */
+  identity?: (authorization: string | null, root?: string) => string;
+  deleted: unknown;
+  expandParam?: string;
+  /** server-sent events: `data` lines, optionally `event:` lines named by each event, and the
+   *  sentinel a finished stream ends with */
+  sse?: { named: boolean; done?: string };
+  /** an operation whose stream is framed otherwise (named events, no sentinel) */
+  streamFor?: Record<string, { named: boolean; done?: string }>;
+  /** the vendor's idempotency header: a write repeated with the same key answers the stored
+   *  answer; the same key with other parameters answers `conflict` */
+  /** `methods` defaults to POST; `onlySuccess` (replay only 2xx answers) to false; without
+   *  `conflict`, a key replays its first answer whatever the parameters */
+  idempotency?: { header: string; storedAs: string; conflict?: ErrorSpec; methods?: string[]; onlySuccess?: boolean };
+  /** how the vendor reads its credential, and what it answers without one or with a key the twin
+   *  reserves as invalid, or one of a shape the vendor never issues (`keyFormat`, a pattern every key it issues
+   *  matches: Resend's begin `re_`); a request that presents no such header at all is a trusted in-process call */
+  auth?: { header: string; scheme: string; missing: ErrorSpec; invalidKeys: string[]; keyFormat?: string; invalid: ErrorSpec; gateWhenAbsent: boolean };
+  /** the twin door that makes the next request answer the vendor's rate-limit refusal */
+  /** headers every answer carries (a request id) */
+  answerHeaders?: Record<string, string>;
+  /** an origin the pack writes into URLs it mints, rewritten in every JSON answer to where this
+   *  twin is reached for the request (twinPublicBase) */
+  origin?: { placeholder: string };
+  /** while a pack moves, how its existing code renders a stored subject (named by its stored
+   *  type), so moved and unmoved operations answer the same shape */
+  view?: (storedType: string, body: Record<string, unknown>) => Record<string, unknown>;
+  resources: Record<string, ResourceDecl>;
+  /** the vendor's screens this pack serves or owes (demand decides which exist) */
+  screens?: ScreenDecl[];
+  /** called after every stored write with the rendered resource, its stored type and the kernel operation name */
+  onWrite?: (write: { operation: string; storedType: string; body: Record<string, unknown>; root?: string; occurredAt: string; request: Request }) => Promise<void>;
+};
+
+// ── request parsing ──────────────────────────────────────────────────────────────────────────
+
+/** A form body's bracket notation (`a[b][0][c]=v`, `expand[]=x`) as nested objects and arrays. A form carries only
+ *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
+ *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
+ *  (`metadata[order]=007`, `name=2024`). */
+export function parseBracketForm(text: string, scalars?: Readonly<Record<string, string | undefined>>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [rawKey, raw] of new URLSearchParams(text)) {
+    const parts = rawKey.replace(/\]/g, '').split('[');
+    const kind = scalars && scalarAt(scalars, parts);
+    const value: unknown = kind === 'boolean' ? (raw === 'true' ? true : raw === 'false' ? false : raw)
+      : kind === 'integer' ? (/^-?\d+$/.test(raw) ? Number(raw) : raw)
+      : kind === 'number' ? (/^-?\d+(\.\d+)?$/.test(raw) ? Number(raw) : raw)
+      : raw;
+    let node: any = out;
+    parts.forEach((key, i) => {
+      if (i === parts.length - 1) {
+        if (key === '') {
+          if (Array.isArray(node)) node.push(value);
+        } else node[key] = value;
+        return;
+      }
+      const next = parts[i + 1]!;
+      if (node[key] === undefined) node[key] = next === '' || /^\d+$/.test(next) ? [] : {};
+      node = node[key];
+    });
+  }
+  return out;
+}
+
+/** The type `scalars` gives a form key's parts: a segment is a property name, `[]` an array's item (an index or empty),
+ *  `*` a map's key. */
+function scalarAt(scalars: Readonly<Record<string, string | undefined>>, parts: string[]): string | undefined {
+  let paths = [''];
+  for (const [i, part] of parts.entries()) {
+    const segs = part === '' || /^\d+$/.test(part) ? ['[]', '*'] : [part, '*'];
+    paths = paths.flatMap((p) => segs.map((seg) => (i === 0 ? seg : `${p}.${seg}`)));
+    if (paths.length > 64) paths = paths.filter((p) => Object.keys(scalars).some((k) => k === p || k.startsWith(`${p}.`)));
+  }
+  for (const p of paths) if (scalars[p]) return scalars[p];
+  return undefined;
+}
+
+/** A request's parameters, its query's and its body's. With the manifest's `body.form.coerce`, a form's fields the
+ *  operation's spec types as numbers or booleans are read as them (parseBracketForm); without an operation (a twin door)
+ *  every form value is its text. */
+export async function readParams(manifest: DerivedManifest, request: Request, operation?: DerivedOperation): Promise<Record<string, unknown>> {
+  const url = new URL(request.url);
+  const scalars = manifest.body.form?.coerce ? (operation?.scalars ?? {}) : undefined;
+  const query = parseBracketForm(url.search.replace(/^\?/, ''), scalars);
+  if (request.method === 'GET' || request.method === 'HEAD') return query;
+  const type = request.headers.get('content-type') ?? '';
+  if (type.includes('multipart/form-data')) {
+    // an upload: text fields as given, each file as its name, media type, size and content (its text), with its raw
+    // `bytes` beside them for a pack that must tell an image or audio file from anything else; the bytes are not
+    // enumerated, so a write's record of the request keeps the text alone
+    const form = await request.formData();
+    const out: Record<string, unknown> = { ...query };
+    for (const [key, value] of form.entries()) {
+      if (typeof value === 'string') {
+        out[key] = value;
+        continue;
+      }
+      const file = value as unknown as { name: string; type: string; size: number; arrayBuffer(): Promise<ArrayBuffer> };
+      const bytes = new Uint8Array(await file.arrayBuffer());
+      const parsed = { name: file.name, type: file.type, size: file.size, content: new TextDecoder().decode(bytes) };
+      out[key] = Object.defineProperty(parsed, 'bytes', { value: bytes, enumerable: false });
+    }
+    return out;
+  }
+  const text = await request.text();
+  if (!text) return query;
+  const asJson = type.includes('json') || manifest.body.json === 'always';
+  const body: unknown = asJson ? JSON.parse(text) : parseBracketForm(text, scalars);
+  // a body that is not an object (GitHub's set-labels takes a bare array) is the body, not fields
+  return body && typeof body === 'object' && !Array.isArray(body) ? { ...query, ...(body as Record<string, unknown>) } : { ...query };
+}
+
+// ── answers ──────────────────────────────────────────────────────────────────────────────────
+
+const ABSENT = Symbol('absent');
+
+function fill(template: unknown, values: Record<string, unknown>, omitAbsent = false): unknown {
+  if (typeof template === 'string') {
+    const whole = /^\{(\w+)\}$/.exec(template);
+    if (whole) return values[whole[1]!] ?? (omitAbsent ? ABSENT : null);
+    return template.replace(/\{(\w+)\}/g, (_, k: string) => String(values[k] ?? ''));
+  }
+  if (Array.isArray(template)) return template.map((t) => fill(t, values, omitAbsent)).filter((v) => v !== ABSENT);
+  if (template && typeof template === 'object') {
+    return Object.fromEntries(Object.entries(template).map(([k, v]) => [k, fill(v, values, omitAbsent)] as const).filter(([, v]) => v !== ABSENT));
+  }
+  return template;
+}
+
+export function vendorError(manifest: DerivedManifest, e: ErrorSpec): Response {
+  // the status as the answer's number, and as text for a vendor whose body spells it as a string (GitHub's "404")
+  const values = { message: e.message, code: e.code ?? null, param: e.param ?? null, kind: e.kind ?? manifest.defaultKind ?? null, status: e.status, statusText: String(e.status) };
+  // a vendor that answers its errors as a document, not JSON (S3's XML `<Error><Code>…`): the template is that text,
+  // each value escaped into it
+  if (typeof manifest.error === 'string') {
+    const escape = (v: unknown): string => String(v ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const body = manifest.error.replace(/\{(\w+)\}/g, (_, k: string) => escape(values[k as keyof typeof values]));
+    return new Response(body, { status: e.status, headers: { 'content-type': body.trimStart().startsWith('<') ? 'application/xml' : 'text/plain; charset=utf-8' } });
+  }
+  return Response.json(fill(manifest.error, values, manifest.errorOmitsAbsent ?? false), { status: e.status });
+}
+
+function notFound(manifest: DerivedManifest, object: string, id: string, param?: string): Response {
+  const nf = manifest.notFound;
+  if (!nf.withParam) param = undefined;
+  const own = manifest.resources[object]?.notFound;
+  const message = typeof own === 'string' ? own : (own?.message ?? nf.message);
+  const code = typeof own === 'object' ? own.code : nf.code;
+  return vendorError(manifest, { status: nf.status, message: String(fill(message, { object, id })), ...(code ? { code } : {}), ...(nf.kind ? { kind: nf.kind } : {}), ...(param ? { param } : {}) });
+}
+
+// ── the tree ─────────────────────────────────────────────────────────────────────────────────
+
+const storedType = (m: DerivedManifest, resource: string): string => m.resources[resource]?.storedAs ?? resource;
+
+// A service's resources by type, folded once per World state (the tree's stamp; any write moves it), not on every read:
+// a read of one resource type projected the service's whole tree, so a pack whose tree also holds many subjects of
+// other types (PlanetScale's SQL rows beside its management records) paid for all of them on each read. A read gets its
+// own copy of each resource, as twinResources hands out, with the vendor's own id/type/updatedAt a spread would drop.
+const typeIndexes = new WeakMap<object, Map<string, { stamp: string; byType: Map<string, Map<string, TwinResource>> }>>();
+/** A service's resources of one type, each the reader's own copy: `twinResources` filtered by type, from an index
+ *  that follows each write rather than projecting the whole tree per call. */
+export function resourcesOfType(service: string, type: string, root?: string): TwinResource[] {
+  const store = getActiveWorldStore();
+  const indexes = typeIndexes.get(store) ?? typeIndexes.set(store, new Map()).get(store)!;
+  const key = `${service}\u0000${root ?? ''}`;
+  let held = indexes.get(key);
+  // a write moves the stamp; the index follows it by the subjects the write touched, and refolds only when
+  // the kernel cannot say which (a projection of the whole tree after every write grew with the World)
+  const delta = held ? treeChangesSince(service, root, held.stamp) : undefined;
+  if (held && delta) {
+    // the index keeps the tree's order: a subject updated where it stands stays there, one new to the tree (or made
+    // again after a delete) goes to the end in the order the tree holds it
+    for (const k of [...delta.removed, ...delta.appended]) held.byType.get(k.slice(0, k.indexOf(':')))?.delete(k);
+    const byKey = new Map(delta.changed.map((r) => [`${r.type}:${r.id}`, r]));
+    for (const [k, r] of byKey) if (!delta.appended.includes(k)) (held.byType.get(r.type) ?? held.byType.set(r.type, new Map()).get(r.type)!).set(k, r);
+    for (const k of delta.appended) { const r = byKey.get(k)!; (held.byType.get(r.type) ?? held.byType.set(r.type, new Map()).get(r.type)!).set(k, r); }
+    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
+    const stamp = treeStamp(service, root);
+    const byType = new Map<string, Map<string, TwinResource>>();
+    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);
+}
+
+function stored(m: DerivedManifest, resource: string, root?: string, opts: { withDeleted?: boolean } = {}): TwinResource[] {
+  const type = storedType(m, resource);
+  const when = Object.entries(m.resources[resource]?.readableWhen ?? {});
+  return resourcesOfType(m.service, type, root).filter((r) => (opts.withDeleted || r.deleted !== true) && when.every(([k, v]) => (r as Record<string, unknown>)[k] === v));
+}
+
+/** The subject an item operation names: the manifest's key over the path parameters, or the last one. */
+function subjectOf(m: DerivedManifest, resource: string, call: DerivedCall): string | undefined {
+  const key = m.resources[resource]?.key;
+  return key ? String(fill(key, call.params)) : Object.values(call.params).at(-1);
+}
+
+/** A missing parent's not-found, when the resource lives under one. */
+/** The parent value a call names: one path parameter, or several joined by the parent's template. */
+function parentValue(parent: NonNullable<ResourceDecl['parent']>, params: Record<string, string>): string | undefined {
+  if (parent.params) return String(fill(parent.value ?? parent.params.map((p) => `{${p}}`).join('/'), params));
+  return parent.param !== undefined ? params[parent.param] : undefined;
+}
+
+function missingParent(m: DerivedManifest, resource: string, call: DerivedCall, root?: string): Response | undefined {
+  const parent = m.resources[resource]?.parent;
+  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((r as Record<string, unknown>)[field]) === v) : r.id === id);
+  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. */
+/** A stored subject as the vendor's object: its id first (the subject's, unless the pack kept an id of its own), then
+ *  the fields the pack wrote, bookkeeping (`_`) and the kernel's updatedAt left out. */
+export function render(r: TwinResource): Record<string, unknown> {
+  return Object.fromEntries(Object.entries({ id: r.id, ...ownFields(r) }).filter(([k]) => !k.startsWith('_') && k !== 'updatedAt'));
+}
+
+function view(m: DerivedManifest, resource: string, r: TwinResource): Record<string, unknown> {
+  const own = m.resources[resource]?.view;
+  if (own) return own(render(r), { id: r.id, type: r.type });
+  if (!m.view) return render(r);
+  // a pack's view sees the stored row whole, and bookkeeping (`_`) never reaches the wire whatever it returns
+  return Object.fromEntries(Object.entries(m.view(storedType(m, resource), r as Record<string, unknown>)).filter(([k]) => !k.startsWith('_')));
+}
+
+/** Where the core runs: the World root it reads and writes, and its clock (the World's by default;
+ *  a caller that pins an instant passes its own). */
+export type CoreScope = { root?: string; clock?: () => string };
+
+function now(m: DerivedManifest, at: string): unknown {
+  return m.time === 'unix' ? Math.floor(Date.parse(at) / 1000) : at;
+}
+
+function applyRule(m: DerivedManifest, rule: FieldRule, id: string, values: Record<string, unknown>, at: string): unknown {
+  if ('now' in rule) return now(m, at);
+  if ('id' in rule) return id;
+  if ('value' in rule) return rule.value;
+  return fill(rule.template, { ...values, id });
+}
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** The next id the manifest's template gives this resource: one past the highest it already minted. */
+function mintId(m: DerivedManifest, resource: string, root?: string): string {
+  const prefix = m.resources[resource]!.idPrefix;
+  if (m.ids.template === '{uuid}') return mintUuid(m, resource, root);
+  const [head, tail = ''] = m.ids.template.split('{n}');
+  const pattern = new RegExp(`^${escapeRe(String(fill(head!, { prefix })))}(\\d+)${escapeRe(String(fill(tail, { prefix })))}$`);
+  let max = 0;
+  // the one type, from the index that follows writes (a scan of the whole World per create grew with it)
+  for (const r of resourcesOfType(m.service, storedType(m, resource), root)) {
+    const hit = pattern.exec(r.id);
+    if (hit) max = Math.max(max, Number(hit[1]));
+  }
+  return String(fill(m.ids.template, { prefix, n: max + 1 }));
+}
+
+/** The next UUID for a resource: a version-4-shaped UUID derived from the resource and the count before it, past any
+ *  the World already holds. */
+function mintUuid(m: DerivedManifest, resource: string, root?: string): string {
+  const type = storedType(m, resource);
+  const held = new Set(resourcesOfType(m.service, type, root).map((r) => r.id));
+  for (let n = held.size + 1; ; n++) {
+    const h = createHash('sha256').update(`${m.service}:${resource}:${n}`).digest('hex');
+    const id = `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${'89ab'[parseInt(h[16]!, 16) % 4]}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+    if (!held.has(id)) return id;
+  }
+}
+
+function expand(m: DerivedManifest, resource: string, body: Record<string, unknown>, paths: string[], root?: string): Record<string, unknown> {
+  const embeds = m.resources[resource]?.embeds ?? {};
+  const out = { ...body };
+  for (const path of paths) {
+    const [head, ...rest] = path.split('.');
+    const target = embeds[head!];
+    const id = out[head!];
+    if (!target || typeof id !== 'string') continue;
+    const hit = stored(m, target, root).find((r) => r.id === id);
+    if (hit) out[head!] = rest.length ? expand(m, target, view(m, target, hit), [rest.join('.')], root) : view(m, target, hit);
+  }
+  return out;
+}
+
+function expandPaths(m: DerivedManifest, params: Record<string, unknown>): string[] {
+  const raw = m.expandParam ? params[m.expandParam] : undefined;
+  return Array.isArray(raw) ? raw.map(String) : typeof raw === 'string' ? [raw] : [];
+}
+
+async function write(m: DerivedManifest, call: DerivedCall, resource: string, id: string, fields: Record<string, unknown>, operation: string, params: Record<string, unknown>, root: string | undefined, occurredAt: string): Promise<Record<string, unknown>> {
+  return (await writeDetailed(m, call, resource, id, fields, operation, params, root, occurredAt)).body;
+}
+
+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): Promise<{ body: Record<string, unknown>; id: string; vendorData?: unknown }> {
+  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
+    { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: { operationId: call.operation.id, params: call.params, body: params }, occurredAt, actor: { kind: 'agent', ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) } },
+    root,
+  );
+  const body = view(m, resource, row);
+  if (m.onWrite) await m.onWrite({ operation, storedType: storedType(m, resource), body, ...(root !== undefined ? { root } : {}), occurredAt, request: call.request });
+  // the subject's id as it stands after the write: the vendor's, when a live head minted one
+  return { body, id: result.externalId ?? row.id, ...(result.vendorData !== undefined ? { vendorData: result.vendorData } : {}) };
+}
+
+/** 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;
+}
+
+const encodeOffset = (o: number): string => btoa(JSON.stringify({ o }));
+function decodeOffset(cursor: unknown): number {
+  if (typeof cursor !== 'string' || !cursor) return 0;
+  try {
+    const o = (JSON.parse(atob(cursor)) as { o?: unknown }).o;
+    return typeof o === 'number' && o >= 0 ? o : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// ── state ────────────────────────────────────────────────────────────────────────────────────
+
+/** What a coverage measurement sees of a pack's declared state logic: each move a request made and each refusal a
+ *  guard gave, by the transition that decided it. Nothing is observed unless a measurement installs an observer
+ *  (scripts/life-coverage.ts); serving never depends on it. */
+export type TransitionObserver = (decl: StateField, transition: Transition, outcome: 'moved' | 'refused', from: string) => void;
+let transitionObserver: TransitionObserver | undefined;
+export function observeTransitions(observer: TransitionObserver | undefined): void {
+  transitionObserver = observer;
+}
+
+/** The transition a request asks for on one state field, or the vendor's refusal when none applies. */
+/** What a declared machine says to one move: the transition that allows it, or the refusal it gives (and
+ *  nothing when it declares neither). The derived core and `legal` ask it; so does an engine that is not
+ *  HTTP-shaped (a line protocol's session), so one machine rules every wire. */
+export function transitionFor(field: string, decl: StateField, operationId: string, current: unknown, requested: unknown, id?: string, actor: Actor = 'api'): { move?: Transition; refusal?: ErrorSpec } {
+  const now = stateOf(decl, current);
+  const candidates = decl.transitions.filter((t) => (t.actor ?? 'api') === actor && (t.operation ? t.operation === operationId : true) && (requested === undefined || (t.to ?? now) === String(requested)));
+  const move = candidates.find((t) => t.from === '*' || t.from.includes(now));
+  if (move) { transitionObserver?.(decl, move, 'moved', now); return { move }; }
+  const refused = candidates.find((t) => t.refusals?.[now]) ?? candidates.find((t) => t.refusal);
+  const r = refused?.refusals?.[now] ?? refused?.refusal;
+  if (refused && r) transitionObserver?.(decl, refused, 'refused', now);
+  if (r) return { refusal: { status: r.status, message: String(fill(r.message, { from: current, to: refused!.to ?? now, field, id: id ?? '' })), ...(r.code ? { code: r.code } : {}) } };
+  return {};
+}
+
+// ── the core ─────────────────────────────────────────────────────────────────────────────────
+
+export type CoreOutcome = { served: Response } | { unmodeled: string };
+
+// ALIAS-AWARE LOOKUP AT THE REQUEST BOUNDARY (architecture.md): after an adoption a caller may still name a subject by
+// its local id; a declared reference in the call's params is resolved through the alias map once, here, where the
+// params are parsed, so a handler's lookup (`ctx.row`) and the write both see the adopted id. The map is read only
+// for a pack that declares references, and once per state of the parent side. An idempotency key's request hash is
+// taken over the bytes as sent, so the same key sent once with the local id and once with the adopted one is two
+// requests.
+const aliasMemos = new WeakMap<object, Map<string, { stamp: string; aliases: Map<string, string> }>>();
+function aliasesNow(service: string, root?: string): Map<string, string> {
+  const store = getActiveWorldStore();
+  const memos = aliasMemos.get(store) ?? aliasMemos.set(store, new Map()).get(store)!;
+  const key = `${service}\u0000${root ?? ''}`;
+  // aliases come from the parent side alone: a local write (the branch log) leaves them as they were
+  const stamp = parentStamp(service, root);
+  let held = memos.get(key);
+  if (!held || held.stamp !== stamp) { held = { stamp, aliases: subjectAliases(service, root) }; memos.set(key, held); }
+  return held.aliases;
+}
+/** The call with a path parameter naming the operation's subject, or its parent, by a local id moved to the adopted
+ *  id (`GET /segments/<local>` after the segment was adopted). Only the operation's own type and its parent's are
+ *  tried, so no other parameter is touched. A vendor naming its subject in the body (Slack's `ts`) declares it as a
+ *  reference, which adoptedInCall resolves. */
+function adoptedPath(m: DerivedManifest, call: DerivedCall, root?: string): DerivedCall {
+  const resource = call.operation.resource;
+  const decl = resource ? m.resources[resource] : undefined;
+  if (!decl || Object.keys(call.params).length === 0) return call;
+  const aliases = aliasesNow(m.service, root);
+  if (aliases.size === 0) return call;
+  const types = [storedType(m, resource!), ...(decl.parent ? [storedType(m, decl.parent.resource)] : [])];
+  let params = call.params;
+  for (const [name, value] of Object.entries(call.params)) {
+    const adopted = types.map((type) => aliases.get(`${type}:${value}`)).find((id) => id !== undefined);
+    if (adopted !== undefined && adopted !== value) params = { ...params, [name]: adopted };
+  }
+  return params === call.params ? call : { ...call, params };
+}
+/** A call's fields with each declared reference that names an adopted subject by its local id moved to the adopted
+ *  id. A call (a handler's operation) need not say which subject type it writes, so every reference the pack declares
+ *  is tried: a field is rewritten only when its value is a local id the alias map holds for the reference's target. */
+function adoptedInCall(service: string, fields: Record<string, unknown>, root?: string): Record<string, unknown> {
+  const refs = packReferences(service);
+  if (refs.length === 0) return fields;
+  const aliases = aliasesNow(service, root);
+  if (aliases.size === 0) return fields;
+  let out = fields;
+  for (const ref of refs) {
+    const local = ref.key(out as SubjectFields);
+    const adopted = local === undefined ? undefined : aliases.get(`${ref.to}:${local}`);
+    if (adopted !== undefined && adopted !== local) out = { ...out, ...ref.adopt(out as SubjectFields, adopted) };
+  }
+  return out;
+}
+async function boundaryParams(m: DerivedManifest, call: DerivedCall, root?: string): Promise<Record<string, unknown>> {
+  return adoptedInCall(m.service, await readParams(m, call.request, call.operation), root);
+}
+
+/** Serve one operation from the manifest, or say why the core cannot. */
+export async function serveCore(m: DerivedManifest, call: DerivedCall, scope: CoreScope = {}): Promise<CoreOutcome> {
+  const root = scope.root;
+  const at = (scope.clock ?? worldNow)();
+  const op: DerivedOperation = call.operation;
+  const resource = op.resource;
+  const decl = resource ? m.resources[resource] : undefined;
+  if (!resource || !decl) return { unmodeled: `no manifest entry for resource ${resource ?? '(none)'}` };
+  call = adoptedPath(m, call, root);
+  const params = await boundaryParams(m, call, root);
+  const idParam = subjectOf(m, resource, call);
+  const orphan = missingParent(m, resource, call, root);
+  if (orphan) return { served: orphan };
+  const parent = decl.parent;
+  const parentId = parent ? parentValue(parent, call.params) : undefined;
+  const underParent = (r: TwinResource): boolean => !parent || (r as Record<string, unknown>)[parent.field] === parentId;
+  const paths = expandPaths(m, params);
+  // the vendor's success status from its spec: 201 for most creates, 204 with no body where it answers nothing
+  const status = op.successStatus ?? 200;
+  const answer = (body: Record<string, unknown>) => ({
+    served: status === 204 ? new Response(null, { status }) : Response.json(envelope(m, op, paths.length ? expand(m, resource, body, paths, root) : body), { status }),
+  });
+  const control = new Set([m.expandParam, m.list.limit.param, m.list.after, m.list.before, m.list.offset?.param].filter(Boolean) as string[]);
+  const data = Object.fromEntries(Object.entries(params).filter(([k]) => !control.has(k) && k !== 'id'));
+
+  switch (op.class) {
+    case 'create': {
+      for (const field of Object.keys(decl.state ?? {})) if (field in data) return { unmodeled: `create sets state field ${field}` };
+      if (decl.key) return { unmodeled: 'a create under a composite key is a handler' };
+      const provided = m.ids.acceptProvided && typeof params.id === 'string' && params.id ? params.id : undefined;
+      const id = provided ?? mintId(m, resource, root);
+      const assigned = Object.fromEntries(Object.entries(decl.assigned ?? {}).map(([k, rule]) => [k, applyRule(m, rule, id, data, at)]));
+      const initial = Object.fromEntries(Object.entries(decl.state ?? {}).map(([k, s]) => [k, s.initial]));
+      const under = parent ? { [parent.field]: parentId } : {};
+      if (decl.number) {
+        const siblings = stored(m, resource, root, { withDeleted: true }).filter((r) => !parent || (r as Record<string, unknown>)[parent.field] === parentId);
+        (under as Record<string, unknown>)[decl.number.field] = 1 + siblings.reduce((n, r) => Math.max(n, Number((r as Record<string, unknown>)[decl.number!.field]) || 0), 0);
+      }
+      return answer(await write(m, call, resource, id, { ...assigned, ...initial, ...under, ...data }, `${storedType(m, resource)}.create`, params, root, at));
+    }
+    case 'retrieve': {
+      const hit = idParam ? stored(m, resource, root).find((r) => r.id === idParam && underParent(r)) : undefined;
+      return hit ? answer(view(m, resource, hit)) : { served: notFound(m, resource, String(idParam), Object.keys(call.params).at(-1)) };
+    }
+    case 'list': {
+      let rows = stored(m, resource, root).filter(underParent).map((r) => view(m, resource, r));
+      for (const f of decl.filters ?? []) if (params[f] !== undefined) rows = rows.filter((r) => String(r[f]) === String(params[f]));
+      const order = decl.order ?? { field: 'created', direction: 'desc' as const };
+      rows.sort((a, b) => {
+        // ties by mint order (`file-twin-10` after `file-twin-9`), not by the ids' lexical order
+        const d = Number(a[order.field] ?? 0) - Number(b[order.field] ?? 0) || String(a.id).localeCompare(String(b.id), undefined, { numeric: true });
+        return order.direction === 'desc' ? -d : d;
+      });
+      const size = m.list.limits?.[op.id] ?? m.list.limit;
+      const asked = params[m.list.limit.param];
+      const n = asked === undefined || asked === '' ? size.default : Number(asked);
+      const limit = Number.isFinite(n) ? Math.min(size.max, Math.max(1, Math.trunc(n))) : size.default;
+      const after = m.list.after ? params[m.list.after] : undefined;
+      const before = m.list.before ? params[m.list.before] : undefined;
+      let from = 0;
+      let to: number;
+      if (typeof before === 'string') {
+        const at = rows.findIndex((r) => r.id === before);
+        to = at === -1 ? (m.list.unknownCursor === 'end' ? 0 : rows.length) : at;
+        from = Math.max(0, to - limit);
+      } else {
+        if (typeof after === 'string') {
+          const at = rows.findIndex((r) => r.id === after);
+          from = at === -1 ? (m.list.unknownCursor === 'end' ? rows.length : 0) : at + 1;
+        }
+        to = from + limit;
+      }
+      const page = rows.slice(from, to).map((r) => (paths.length ? expand(m, resource, r, paths.filter((p) => p.startsWith('data.')).map((p) => p.slice(5)), root) : r));
+      const hasMore = typeof before === 'string' ? from > 0 : to < rows.length;
+      const url = op.path.replace(/\{[^}]+\}/g, (p) => call.params[p.slice(1, -1)] ?? p);
+      if (m.list.page) {
+        const n = Math.max(1, Math.floor(Number(params[m.list.page.param]) || 1));
+        const slice = rows.slice((n - 1) * limit, n * limit);
+        const last = Math.max(1, Math.ceil(rows.length / limit));
+        const headers = new Headers();
+        if (m.list.page.link && rows.length > limit) {
+          const at = (k: number): string => {
+            const u = new URL(call.request.url);
+            u.searchParams.set(m.list.page!.param, String(k));
+            return u.toString();
+          };
+          const rels = [...(n > 1 ? [`<${at(n - 1)}>; rel="prev"`] : []), ...(n < last ? [`<${at(n + 1)}>; rel="next"`, `<${at(last)}>; rel="last"`] : []), ...(n > 1 ? [`<${at(1)}>; rel="first"`] : [])];
+          if (rels.length) headers.set('link', rels.join(', '));
+        }
+        return { served: Response.json(fill(m.list.envelope, { data: slice, next_cursor: null, key: op.answers?.key ?? 'data' }), { headers }) };
+      }
+      if (m.list.offset) {
+        const skip = Math.max(0, Math.trunc(Number(params[m.list.offset.param]) || 0));
+        const slice = rows.slice(skip, skip + limit);
+        const key = op.answers?.key ?? 'data';
+        return { served: Response.json({ ...(m.success ?? {}), [key]: slice, ...(fill(m.list.envelopes?.[op.id] ?? m.list.envelope, { data: slice, total_count: rows.length, key }) as object) }) };
+      }
+      if (m.list.cursor) {
+        const start = decodeOffset(params[m.list.cursor.param]);
+        const slice = rows.slice(start, start + limit);
+        const next = start + limit < rows.length ? encodeOffset(start + limit) : '';
+        return { served: Response.json({ ...(m.success ?? {}), ...(fill(m.list.envelope, { data: slice, next_cursor: next, key: op.answers?.key ?? 'data' }) as object), ...(op.answers?.key ? { [op.answers.key]: slice } : {}) }) };
+      }
+      return { served: Response.json(fill(m.list.envelope, { data: page, has_more: hasMore, url, first_id: page[0]?.id ?? null, last_id: page.at(-1)?.id ?? null })) };
+    }
+    case 'update':
+    case 'action': {
+      const hit = idParam ? stored(m, resource, root).find((r) => r.id === idParam && underParent(r)) : undefined;
+      if (!hit) return { served: notFound(m, resource, String(idParam), Object.keys(call.params).at(-1)) };
+      const current = view(m, resource, hit);
+      const changes: Record<string, unknown> = { ...(op.class === 'update' ? data : {}) };
+      let moved = false;
+      for (const [field, sdecl] of Object.entries(decl.state ?? {})) {
+        const requested = op.class === 'update' ? data[field] : undefined;
+        if (op.class === 'update' && requested === undefined) continue;
+        const { move, refusal } = transitionFor(field, sdecl, op.id, current[field], requested, hit.id);
+        if (refusal) return { served: vendorError(m, refusal) };
+        if (!move) {
+          if (op.class === 'update') return { unmodeled: `no declared transition of ${field} to ${String(requested)} by ${op.id}` };
+          continue;
+        }
+        const stored = storedState(sdecl, move.to);
+        if (stored !== undefined) changes[field] = stored;
+        for (const [k, rule] of Object.entries(move.effects ?? {})) changes[k] = applyRule(m, rule, hit.id, { ...current, ...changes }, at);
+        moved = true;
+      }
+      if (op.class === 'action' && !moved) return { unmodeled: `action ${op.id} declares no transition` };
+      const merged: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(changes)) {
+        const prior = current[k];
+        merged[k] = decl.update !== 'replace' && v && typeof v === 'object' && !Array.isArray(v) && prior && typeof prior === 'object' && !Array.isArray(prior) ? Object.fromEntries(Object.entries({ ...(prior as object), ...(v as object) }).filter(([, value]) => value !== '')) : v;
+      }
+      return answer(await write(m, call, resource, hit.id, merged, `${storedType(m, resource)}.${op.class === 'update' ? 'update' : op.id}`, params, root, at));
+    }
+    case 'delete': {
+      const hit = idParam ? stored(m, resource, root).find((r) => r.id === idParam && underParent(r)) : undefined;
+      if (!hit) return { served: notFound(m, resource, String(idParam), Object.keys(call.params).at(-1)) };
+      await write(m, call, resource, hit.id, { deleted: true }, `${storedType(m, resource)}.delete`, params, root, at);
+      const shape = decl.deleted !== undefined ? decl.deleted : m.deleted;
+      return { served: status === 204 || shape === null ? new Response(null, { status: 204 }) : Response.json(fill(shape, { id: hit.id, object: current(hit) }), { status }) };
+    }
+    default:
+      return { unmodeled: `class ${op.class} is not served by the core` };
+  }
+}
+
+function current(r: TwinResource): unknown {
+  return render(r).object ?? r.type;
+}
+
+/** Server-sent events in the manifest's framing. The events are known when the answer starts: the
+ *  twin decides deterministically, so the stream carries a decided answer, never a model's. */
+export function sse(m: DerivedManifest, events: Array<{ event?: string; data: unknown }>, operationId?: string): Response {
+  const enc = new TextEncoder();
+  const framing = (operationId && m.streamFor?.[operationId]) || m.sse;
+  const frame = (e: { event?: string; data: unknown }): string => `${framing?.named && e.event ? `event: ${e.event}\n` : ''}data: ${JSON.stringify(e.data)}\n\n`;
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const e of events) controller.enqueue(enc.encode(frame(e)));
+      if (framing?.done) controller.enqueue(enc.encode(`data: ${framing.done}\n\n`));
+      controller.close();
+    },
+  });
+  return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache' } });
+}
+
+// ── semantics ────────────────────────────────────────────────────────────────────────────────
+
+/** What a semantics handler works with: the request's parameters, the tree through the pack's view,
+ *  the write path (which runs the manifest's write hook), and the declared machine. A handler never
+ *  imports the kernel; this is its whole interface. */
+export type SemanticsContext = {
+  call: DerivedCall;
+  params: Record<string, unknown>;
+  /** the last path parameter: the subject an item operation names */
+  id: string | undefined;
+  /** the request body as the vendor reads it (an array, where the vendor takes one), and its text */
+  body: unknown;
+  text: string;
+  root: string | undefined;
+  occurredAt: string;
+  /** who is calling, when the manifest says how to tell */
+  actor: string | undefined;
+  now(): unknown;
+  get(resource: string, id: string): Record<string, unknown> | undefined;
+  rows(resource: string): Array<Record<string, unknown>>;
+  mint(resource: string): string;
+  write(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<Record<string, unknown>>;
+  /** `write`, with what a live vendor answered when the head performed it */
+  writeDetailed(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<{ body: Record<string, unknown>; id: string; vendorData?: unknown }>;
+  /** The id a subject has now, for an id a caller may still use from before the vendor minted its own
+   *  (a branch naming a message by the ts it minted locally). */
+  resolve(resource: string, id: string): string;
+  /** Answer the vendor's success envelope around several fields (`{ ok: true, ts, channel, message }`). */
+  ok(fields: Record<string, unknown>): Response;
+  /** A stored row as it is kept, bookkeeping (`_`) fields and tombstones included. */
+  row(resource: string, id: string, opts?: { withDeleted?: boolean }): Record<string, unknown> | undefined;
+  rowsRaw(resource: string, opts?: { withDeleted?: boolean }): Array<Record<string, unknown>>;
+  /** Every stored subject of the pack, of every type, in the tree's order (a projection folding many types at once). */
+  tree(): Array<Record<string, unknown>>;
+  /** The writes that touched a subject, in order: its history. */
+  history(resource: string, id: string): Array<{ operation?: string; fields?: Record<string, unknown>; occurredAt?: string }>;
+  /** Write a bookkeeping subject (a `_`-prefixed type the vendor never serves), minting its id when none is given. */
+  record(type: string, fields: Record<string, unknown>, id?: string): Promise<string>;
+  /** Decide a write from the tree as it stands and make it, with nothing written between the read
+   *  and the write (a minted number, a first poll that moves a subject). `decide` returns the write,
+   *  or nothing to write; the answer is its `value`. */
+  atomically<T>(decide: (rows: (resource: string) => Array<Record<string, unknown>>) => { value: T; write?: { resource: string; id: string; fields: Record<string, unknown>; operation: string } }): Promise<T>;
+  /** Answer bytes or text as they are (a file's content), with the vendor's headers. */
+  raw(body: BodyInit | null, init?: { status?: number; headers?: Record<string, string> }): Response;
+  /** Whether the machine lets `operationId` move `field` from `current` (to `to`): nothing when it
+   *  does, the vendor's refusal when it does not. A move the machine does not declare throws. */
+  legal(resource: string, field: string, operationId: string, current: unknown, to?: string, id?: string, actor?: Actor): ErrorSpec | undefined;
+  refuse(e: ErrorSpec): Response;
+  notFound(resource: string, id: string, param?: string): Response;
+  reply(body: unknown, status?: number): Response;
+  /** Answer in the vendor's success envelope under this operation's key (`{ ok: true, channel }`). */
+  wrap(body: Record<string, unknown>, extra?: Record<string, unknown>): Response;
+  /** Answer as a server-sent event stream, framed as the manifest says. */
+  sse(events: Array<{ event?: string; data: unknown }>): Response;
+  expand(resource: string, body: Record<string, unknown>): Record<string, unknown>;
+  /** This context at another moment of the World clock (ISO): a move time makes is written at the moment it fell due. */
+  at(when: string): Promise<SemanticsContext>;
+  /** The generic core's answer to this call, or undefined where the core does not serve it. */
+  core(): Promise<Response | undefined>;
+  /** A stored row's own fields, as the vendor's object carries them (an `id`, `type` or `updatedAt` of its own restored). */
+  own(row: Record<string, unknown>): Record<string, unknown>;
+};
+export type Semantics = (ctx: SemanticsContext) => Promise<Response>;
+
+async function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext> {
+  const root = scope.root;
+  call = adoptedPath(m, call, root);
+  const at = (scope.clock ?? worldNow)();
+  const text = await call.request.clone().text().catch(() => '');
+  let body: unknown = undefined;
+  try { body = text ? JSON.parse(text) : undefined; } catch { body = text; }
+  // a handler reading the body itself sees the adopted id too (the boundary's one resolution, below)
+  if (body && typeof body === 'object' && !Array.isArray(body)) body = adoptedInCall(m.service, body as Record<string, unknown>, root);
+  const params = await boundaryParams(m, call, root);
+  const paths = expandPaths(m, params);
+  return {
+    call,
+    params,
+    id: Object.values(call.params).at(-1),
+    body,
+    text,
+    root,
+    occurredAt: at,
+    actor: m.identity ? m.identity(call.request.headers.get('authorization'), root) : undefined,
+    now: () => now(m, at),
+    get: (resource, id) => {
+      const hit = stored(m, resource, root).find((r) => r.id === id);
+      return hit ? view(m, resource, hit) : undefined;
+    },
+    rows: (resource) => stored(m, resource, root).map((r) => view(m, resource, r)),
+    mint: (resource) => mintId(m, resource, root),
+    write: (resource, id, fields, operation) => write(m, call, resource, id, fields, operation, params, root, at),
+    writeDetailed: (resource, id, fields, operation) => writeDetailed(m, call, resource, id, fields, operation, params, root, at),
+    resolve: (resource, id) => resolveSubjectId(m.service, storedType(m, resource), id, root),
+    ok: (fields) => Response.json({ ...(m.success ?? {}), ...fields }),
+    row: (resource, id, opts) => stored(m, resource, root, opts).find((r) => r.id === id) as Record<string, unknown> | undefined,
+    rowsRaw: (resource, opts) => stored(m, resource, root, opts) as Array<Record<string, unknown>>,
+    tree: () => twinResources(m.service, root) as Array<Record<string, unknown>>,
+    history: (resource, id) => subjectHistory(m.service, { type: storedType(m, resource), id }, root).map((e) => ({ ...(e.operation ? { operation: e.operation } : {}), ...(e.fields ? { fields: e.fields as Record<string, unknown> } : {}), ...(e.occurredAt ? { occurredAt: e.occurredAt } : {}) })),
+    record: async (type, fields, id) => {
+      if (!type.startsWith('_')) throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
+      const subject = id ?? `${type.slice(1)}_${twinResources(m.service, root).filter((r) => r.type === type).length + 1}`;
+      await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } }, root);
+      return subject;
+    },
+    raw: (body, init = {}) => new Response(body, { status: init.status ?? 200, headers: init.headers ?? {} }),
+    atomically: async (decide) => {
+      const { value } = await applyTwinWriteAtomic(
+        m.service,
+        (resources) => {
+          const rows = (resource: string): Array<Record<string, unknown>> => resources.filter((r) => r.type === storedType(m, resource) && r.deleted !== true) as Array<Record<string, unknown>>;
+          const d = decide(rows);
+          if (!d.write) return { kind: 'skip', value: d.value };
+          const w = d.write;
+          return { kind: 'write', value: d.value, write: { operation: w.operation, subjectType: storedType(m, w.resource), subjectId: w.id, fields: w.fields, occurredAt: at, actor: { kind: 'agent' } } };
+        },
+        root,
+      );
+      return value;
+    },
+    legal: (resource, field, operationId, current, to, id, actor) => {
+      const decl = m.resources[resource]?.state?.[field];
+      if (!decl) throw new Error(`semantics: ${resource}.${field} is not a declared state field`);
+      const { move, refusal } = transitionFor(field, decl, operationId, current, to, id ?? Object.values(call.params).at(-1), actor ?? 'api');
+      if (move) return undefined;
+      if (refusal) return refusal;
+      throw new Error(`semantics: ${operationId} moves ${resource}.${field} from ${String(current)}${to ? ` to ${to}` : ''}, which the machine does not declare`);
+    },
+    refuse: (e) => vendorError(m, e),
+    notFound: (resource, id, param) => notFound(m, resource, id, param),
+    reply: (body, status = 200) => Response.json(body, { status }),
+    wrap: (body, extra = {}) => Response.json({ ...envelope(m, call.operation, body), ...extra }),
+    sse: (events) => sse(m, events, call.operation.id),
+    expand: (resource, body) => (paths.length ? expand(m, resource, body, paths, root) : body),
+    at: (when) => contextFor(m, { ...call, request: new Request(call.request.url) }, { ...scope, clock: () => when }),
+    core: async () => { const out = await serveCore(m, call, { ...scope, clock: () => at }); return 'served' in out ? out.served : undefined; },
+    own: (row) => ownFields(row as unknown as TwinResource),
+  };
+}
+
+/** A pack's semantics handlers as the dispatch's handlers. */
+export function bindSemantics(m: DerivedManifest, handlers: Record<string, Semantics>, scope: CoreScope = {}): Record<string, DerivedHandler> {
+  return Object.fromEntries(Object.entries(handlers).map(([id, h]) => [id, async (call: DerivedCall) => h(await contextFor(m, call, scope))]));
+}
+
+/** The derived core as the dispatch's core: it owns every operation on a resource the manifest declares. */
+export function coreFor(m: DerivedManifest, scope: CoreScope = {}): { owns: (o: DerivedOperation) => boolean; serve: (call: DerivedCall) => Promise<DerivedCoreOutcome> } {
+  const crud = new Set(['create', 'retrieve', 'list', 'update', 'delete']);
+  const owns = (o: DerivedOperation): boolean => {
+    const decl = o.resource !== undefined ? m.resources[o.resource] : undefined;
+    if (!decl || m.unmodeled?.includes(o.id)) return false;
+    if (crud.has(o.class)) return true;
+    return o.class === 'action' && Object.values(decl.state ?? {}).some((f) => f.transitions.some((t) => t.operation === o.id));
+  };
+  return { owns, serve: (call) => serveCore(m, call, scope) };
+}
+
+// ── what every moved operation gets ──────────────────────────────────────────────────────────
+
+const hex = (s: string): string => Array.from(new TextEncoder().encode(s), (b) => b.toString(16).padStart(2, '0')).join('');
+
+/** Read-only refusal, API-version validation and idempotent replay, applied once around every
+ *  operation a handler or the core serves. */
+export function crossCutting(m: DerivedManifest, opts: CoreScope & { readOnly?: boolean } = {}): (call: DerivedCall, next: () => Promise<Response>) => Promise<Response> {
+  const finish = async (r: Response, request: Request): Promise<Response> => {
+    if (!m.origin || !(r.headers.get('content-type') ?? '').includes('json')) return withHeaders(r);
+    const text = (await r.text()).replaceAll(m.origin.placeholder, twinPublicBase(request));
+    return withHeaders(new Response(text, { status: r.status, statusText: r.statusText, headers: r.headers }));
+  };
+  const withHeaders = (r: Response): Response => {
+    if (!m.answerHeaders) return r;
+    const headers = new Headers(r.headers);
+    for (const [k, v] of Object.entries(m.answerHeaders)) if (!headers.has(k)) headers.set(k, v);
+    return new Response(r.body, { status: r.status, statusText: r.statusText, headers });
+  };
+  return async (call, next) => finish(await guarded(call, next), call.request);
+  async function guarded(call: DerivedCall, next: () => Promise<Response>): Promise<Response> {
+    const { request } = call;
+    if (m.auth) {
+      const raw = request.headers.get(m.auth.header);
+      if (raw !== null || m.auth.gateWhenAbsent) {
+        const scheme = `${m.auth.scheme.toLowerCase()} `;
+        const key = raw && raw.toLowerCase().startsWith(scheme) ? raw.slice(scheme.length).trim() : '';
+        if (!key) return vendorError(m, m.auth.missing);
+        if (m.auth.invalidKeys.includes(key) || (m.auth.keyFormat && !new RegExp(m.auth.keyFormat).test(key))) return vendorError(m, m.auth.invalid);
+      }
+    }
+    // a read-only twin refuses writes: what the operation does, not the HTTP verb it came by (an RPC
+    // wire POSTs its reads)
+    if (opts.readOnly && !['retrieve', 'list', 'computed'].includes(call.operation.class) && !m.reads?.includes(call.operation.id)) return vendorError(m, m.readOnly);
+    // a body labelled JSON that does not parse is the vendor's refusal, never a crash of the twin
+    if ((request.headers.get('content-type') ?? '').includes('json') || m.body.json === 'always') {
+      const text = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.clone().text().catch(() => '');
+      if (text) { try { JSON.parse(text); } catch { return vendorError(m, m.malformedBody ?? { status: 400, message: 'The request body could not be parsed as JSON.' }); } }
+    }
+    if (m.version) {
+      const value = request.headers.get(m.version.header);
+      if (value && !new RegExp(m.version.pattern).test(value)) return vendorError(m, { ...m.version.error, message: String(fill(m.version.error.message, { value })) });
+    }
+    const key = m.idempotency ? request.headers.get(m.idempotency.header) : null;
+    if (!m.idempotency || !key || !(m.idempotency.methods ?? ['POST']).includes(request.method.toUpperCase())) return next();
+    const url = new URL(request.url);
+    const signature = hashFieldValue({ path: url.pathname + url.search, body: await request.clone().text() });
+    const id = `idem_${hex(key)}`;
+    const prior = twinResources(m.service, opts.root).find((r) => r.type === m.idempotency!.storedAs && r.id === id) as Record<string, unknown> | undefined;
+    if (prior) {
+      if (m.idempotency.conflict && prior.requestHash !== undefined && prior.requestHash !== signature) return vendorError(m, m.idempotency.conflict);
+      const answer = prior.response as { status: number; body?: unknown; text?: string; contentType?: string };
+      // a streamed answer replays as the stream it was; a record kept before text was kept replays its JSON
+      return answer.text !== undefined ? new Response(answer.text, { status: answer.status, headers: { 'content-type': answer.contentType ?? 'application/json' } }) : Response.json(answer.body, { status: answer.status });
+    }
+    const response = await next();
+    if (m.idempotency.onlySuccess && (response.status < 200 || response.status >= 300)) return response;
+    const contentType = response.headers.get('content-type') ?? 'application/json';
+    const text = await response.clone().text();
+    await applyTwinWrite(m.service, { operation: 'idempotency.record', subjectType: m.idempotency.storedAs, subjectId: id, fields: { response: { status: response.status, text, contentType }, requestHash: signature }, occurredAt: (opts.clock ?? worldNow)(), actor: { kind: 'system' } }, opts.root);
+    return response;
+  }
+}
+
+/** A semantics context for a request no surface operation names: another wire's (GraphQL) resolvers
+ *  get the same interface as a handler, named by the operation id the wire gives. */
+export function semanticsContext(m: DerivedManifest, request: Request, operation: DerivedOperation, scope: CoreScope = {}): Promise<SemanticsContext> {
+  return contextFor(m, { request, operation, params: {} }, scope);
+}