@volter/world-core 2.0.37 → 3.0.1

package/src/derived-real.ts

@@ -0,0 +1,434 @@
+// THE REAL-SYSTEM ADAPTERS, DERIVED (docs/contributing/architecture.md, "The real-system adapters"): a pack's perform,
+// refresh and ingest made by the kernel from its manifest and its generated surface, so no pack writes adapter code.
+// They run over the kernel executor (`RemoteExecute`), which applies the sealed credential; the credential never
+// reaches here, only its keyed fingerprint (`PerformContext.credential`, for the idempotency key).
+import type { TwinAction } from './actions.ts';
+import { aliasesFrom, parentEntries, readParentTreeMap, readTree } from './log.ts';
+import { storedType, type DerivedManifest, type IngestDecl, type ResourceDecl, type VendorManifest } from './derived-core.ts';
+import type { DerivedOperation, DerivedSurface } from './derived.ts';
+import { verifyEvent, type EventScheme } from './events.ts';
+import { hashFieldValue } from './hash.ts';
+import { readResourceBlob } from './resource-blob.ts';
+import { RefusedWriteError, type PerformAction, type PerformContext, type PushOutcome } from './head.ts';
+import { observeResources, type Completed, type ObservedResource } from './observe.ts';
+import type { RemoteExecute, RemoteExecuteResponse } from './remote-execute.ts';
+import type { StateSystemAdapters } from './state-system.ts';
+
+type Unit = { manifest: DerivedManifest; surface: DerivedSurface; lane?: string };
+type Row = Record<string, unknown>;
+
+/** A JSON path's value: `a.b`, `a[0].b`, `$body.a` (the leading `$body.` read as the root). */
+function at(value: unknown, path: string): unknown {
+  let cur = value;
+  for (const part of path.replace(/^\$body\.?/, '').split(/\.|\[(\d+)\]/).filter((p) => p !== undefined && p !== '')) {
+    if (cur === null || typeof cur !== 'object') return undefined;
+    cur = (cur as Row)[part];
+  }
+  return cur;
+}
+const object = (v: unknown): Row | undefined => (v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Row) : undefined);
+const parse = (r: RemoteExecuteResponse): unknown => { try { return r.body ? JSON.parse(r.body) : undefined; } catch { return r.body; } };
+
+/** The manifest's resource a surface schema answers (the operation's `answers.resource` is the spec's schema name). */
+function resourceOf(m: DerivedManifest, schema: string | undefined): string | undefined {
+  if (!schema) return undefined;
+  if (m.resources[schema]) return schema;
+  const lower = schema.toLowerCase();
+  return Object.keys(m.resources).find((r) => r.toLowerCase() === lower || storedType(m, r).toLowerCase() === lower);
+}
+
+/** The error template's fixed leaves (Slack's `ok: false`): an answer holding them all is the vendor's refusal, whatever
+ *  its status (a vendor that answers its errors 200). */
+function refusalShape(m: DerivedManifest): Array<[string, unknown]> {
+  const out: Array<[string, unknown]> = [];
+  const walk = (v: unknown, path: string): void => {
+    if (typeof v === 'string' && /\{\w+\}/.test(v)) return;
+    const o = object(v);
+    if (o) { for (const [k, x] of Object.entries(o)) walk(x, path ? `${path}.${k}` : k); return; }
+    if (path) out.push([path, v]);
+  };
+  walk(m.error, '');
+  return out;
+}
+/** The words of a refusal, at the template's `{message}` (else `{code}`) place. */
+function refusalWords(m: DerivedManifest, body: unknown): string {
+  let found: string | undefined;
+  const walk = (v: unknown, path: string): void => {
+    if (typeof v === 'string' && (v.includes('{message}') || (found === undefined && v.includes('{code}')))) { const said = at(body, path); if (said !== undefined) found = String(said); return; }
+    const o = object(v);
+    if (o) for (const [k, x] of Object.entries(o)) walk(x, path ? `${path}.${k}` : k);
+  };
+  walk(m.error, '');
+  return found ?? (typeof body === 'string' ? body : JSON.stringify(body ?? null)).slice(0, 300);
+}
+
+/** Every string in a body that names a subject the vendor knows by another id, as the vendor names it. */
+function resolvedDeep(value: unknown, resolve: (v: string) => string): unknown {
+  if (typeof value === 'string') return resolve(value);
+  if (Array.isArray(value)) return value.map((v) => resolvedDeep(v, resolve));
+  const o = object(value);
+  return o ? Object.fromEntries(Object.entries(o).map(([k, v]) => [k, resolvedDeep(v, resolve)])) : value;
+}
+
+/** A multipart body: the recorded fields, then each recorded file part read back from the World's blob store. */
+async function multipart(body: unknown, files: Row[], ctx: PerformContext): Promise<{ body: Uint8Array; type: string }> {
+  const boundary = `----volter${hashFieldValue({ body, files }).slice(0, 24)}`;
+  const chunks: Uint8Array[] = [];
+  const text = (t: string): void => { chunks.push(new TextEncoder().encode(t)); };
+  for (const [k, v] of Object.entries(object(body) ?? {})) if (v !== undefined && v !== null) text(`--${boundary}\r\ncontent-disposition: form-data; name="${k}"\r\n\r\n${typeof v === 'object' ? JSON.stringify(v) : String(v)}\r\n`);
+  for (const f of files) {
+    const bytes = await readResourceBlob(ctx.service ?? '', String(f.blob), ctx.root);
+    if (!bytes) throw new Error(`the recorded file ${String(f.name)} is not in the World's blob store (${String(f.blob)})`);
+    text(`--${boundary}\r\ncontent-disposition: form-data; name="${String(f.field)}"; filename="${String(f.name)}"\r\n${f.type ? `content-type: ${String(f.type)}\r\n` : ''}\r\n`);
+    chunks.push(bytes);
+    text('\r\n');
+  }
+  text(`--${boundary}--\r\n`);
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+  let at = 0;
+  for (const c of chunks) { out.set(c, at); at += c.length; }
+  return { body: out, type: `multipart/form-data; boundary=${boundary}` };
+}
+
+/** The body as the operation's encoding sends it. */
+function encode(op: DerivedOperation, body: unknown): { body?: string; type?: string } {
+  if (body === undefined || op.bodyEncoding === 'none') return {};
+  if (op.bodyEncoding === 'form') {
+    const form = new URLSearchParams();
+    for (const [k, v] of Object.entries(object(body) ?? {})) if (v !== undefined && v !== null) form.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
+    return { body: form.toString(), type: 'application/x-www-form-urlencoded' };
+  }
+  return { body: JSON.stringify(body), type: 'application/json' };
+}
+
+/** The unit an entry was written through: its recorded lane, else the one whose surface names its operation. */
+function unitOf(units: Unit[], input: Row): Unit | undefined {
+  const id = input.operationId;
+  return (typeof input.lane === 'string' ? units.find((u) => u.lane === input.lane) : undefined)
+    ?? units.find((u) => u.surface.operations.some((o) => o.id === id))
+    ?? (input.graphql ? units[0] : undefined);
+}
+
+function performOf(units: Unit[]): PerformAction {
+  return async (execute: RemoteExecute, group: TwinAction[], ctx: PerformContext): Promise<PushOutcome> => {
+    const first = group[0]!;
+    const input = (first.input ?? {}) as Row;
+    const unit = unitOf(units, input);
+    if (!unit) throw new RefusedWriteError('vendor', `the write records no operation of the vendor's surface (${String(input.operationId ?? 'none')})`, first.id);
+    const { manifest: m, surface } = unit;
+    // ids the World minted are sent as the vendor's: every stored type's adopted aliases, tried in turn
+    const types = [...new Set(Object.keys(m.resources).map((r) => storedType(m, r)))];
+    const resolve = (v: string): string => { for (const t of types) { const r = ctx.resolve(t, v); if (r !== v) return r; } return v; };
+    let method: string; let path: string; let body: unknown; let op: DerivedOperation | undefined;
+    if (input.graphql) {
+      const gql = (m as { graphql?: { paths: string[] } }).graphql;
+      method = 'POST'; path = gql?.paths[0] ?? '/graphql'; body = resolvedDeep(input.graphql, resolve);
+    } else {
+      op = surface.operations.find((o) => o.id === input.operationId)!;
+      method = op.method.toUpperCase();
+      const params = { ...((object(input.path) ?? {}) as Record<string, string>) };
+      const queried = { ...((object(input.query) ?? {}) as Record<string, string | string[]>) };
+      const sentBody = input.body === undefined ? undefined : object(input.body) ? { ...object(input.body)! } : input.body;
+      // a subject named by its key's parts (Slack's message: its `channel` and its `ts`): the parts the request sends,
+      // resolved as one id and sent as the vendor's parts
+      for (const [resource, decl] of Object.entries(m.resources)) {
+        if (!decl.key) continue;
+        const names = [...decl.key.matchAll(/\{([^}]+)\}/g)].map((x) => x[1]!);
+        const where = (n: string): Record<string, unknown> | undefined => [params, queried, object(sentBody)].find((o) => o !== undefined && typeof o[n] === 'string') as Record<string, unknown> | undefined;
+        if (!names.every((n) => where(n))) continue;
+        const local = decl.key.replace(/\{([^}]+)\}/g, (_, n: string) => String(where(n)![n]));
+        const vendorId = ctx.resolve(storedType(m, resource), local);
+        if (vendorId === local) continue;
+        const parts = new RegExp(`^${decl.key.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '(.+?)')}$`).exec(vendorId);
+        if (parts) names.forEach((n, i) => { where(n)![n] = parts[i + 1]!; });
+      }
+      if (op.resource && ctx.service !== undefined) vendorFieldParams(m, op.resource, params, ctx);
+      path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, name: string) => encodeURIComponent(resolve(String(params[name] ?? ''))));
+      const query = new URLSearchParams(Object.entries(queried).flatMap(([k, v]) => (Array.isArray(v) ? v : [v]).map((x): [string, string] => [k, resolve(String(x))])));
+      if ([...query].length) path += `?${query}`;
+      body = sentBody === undefined ? undefined : resolvedDeep(sentBody, resolve);
+    }
+    const files = Array.isArray(input.files) ? (input.files as Row[]) : [];
+    // a body recorded as it came (not JSON) goes as it came
+    const asCame = object(input.body);
+    const raw = asCame && typeof asCame.$text === 'string' ? { body: asCame.$text as string } : asCame && typeof asCame.$base64 === 'string' ? { body: new Uint8Array(Buffer.from(asCame.$base64 as string, 'base64')) } : undefined;
+    const sent: { body?: string | Uint8Array; type?: string } = raw ? { ...raw, ...(typeof input.contentType === 'string' ? { type: input.contentType } : {}) }
+      : files.length ? await multipart(body, files, ctx) : op ? encode(op, body) : { body: JSON.stringify(body), type: 'application/json' };
+    const headers: Record<string, string> = { ...((object(input.headers) ?? {}) as Record<string, string>), ...(sent.type ? { 'content-type': sent.type } : {}) };
+    // a retried deploy makes nothing twice, and two Worlds deploying into one account never collide
+    if (m.idempotency) headers[m.idempotency.header] = hashFieldValue({ credential: ctx.credential ?? '', entry: first.id });
+    const answer = await execute({ method, path, headers, ...(sent.body !== undefined ? { body: sent.body } : {}) });
+    const parsed = parse(answer);
+    const shape = refusalShape(m);
+    const refused = answer.status >= 400 || (shape.length > 0 && shape.every(([p, v]) => at(parsed, p) === v));
+    if (answer.status === 408 || answer.status === 429 || answer.status >= 500) throw new Error(`${answer.status}: ${refusalWords(m, parsed)}${answer.headers['retry-after'] ? ` (retry after ${answer.headers['retry-after']}s)` : ''}`);
+    if (refused) throw new RefusedWriteError('vendor', `${answer.status >= 400 ? answer.status : 400}: ${refusalWords(m, parsed)}`, first.id);
+    // the subject the answer is: under the operation's key, inside the success envelope when the vendor has one
+    const key = op?.answers?.key;
+    const obj = object(key ? at(parsed, key) : parsed) ?? object(parsed) ?? {};
+    // the answered resource: the spec's schema name, else the envelope key the answer is under (Slack's `channel`,
+    // `message`), when the manifest has a resource of that name
+    const answerKey = op?.answers?.key;
+    const resource = resourceOf(m, op?.answers?.resource) ?? (answerKey && m.resources[answerKey] ? answerKey : undefined);
+    const decl: ResourceDecl | undefined = resource ? m.resources[resource] : undefined;
+    const idOf = (o: Row | undefined, d: ResourceDecl | undefined): string | undefined => { const v = o?.[d?.idAs ?? 'id']; return typeof v === 'string' ? v : undefined; };
+    // the group's entry the answer is: of the answered resource's stored type (a cascade writes children first), else
+    // the last; a delete answers its subject's own vendor id
+    const answered = resource ? [...group].reverse().find((e) => e.subject.type === storedType(m, resource)) : undefined;
+    const primary = answered ?? group.at(-1)!;
+    // an answer about a subject no entry of the group is (Slack's conversations.join answers the channel; the group is
+    // the membership and its channel_join message) gives no entry its id or its fields: each settles deployed with no
+    // vendor id, and refresh adopts it ("Perform", step 2)
+    if (resource && !answered) return { externalId: '', actionId: primary.id };
+    const deleted = primary.fields?.deleted === true;
+    // a keyed subject's id is its key filled from the answer (its envelope's fields, Slack's `channel` and `ts`, among them)
+    const keyed = decl?.key ? decl : Object.entries(m.resources).find(([r]) => storedType(m, r) === primary.subject.type)?.[1];
+    const externalId = deleted ? ctx.resolve(primary.subject.type, primary.subject.id)
+      : keyed?.key ? storedIdOf(keyed, { ...(object(parsed) ?? {}), ...obj }) ?? '' : idOf(obj, decl) ?? '';
+    const also: Array<{ actionId: string; externalId: string }> = [];
+    for (const [companion, where] of Object.entries(decl?.companions ?? {})) {
+      const id = at(parsed, where) ?? at(obj, where);
+      const entry = group.find((e) => e !== primary && e.subject.type === storedType(m, companion));
+      if (entry && typeof id === 'string') also.push({ actionId: entry.id, externalId: id });
+    }
+    return { externalId, actionId: primary.id, data: obj, ...(also.length ? { also } : {}) };
+  };
+}
+
+/** Path parameters that name a subject by a field rather than its id, sent as the vendor's value of that field, read
+ *  from the adopted landed copy ("Perform", step 1): a parent found by `parent.where` (a repository addressed as
+ *  `{owner}/{repo}`), and a subject named by the number it counts per parent (`number`, an issue's `issue_number`).
+ *  A subject the vendor has not given another id keeps the World's values, which are then the vendor's. */
+function vendorFieldParams(m: DerivedManifest, resource: string, params: Record<string, string>, ctx: PerformContext): void {
+  const decl = m.resources[resource];
+  if (!decl || (!decl.number && !decl.parent?.where)) return;
+  const tree = readTree(ctx.service!, ctx.root) as Row[];
+  const landed = readParentTreeMap(ctx.service!, ctx.root);
+  const vendorCopy = (type: string, local: Row | undefined): Row | undefined => {
+    if (!local) return undefined;
+    const id = ctx.resolve(type, String(local.id));
+    return id === String(local.id) ? undefined : (landed.get(`${type}:${id}`)?.fields as Row | undefined);
+  };
+  const fill = (template: string): string => template.replace(/\{([^}]+)\}/g, (_, n: string) => params[n] ?? '');
+  // the parent as the World stores it, read before any parameter becomes the vendor's
+  const parent = decl.parent;
+  const parentType = parent ? storedType(m, parent.resource) : undefined;
+  const where = Object.entries(parent?.where ?? {}).map(([field, template]) => [field, template, fill(template)] as const);
+  const localParent = where.length ? tree.find((r) => r.type === parentType && where.every(([f, , v]) => String(r[f]) === v)) : undefined;
+  const parentId = parent ? (where.length ? (localParent ? String(localParent.id) : undefined) : parent.params ? fill(parent.value ?? parent.params.map((p) => `{${p}}`).join('/')) : parent.param !== undefined ? params[parent.param] : undefined) : undefined;
+  if (decl.number && !decl.key) {
+    const type = storedType(m, resource);
+    const name = Object.keys(params).at(-1);
+    const field = decl.number.field;
+    const local = name === undefined ? undefined : tree.find((r) => r.type === type && String(r[field]) === params[name] && (!parent || String(r[parent.field]) === parentId));
+    const copy = vendorCopy(type, local);
+    if (name !== undefined && copy?.[field] !== undefined) params[name] = String(copy[field]);
+  }
+  const parentCopy = vendorCopy(parentType ?? '', localParent);
+  if (parentCopy) for (const [field, template] of where) { const one = /^\{([^}]+)\}$/.exec(template); if (one && parentCopy[field] !== undefined) params[one[1]!] = String(parentCopy[field]); }
+}
+
+/** The items of a list's answer: under the operation's key, else the answer when it is a list. */
+function itemsOf(op: DerivedOperation, parsed: unknown): Row[] {
+  const v = op.answers?.key ? at(parsed, op.answers.key) : parsed;
+  const list = Array.isArray(v) ? v : Array.isArray(at(parsed, 'data')) ? (at(parsed, 'data') as unknown[]) : Array.isArray(at(parsed, 'results')) ? (at(parsed, 'results') as unknown[]) : [];
+  return list.map(object).filter((x): x is Row => x !== undefined);
+}
+
+function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapters['refresh']> {
+  return async (execute, opts) => {
+    const observed: ObservedResource[] = [];
+    const complete: Completed[] = [];
+    for (const { manifest: m, surface } of units) {
+      // parents before children, however deep
+      const scoped = Object.entries(m.resources).filter(([, d]) => d.refresh && !('none' in d.refresh));
+      const depth = (r: string, seen = new Set<string>()): number => { const p = m.resources[r]?.parent?.resource; return p && !seen.has(p) ? 1 + depth(p, seen.add(r)) : 0; };
+      const order = scoped.sort(([a], [b]) => depth(a) - depth(b));
+      for (const [resource, decl] of order) {
+        const scope = decl.refresh!;
+        const opId = 'list' in scope ? scope.list : 'get' in scope ? scope.get : '';
+        const op = surface.operations.find((o) => o.id === opId);
+        if (!op) throw new Error(`${m.vendor}: ${resource}'s refresh names ${opId}, no operation of the surface`);
+        const type = storedType(m, resource);
+        const parents = decl.parent ? [...new Set(observed.filter((o) => o.type === storedType(m, decl.parent!.resource)).map((o) => o.id))] : [undefined];
+        let whole = 'list' in scope && scope.complete !== false;
+        for (const parent of parents) {
+          const limit = m.list?.limit && (op.query ?? []).some((q) => q.name === m.list!.limit.param) ? { [m.list.limit.param]: String(m.list.limit.max) } : {};
+          let page: Record<string, string> = { ...limit };
+          for (let taken = 0; ;) {
+            const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n: string) => encodeURIComponent(n === decl.parent?.param ? String(parent) : ''));
+            // a parent the operation names in its query, not its path (Slack's conversations.history `channel`)
+            const byQuery = decl.parent?.param && parent !== undefined && !op.path.includes(`{${decl.parent.param}}`) ? { [decl.parent.param]: String(parent) } : {};
+            const q = new URLSearchParams({ ...page, ...byQuery });
+            const answer = await execute({ method: op.method.toUpperCase(), path: [...q].length ? `${path}?${q}` : path });
+            if (answer.status === 401 || answer.status === 403) throw new Error(`${answer.status}: the vendor refused the root's credential; nothing folded`);
+            if (answer.status === 429) throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
+            if (answer.status >= 400) throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);
+            const parsed = parse(answer);
+            const items = 'get' in scope ? [object(op.answers?.key ? at(parsed, op.answers.key) : parsed) ?? {}]
+              : 'items' in scope && scope.items ? ((at(parsed, scope.items) as unknown[] | undefined) ?? []).map((x) => object(x)).filter((x): x is Row => x !== undefined) : itemsOf(op, parsed);
+            for (const item of items) {
+              const fields = { ...item, ...(decl.parent && parent !== undefined ? { [decl.parent.field]: parent } : {}) };
+              const id = storedIdOf(decl, fields);
+              if (id === undefined) continue;
+              observed.push({ type, id, fields: fields as ObservedResource['fields'] });
+            }
+            taken += items.length;
+            if ('get' in scope) break;
+            if (taken >= 10_000) { whole = false; break; }
+            // the next page by the manifest's list model. The list is whole only where its end shows: a cursor model
+            // gives no next cursor (a short page may still name one), or a page is empty or shorter than the limit
+            // asked; a list the twin cannot page on, or whose page size it does not know, is not known whole.
+            if (m.list?.cursor) {
+              const next = at(parsed, 'next_cursor') ?? at(parsed, 'response_metadata.next_cursor');
+              if (!next) break;
+              page = { ...page, [m.list.cursor.param]: String(next) };
+              continue;
+            }
+            const size = Number(limit[m.list?.limit.param ?? ''] ?? 0);
+            if (!items.length || (size && items.length < size)) break;
+            if (!size) { whole = false; break; }
+            const last = items.at(-1)![decl.idAs ?? 'id'];
+            if (m.list?.after) page = { ...page, [m.list.after]: String(last) };
+            else if (m.list?.page) page = { ...page, [m.list.page.param]: String(Number(page[m.list.page.param] ?? 1) + 1) };
+            else if (m.list?.offset) page = { ...page, [m.list.offset.param]: String(taken) };
+            else { whole = false; break; }
+          }
+        }
+        // a type under a parent is whole only for the parents observed: what it held under another parent stands. A root
+        // scoped to one resource (`RootConfig.scope`, GitHub's `repos/o/r`) lists only what is under it, so a type with no
+        // parent is never the account's whole list there
+        if (whole && !decl.parent && !opts.scope) complete.push(type);
+        else if (whole && parents.length) complete.push({ type, field: decl.parent!.field, within: parents.map(String) });
+      }
+    }
+    adopt(service, opts.root, units, observed);
+    return observeResources(service, observed, { ...(opts.root !== undefined ? { root: opts.root } : {}), complete });
+  };
+}
+
+/** A vendor's subject's stored id: its key template filled from its fields (its parent's among them), else its id
+ *  field. Undefined when the subject names none. */
+function storedIdOf(decl: ResourceDecl, fields: Row): string | undefined {
+  if (decl.key) {
+    let missing = false;
+    const id = decl.key.replace(/\{([^}]+)\}/g, (_, n: string) => { const v = fields[n]; if (typeof v !== 'string' && typeof v !== 'number') missing = true; return String(v ?? ''); });
+    return missing ? undefined : id;
+  }
+  const id = fields[decl.idAs ?? 'id'];
+  return typeof id === 'string' || typeof id === 'number' ? String(id) : undefined;
+}
+
+/** Adoption ("Refresh"): an observation whose vendor id the World holds under no subject, matching a subject a deploy
+ *  settled with no vendor id (the same type and parent, and equal on the resource's `alternateKeys`, else the only
+ *  such subject under that parent), is that subject: it lands as its alias instead of a second subject beside it. */
+function adopt(service: string, root: string | undefined, units: Unit[], observed: ObservedResource[]): void {
+  const entries = parentEntries(service, root);
+  const aliases = aliasesFrom(entries);
+  const tree = readParentTreeMap(service, root);
+  const pending = new Map<string, Array<{ id: string; fields: Record<string, unknown> }>>();
+  for (const e of entries) {
+    if (e.receipt?.status !== 'deployed' || e.receipt.externalId || e.landsId === undefined || e.aliasOf !== undefined) continue;
+    const key = `${e.subject.type}:${e.subject.id}`;
+    const held = tree.get(key);
+    if (aliases.has(key) || !held || held.fields.deleted === true) continue;
+    const list = pending.get(e.subject.type) ?? [];
+    if (!list.some((p) => p.id === e.subject.id)) list.push({ id: e.subject.id, fields: held.fields });
+    pending.set(e.subject.type, list);
+  }
+  if (!pending.size) return;
+  const declOf = (type: string): { m: DerivedManifest; decl: ResourceDecl } | undefined => {
+    for (const u of units) { const hit = Object.entries(u.manifest.resources).find(([r]) => storedType(u.manifest, r) === type); if (hit) return { m: u.manifest, decl: hit[1] }; }
+    return undefined;
+  };
+  for (const o of observed) {
+    const pool = pending.get(o.type);
+    if (!pool?.length || tree.has(`${o.type}:${o.id}`)) continue;
+    const { m, decl } = declOf(o.type) ?? {};
+    const parentField = decl?.parent?.field;
+    // a local child names its parent by the parent's local id, which the parent's adoption aliased to the vendor's
+    const parentType = decl?.parent && m ? storedType(m, decl.parent.resource) : undefined;
+    const resolved = (v: unknown): string => aliases.get(`${parentType}:${String(v)}`) ?? String(v);
+    const siblings = pool.filter((p) => parentField === undefined || resolved(p.fields[parentField]) === String(o.fields[parentField]));
+    const keys = decl?.alternateKeys ?? [];
+    const match = keys.length ? siblings.filter((p) => keys.every((k) => p.fields[k] !== undefined && p.fields[k] === o.fields[k])) : siblings.length === 1 ? siblings : [];
+    if (match.length !== 1) continue;
+    o.adopts = match[0]!.id;
+    pool.splice(pool.indexOf(match[0]!), 1);
+    // its children, observed after it, name it by the local id this adoption aliases
+    aliases.set(`${o.type}:${o.adopts}`, o.id);
+  }
+}
+
+/** The event's resource: the declared `types`, else the manifest's events read backwards, else `<resource>.created|updated|deleted`. */
+function eventResource(m: DerivedManifest, decl: IngestDecl, type: string): { resource: string; deleted?: true } | undefined {
+  if (decl.types?.[type]) return decl.types[type];
+  for (const [operation, sent] of Object.entries(m.events?.types ?? {})) {
+    if ((Array.isArray(sent) ? sent : [sent]).includes(type)) { const r = resourceOf(m, operation.split('.')[0]); if (r) return { resource: r, ...(/\.delete/.test(operation) ? { deleted: true as const } : {}) }; }
+  }
+  const pattern = /^(.+)\.(created|updated|deleted)$/.exec(type);
+  const r = pattern ? resourceOf(m, pattern[1]) : undefined;
+  return r ? { resource: r, ...(pattern![2] === 'deleted' ? { deleted: true as const } : {}) } : undefined;
+}
+
+/** A version older than the held one: numbers as numbers ("9" before "10"), timestamps as instants, else as text. */
+function older(theirs: unknown, held: unknown): boolean {
+  if (theirs === undefined || theirs === null || held === undefined || held === null) return false;
+  const a = Number(theirs); const b = Number(held);
+  if (String(theirs).trim() !== '' && String(held).trim() !== '' && Number.isFinite(a) && Number.isFinite(b)) return a < b;
+  const ta = Date.parse(String(theirs)); const tb = Date.parse(String(held));
+  if (Number.isFinite(ta) && Number.isFinite(tb)) return ta < tb;
+  return String(theirs) < String(held);
+}
+
+function ingestOf(units: Unit[], decl: IngestDecl, service: string): NonNullable<StateSystemAdapters['ingest']> {
+  return async (request, ctx) => {
+    const body = await request.text();
+    const headers = Object.fromEntries(request.headers);
+    const now = Math.floor(Date.now() / 1000);
+    const schemes = (Array.isArray(decl.scheme) ? decl.scheme : [decl.scheme]) as EventScheme[];
+    if (!ctx.secret || !schemes.some((s) => verifyEvent(s, ctx.secret!, body, headers, { now, tolerance: 300 }))) return Response.json({ error: 'invalid signature' }, { status: 401 });
+    let event: unknown;
+    try { event = JSON.parse(body); } catch { return Response.json({ error: 'the event is not JSON' }, { status: 400 }); }
+    if (decl.handshake && Object.entries(decl.handshake.when).every(([k, v]) => at(event, k) === v)) {
+      const answer = decl.handshake.answer.startsWith('$body.') ? at(event, decl.handshake.answer) : decl.handshake.answer;
+      return new Response(typeof answer === 'string' ? answer : JSON.stringify(answer), { status: 200 });
+    }
+    const named = [decl.type.header ? request.headers.get(decl.type.header) : decl.type.body ? at(event, decl.type.body) : undefined, decl.type.action ? at(event, decl.type.action) : undefined].filter((x) => typeof x === 'string' && x !== '');
+    const type = named.join('.');
+    for (const { manifest: m } of units) {
+      const found = eventResource(m, decl, type);
+      if (!found) continue;
+      const item = object(at(event, decl.object));
+      const d = m.resources[found.resource]!;
+      const id = item ? storedIdOf(d, item) : undefined;
+      if (!item || id === undefined) break;
+      const stored = storedType(m, found.resource);
+      // an event older than the root's copy folds nothing
+      const held = d.version ? (readTree(service, ctx.root) as Row[]).find((r) => r.type === stored && r.id === String(id)) : undefined;
+      if (held && d.version && older(item[d.version], held[d.version])) break;
+      observeResources(service, [{ type: stored, id: String(id), fields: item as ObservedResource['fields'], ...(found.deleted ? { deleted: true } : {}) }], ctx.root !== undefined ? { root: ctx.root } : {});
+      break;
+    }
+    return Response.json({ received: true });
+  };
+}
+
+function adaptersOf(units: Unit[], service: string, ingest: IngestDecl | undefined): StateSystemAdapters {
+  return { perform: performOf(units), refresh: refreshOf(units, service), ...(ingest ? { ingest: ingestOf(units, ingest, service) } : {}) };
+}
+
+/** A derived pack's adapters, from its manifest and its generated surface. */
+export function deriveStateSystem(manifest: DerivedManifest, surface: DerivedSurface, lanes: Record<string, { manifest: DerivedManifest; surface: DerivedSurface }> = {}): StateSystemAdapters {
+  // a pack with an API of its own and lanes beside it (Clerk's Backend API and its Frontend API, `fapi`): one state
+  // system over its surface and each lane's
+  const units = [{ manifest, surface }, ...Object.entries(lanes).map(([lane, u]) => ({ ...u, lane }))];
+  return adaptersOf(units, manifest.service, manifest.ingest ?? units.find((u) => u.manifest.ingest)?.manifest.ingest);
+}
+
+/** A vendor of lanes' adapters: one state system over every lane's surface (the lanes keep the vendor's one store). */
+export function deriveVendorStateSystem(vendor: VendorManifest, lanes: Record<string, { manifest: DerivedManifest; surface: DerivedSurface }>): StateSystemAdapters {
+  const units = Object.entries(lanes).map(([lane, u]) => ({ ...u, lane }));
+  const service = units[0]?.manifest.service ?? vendor.vendor;
+  return adaptersOf(units, service, vendor.ingest ?? units.find((u) => u.manifest.ingest)?.manifest.ingest);
+}

