@volter/world-core 2.0.37 → 3.0.0

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

@@ -0,0 +1,13 @@
+import { type DerivedManifest, type VendorManifest } from './derived-core.js';
+import type { DerivedSurface } from './derived.js';
+import type { StateSystemAdapters } from './state-system.js';
+/** A derived pack's adapters, from its manifest and its generated surface. */
+export declare function deriveStateSystem(manifest: DerivedManifest, surface: DerivedSurface, lanes?: Record<string, {
+    manifest: DerivedManifest;
+    surface: DerivedSurface;
+}>): StateSystemAdapters;
+/** A vendor of lanes' adapters: one state system over every lane's surface (the lanes keep the vendor's one store). */
+export declare function deriveVendorStateSystem(vendor: VendorManifest, lanes: Record<string, {
+    manifest: DerivedManifest;
+    surface: DerivedSurface;
+}>): StateSystemAdapters;

package/dist/src/derived-real.js

@@ -0,0 +1,518 @@
+import { aliasesFrom, parentEntries, readParentTreeMap, readTree } from "./log.js";
+import { storedType } from "./derived-core.js";
+import { verifyEvent } from "./events.js";
+import { hashFieldValue } from "./hash.js";
+import { readResourceBlob } from "./resource-blob.js";
+import { RefusedWriteError } from "./head.js";
+import { observeResources } from "./observe.js";
+/** A JSON path's value: `a.b`, `a[0].b`, `$body.a` (the leading `$body.` read as the root). */
+function at(value, path) {
+    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[part];
+    }
+    return cur;
+}
+const object = (v) => (v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined);
+const parse = (r) => { 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, schema) {
+    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) {
+    const out = [];
+    const walk = (v, path) => {
+        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, body) {
+    let found;
+    const walk = (v, path) => {
+        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, resolve) {
+    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, files, ctx) {
+    const boundary = `----volter${hashFieldValue({ body, files }).slice(0, 24)}`;
+    const chunks = [];
+    const text = (t) => { 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, body) {
+    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, input) {
+    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) {
+    return async (execute, group, ctx) => {
+        const first = group[0];
+        const input = (first.input ?? {});
+        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) => { for (const t of types) {
+            const r = ctx.resolve(t, v);
+            if (r !== v)
+                return r;
+        } return v; };
+        let method;
+        let path;
+        let body;
+        let op;
+        if (input.graphql) {
+            const gql = m.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) ?? {}) };
+            const queried = { ...(object(input.query) ?? {}) };
+            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) => [params, queried, object(sentBody)].find((o) => o !== undefined && typeof o[n] === 'string');
+                if (!names.every((n) => where(n)))
+                    continue;
+                const local = decl.key.replace(/\{([^}]+)\}/g, (_, n) => 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) => encodeURIComponent(resolve(String(params[name] ?? ''))));
+            const query = new URLSearchParams(Object.entries(queried).flatMap(([k, v]) => (Array.isArray(v) ? v : [v]).map((x) => [k, resolve(String(x))])));
+            if ([...query].length)
+                path += `?${query}`;
+            body = sentBody === undefined ? undefined : resolvedDeep(sentBody, resolve);
+        }
+        const files = Array.isArray(input.files) ? input.files : [];
+        // 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 } : asCame && typeof asCame.$base64 === 'string' ? { body: new Uint8Array(Buffer.from(asCame.$base64, 'base64')) } : undefined;
+        const sent = 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 = { ...(object(input.headers) ?? {}), ...(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 = resource ? m.resources[resource] : undefined;
+        const idOf = (o, d) => { 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 = [];
+        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, resource, params, ctx) {
+    const decl = m.resources[resource];
+    if (!decl || (!decl.number && !decl.parent?.where))
+        return;
+    const tree = readTree(ctx.service, ctx.root);
+    const landed = readParentTreeMap(ctx.service, ctx.root);
+    const vendorCopy = (type, local) => {
+        if (!local)
+            return undefined;
+        const id = ctx.resolve(type, String(local.id));
+        return id === String(local.id) ? undefined : landed.get(`${type}:${id}`)?.fields;
+    };
+    const fill = (template) => template.replace(/\{([^}]+)\}/g, (_, n) => 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)]);
+    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, parsed) {
+    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') : Array.isArray(at(parsed, 'results')) ? at(parsed, 'results') : [];
+    return list.map(object).filter((x) => x !== undefined);
+}
+function refreshOf(units, service) {
+    return async (execute, opts) => {
+        const observed = [];
+        const complete = [];
+        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, seen = new Set()) => { 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 = { ...limit };
+                    for (let taken = 0;;) {
+                        const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n) => 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) ?? []).map((x) => object(x)).filter((x) => 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 });
+                        }
+                        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, fields) {
+    if (decl.key) {
+        let missing = false;
+        const id = decl.key.replace(/\{([^}]+)\}/g, (_, n) => { 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, root, units, observed) {
+    const entries = parentEntries(service, root);
+    const aliases = aliasesFrom(entries);
+    const tree = readParentTreeMap(service, root);
+    const pending = new Map();
+    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) => {
+        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) => 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, decl, type) {
+    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 } : {}) };
+        }
+    }
+    const pattern = /^(.+)\.(created|updated|deleted)$/.exec(type);
+    const r = pattern ? resourceOf(m, pattern[1]) : undefined;
+    return r ? { resource: r, ...(pattern[2] === 'deleted' ? { deleted: true } : {}) } : undefined;
+}
+/** A version older than the held one: numbers as numbers ("9" before "10"), timestamps as instants, else as text. */
+function older(theirs, held) {
+    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, decl, service) {
+    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]);
+        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;
+        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).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, ...(found.deleted ? { deleted: true } : {}) }], ctx.root !== undefined ? { root: ctx.root } : {});
+            break;
+        }
+        return Response.json({ received: true });
+    };
+}
+function adaptersOf(units, service, ingest) {
+    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, surface, lanes = {}) {
+    // 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, lanes) {
+    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/dist/src/derived.d.ts

@@ -1,3 +1,4 @@
+import type { WebSocketUpgrade } from './serve-http.js';
 /** The slice of a generated surface the dispatch reads. */
 export type DerivedOperation = {
     id: string;
@@ -11,6 +12,10 @@ 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 */
@@ -21,6 +26,24 @@ export type DerivedOperation = {
     };
     /** 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. */
@@ -36,6 +59,13 @@ export type DerivedCall = {
     operation: DerivedOperation;
     params: Record<string, string>;
 };
+export declare function bodyTextOf(request: Request): Promise<string>;
+/** The body's text, as JSON, or undefined when it is not JSON; the parse is kept for the first taker. */
+export declare function checkJsonBody(request: Request): Promise<boolean>;
+/** The guard's parse of this request's body, taken once (a clone of a tagged request shares its key). */
+export declare function takeParsedBody(request: Request): {
+    value: unknown;
+} | undefined;
 export type DerivedHandler = (call: DerivedCall) => Promise<Response>;
 /** What the derived core made of an operation: an answer, or why it cannot model it. */
 export type DerivedCoreOutcome = {
@@ -58,7 +88,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>;
 };
 type Route = {
     operation: DerivedOperation;
@@ -73,10 +103,14 @@ export declare function matchOperation(routes: Map<string, Route[]>, method: str
     params: Record<string, string>;
 } | undefined;
 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 declare 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 declare function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch;
 export {};