@volter/world-core 2.0.0

package/dist/src/derived-core.js

@@ -0,0 +1,782 @@
+// 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 } from "./serve.js";
+import { copyResource, ownFields, parentStamp, subjectHistory, treeChangesSince, treeStamp } from "./log.js";
+import { getActiveWorldStore } from "./world-store.js";
+import { worldNow } from "./world-clock.js";
+import { createHash } from 'node:crypto';
+import { hashFieldValue } from "./hash.js";
+import { resolveSubjectId, subjectAliases } from "./actions.js";
+import { packReferences } from "./references.js";
+import { twinPublicBase } from "./twin-fetch.js";
+/** 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, to) {
+    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, value) {
+    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);
+}
+// ── 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, scalars) {
+    const out = {};
+    for (const [rawKey, raw] of new URLSearchParams(text)) {
+        const parts = rawKey.replace(/\]/g, '').split('[');
+        const kind = scalars && scalarAt(scalars, parts);
+        const value = 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 = 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, parts) {
+    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, request, operation) {
+    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 = { ...query };
+        for (const [key, value] of form.entries()) {
+            if (typeof value === 'string') {
+                out[key] = value;
+                continue;
+            }
+            const file = value;
+            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 = 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 } : { ...query };
+}
+// ── answers ──────────────────────────────────────────────────────────────────────────────────
+const ABSENT = Symbol('absent');
+function fill(template, values, omitAbsent = false) {
+    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(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)]).filter(([, v]) => v !== ABSENT));
+    }
+    return template;
+}
+export function vendorError(manifest, e) {
+    // 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) => String(v ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+        const body = manifest.error.replace(/\{(\w+)\}/g, (_, k) => escape(values[k]));
+        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, object, id, param) {
+    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, resource) => 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();
+/** 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, type, root) {
+    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();
+        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, resource, root, opts = {}) {
+    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[k] === v));
+}
+/** The subject an item operation names: the manifest's key over the path parameters, or the last one. */
+function subjectOf(m, resource, call) {
+    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, params) {
+    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, resource, call, root) {
+    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))]);
+    const found = (r) => (where.length ? where.every(([field, v]) => String(r[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) {
+    return Object.fromEntries(Object.entries({ id: r.id, ...ownFields(r) }).filter(([k]) => !k.startsWith('_') && k !== 'updatedAt'));
+}
+function view(m, resource, r) {
+    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)).filter(([k]) => !k.startsWith('_')));
+}
+function now(m, at) {
+    return m.time === 'unix' ? Math.floor(Date.parse(at) / 1000) : at;
+}
+function applyRule(m, rule, id, values, at) {
+    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) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** The next id the manifest's template gives this resource: one past the highest it already minted. */
+function mintId(m, resource, root) {
+    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, resource, root) {
+    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, resource, body, paths, root) {
+    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, params) {
+    const raw = m.expandParam ? params[m.expandParam] : undefined;
+    return Array.isArray(raw) ? raw.map(String) : typeof raw === 'string' ? [raw] : [];
+}
+async function write(m, call, resource, id, fields, operation, params, root, occurredAt) {
+    return (await writeDetailed(m, call, resource, id, fields, operation, params, root, occurredAt)).body;
+}
+async function writeDetailed(m, call, resource, id, fields, operation, params, root, occurredAt) {
+    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, op, body) {
+    return m.success && op.answers?.key ? { ...m.success, [op.answers.key]: body } : body;
+}
+const encodeOffset = (o) => btoa(JSON.stringify({ o }));
+function decodeOffset(cursor) {
+    if (typeof cursor !== 'string' || !cursor)
+        return 0;
+    try {
+        const o = JSON.parse(atob(cursor)).o;
+        return typeof o === 'number' && o >= 0 ? o : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+let transitionObserver;
+export function observeTransitions(observer) {
+    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, decl, operationId, current, requested, id, actor = 'api') {
+    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 {};
+}
+// 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();
+function aliasesNow(service, root) {
+    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, call, root) {
+    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, fields, root) {
+    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);
+        const adopted = local === undefined ? undefined : aliases.get(`${ref.to}:${local}`);
+        if (adopted !== undefined && adopted !== local)
+            out = { ...out, ...ref.adopt(out, adopted) };
+    }
+    return out;
+}
+async function boundaryParams(m, call, root) {
+    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, call, scope = {}) {
+    const root = scope.root;
+    const at = (scope.clock ?? worldNow)();
+    const op = 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) => !parent || r[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) => ({
+        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));
+    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[parent.field] === parentId);
+                under[decl.number.field] = 1 + siblings.reduce((n, r) => Math.max(n, Number(r[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' };
+            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;
+            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) => {
+                        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 }) }) };
+            }
+            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' }), ...(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 = { ...(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 = {};
+            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, ...v }).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) {
+    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, events, operationId) {
+    const enc = new TextEncoder();
+    const framing = (operationId && m.streamFor?.[operationId]) || m.sse;
+    const frame = (e) => `${framing?.named && e.event ? `event: ${e.event}\n` : ''}data: ${JSON.stringify(e.data)}\n\n`;
+    const body = new ReadableStream({
+        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' } });
+}
+async function contextFor(m, call, scope) {
+    const root = scope.root;
+    call = adoptedPath(m, call, root);
+    const at = (scope.clock ?? worldNow)();
+    const text = await call.request.clone().text().catch(() => '');
+    let body = 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, 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),
+        rowsRaw: (resource, opts) => stored(m, resource, root, opts),
+        tree: () => twinResources(m.service, root),
+        history: (resource, id) => subjectHistory(m.service, { type: storedType(m, resource), id }, root).map((e) => ({ ...(e.operation ? { operation: e.operation } : {}), ...(e.fields ? { fields: e.fields } : {}), ...(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) => resources.filter((r) => r.type === storedType(m, resource) && r.deleted !== true);
+                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),
+    };
+}
+/** A pack's semantics handlers as the dispatch's handlers. */
+export function bindSemantics(m, handlers, scope = {}) {
+    return Object.fromEntries(Object.entries(handlers).map(([id, h]) => [id, async (call) => 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, scope = {}) {
+    const crud = new Set(['create', 'retrieve', 'list', 'update', 'delete']);
+    const owns = (o) => {
+        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) => 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, opts = {}) {
+    const finish = async (r, request) => {
+        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) => {
+        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, next) {
+        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);
+        if (prior) {
+            if (m.idempotency.conflict && prior.requestHash !== undefined && prior.requestHash !== signature)
+                return vendorError(m, m.idempotency.conflict);
+            const answer = prior.response;
+            // 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, request, operation, scope = {}) {
+    return contextFor(m, { request, operation, params: {} }, scope);
+}