package/src/derived.ts

@@ -5,6 +5,7 @@
 // existing fetch, which keeps serving everything not yet moved (and every route outside the spec, such
 // as the `/twin` door). `owners` says, per operation, which of the two serves it: the count a pack's
 // move is measured by. Workerd-clean: no fs, no clock, nothing at import.
+import type { WebSocketUpgrade } from './serve-http.ts';
 import { runWithRequestTrace } from './trace-context.ts';
 
 /** The slice of a generated surface the dispatch reads. */
@@ -20,12 +21,24 @@ export type DerivedOperation = {
   headers?: Record<string, string | null>;
   /** the status the vendor answers success with (201 for a create, 204 for an empty answer) */
   successStatus?: number;
+  /** how the spec says the request body is encoded (derive-pack: json, form, multipart, none) */
+  bodyEncoding?: string;
+  /** the success is documented with no content (a setting's update answered 200 and nothing else) */
+  emptySuccess?: boolean;
   /** a form-encoded operation's number and boolean fields, by bracket path (`items.[].quantity`, `metadata.*`) */
   scalars?: Readonly<Record<string, string | undefined>>;
   /** what the success answer is: a resource, a list of them, and the envelope key holding it */
   answers?: { resource: string; list: boolean; key?: string };
   /** the path its own server puts before it, where the operation names a server other than the surface's */
   basePath?: string;
+  /** the query's declared parameters (a strict body checks what is not one of them) */
+  query?: ReadonlyArray<{ name: string; type: string; required?: boolean }>;
+  /** the credential scopes any one of which lets a caller make the call, and the security schemes it is made with
+   *  (`anonymous` where it may also go without; absent when it takes none), from the spec's security */
+  scopes?: ReadonlyArray<string>;
+  credentials?: ReadonlyArray<string>;
+  /** the body's declared fields: name, type, and the numeric bounds the spec states (a strict body, `ctx.fields`) */
+  body?: ReadonlyArray<{ name: string; type: string; required?: boolean; minimum?: number; maximum?: number }>;
 };
 /** `basePath` is what the vendor's server URL puts before every operation path; `spanning` names the
  *  path parameters whose values may hold slashes (a git ref, a file path), which no spec says. */
@@ -33,6 +46,52 @@ export type DerivedSurface = { version: string; basePath?: string; spanning?: Re
 
 /** What a semantics handler receives: the request, the operation it matched, and its path parameters. */
 export type DerivedCall = { request: Request; operation: DerivedOperation; params: Record<string, string> };
+
+/**
+ * A request's body as text, read once per request: the dispatch reads it and tags the request with it, and every clone
+ * made from a tagged request carries the tag, so the malformed-JSON guard, the idempotency signature, the handler's
+ * context and the parameters all take the one string (a publish's body is megabytes, and each read made a copy).
+ */
+const BODY_TEXT = Symbol('volter.bodyText');
+type Tagged = Request & { [BODY_TEXT]?: string };
+function tagBody(request: Request, text: string, key: object = {}): Request {
+  const tagged = request as Tagged;
+  tagged[BODY_TEXT] = text;
+  BODY_PARSE_KEY.set(request, key);
+  const clone = request.clone.bind(request);
+  tagged.clone = () => tagBody(clone(), text, key);
+  return request;
+}
+export async function bodyTextOf(request: Request): Promise<string> {
+  const held = (request as Tagged)[BODY_TEXT];
+  return held !== undefined ? held : request.text();
+}
+
+/** The body parsed by the malformed-JSON guard, which only checks it: handed once to the handler's context (that parse
+ *  would be the same), and never shared further, so no reader sees another's changes. */
+const BODY_PARSED = new WeakMap<object, { value: unknown }>();
+/** The body's text, as JSON, or undefined when it is not JSON; the parse is kept for the first taker. */
+export async function checkJsonBody(request: Request): Promise<boolean> {
+  const text = await bodyTextOf(request);
+  if (!text) return true;
+  // a body labelled otherwise and not shaped as JSON is the form it is labelled (an OAuth token request), not bad JSON
+  if (!(request.headers.get('content-type') ?? '').includes('json') && !/^\s*[[{]/.test(text)) return true;
+  try {
+    const value = JSON.parse(text);
+    const tag = (request as Tagged)[BODY_TEXT] !== undefined ? BODY_PARSE_KEY.get(request) : undefined;
+    if (tag) BODY_PARSED.set(tag, { value });
+    return true;
+  } catch { return false; }
+}
+/** The guard's parse of this request's body, taken once (a clone of a tagged request shares its key). */
+export function takeParsedBody(request: Request): { value: unknown } | undefined {
+  const tag = BODY_PARSE_KEY.get(request);
+  const held = tag ? BODY_PARSED.get(tag) : undefined;
+  if (tag && held) BODY_PARSED.delete(tag);
+  return held;
+}
+/** One key per request as the dispatch received it, shared by every clone made from it. */
+const BODY_PARSE_KEY = new WeakMap<Request, object>();
 export type DerivedHandler = (call: DerivedCall) => Promise<Response>;
 
 /** What the derived core made of an operation: an answer, or why it cannot model it. */
@@ -50,7 +109,7 @@ export type DerivedFetchOptions = {
    *  checks, idempotent replay). */
   around?: (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;
   /** The vendor's answer for an operation nothing models: the pack's gap. */
-  gap: (request: Request, operation: DerivedOperation | undefined, reason: string) => Response;
+  gap: (request: Request, operation: DerivedOperation | undefined, reason: string) => Response | Promise<Response>;
 };
 
 class Unmodeled extends Error {}
@@ -80,7 +139,9 @@ function compile(operation: DerivedOperation, basePath: string, spanning: Readon
       }).join('');
     })
     .join('/');
-  return { operation, pattern: new RegExp(`^${body}/?$`), names, literals };
+  // a path the spec writes with its trailing slash (Django's `/persons/`) is the same path without it, as a router that
+  // takes both answers it (PostHog's `trailing_slash = r"/?"`)
+  return { operation, pattern: new RegExp(`^${body.replace(/\/$/, '')}/?$`), names, literals };
 }
 
 const compiled = new WeakMap<DerivedSurface, Map<string, Route[]>>(); // cache: compiled routes per surface; a surface is immutable generated data
@@ -126,10 +187,15 @@ export function matchOperation(routes: Map<string, Route[]>, method: string, pat
 
 export type DerivedOwner = 'handler' | 'core' | 'gap';
 
+/** The header the kernel carries a path prefix's named groups in, from routing to the call (never a client's). */
+export const PREFIX_PARAMS_HEADER = 'x-volter-path-prefix-params';
+
 export type DerivedFetch = ((request: Request) => Promise<Response>) & {
   /** Per operationId, who serves it: a semantics handler, the derived core, the pack's existing
    *  fetch while it moves, or nothing (the vendor's gap). */
   owners(): Record<string, DerivedOwner>;
+  /** The vendor's sockets (sockets.ts), for the serve seam to upgrade to, when its manifest declares any. */
+  upgrade?: WebSocketUpgrade;
 };
 
 export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
@@ -148,7 +214,11 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
       ? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, request.headers)).find(Boolean)
       : matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
     if (!matched) return fallback(request, undefined, 'no operation at this path');
-    const call: DerivedCall = { request, operation: matched.operation, params: matched.params };
+    // the body read once, as text, for everything the dispatch does with it (bodyTextOf)
+    if (request.method !== 'GET' && request.method !== 'HEAD' && request.body && !(request.headers.get('content-type') ?? '').includes('multipart')) tagBody(request, await request.clone().text());
+    // the path prefix's named groups (pack-fetch.ts, `pathPrefix`) are the call's parameters too
+    const prefixed = request.headers.get(PREFIX_PARAMS_HEADER);
+    const call: DerivedCall = { request, operation: matched.operation, params: prefixed ? { ...(JSON.parse(prefixed) as Record<string, string>), ...matched.params } : matched.params };
     const around = options.around ?? ((_c: DerivedCall, next: () => Promise<Response>) => next());
     const handler = handlers[matched.operation.id];
     if (handler) return around(call, () => handler(call));

package/src/emit.ts

@@ -6,8 +6,7 @@
 // `TwinEmitter` and registered on its `TwinPack.emitter` (same argument as `browserRouting`:
 // vendor knowledge in the descriptor, kernel stays vendor-agnostic).
 //
-// The operator surface is the PACK's bin (`world-stripe emit …`), exactly like the mirror
-// UIs — the kernel never imports packs, so `volter-twin emit <service>` only works when a
+// The operator surface is the PACK's bin (`world-stripe emit …`) — the kernel never imports packs, so `volter-twin emit <service>` only works when a
 // consumer registered the pack in-process, and otherwise fails loudly pointing at the
 // vendor bin. Unlike the twin's own background emission on state changes (fire-and-forget,
 // vendor-faithful), an explicit DELIVER is an operator asking for exactly this delivery, so