@volter/world-core 3.0.37 → 3.0.39

package/dist/src/derived-real.js

@@ -1,12 +1,16 @@
+import { parseExactJson, exactInteger, compareExactNumbers } from "./exact-json.js";
 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 { readResourceBlob, writeResourceBlob } from "./resource-blob.js";
 import { RefusedWriteError } from "./head.js";
 import { observeResources } from "./observe.js";
+import { readRoot } from "./state-system.js";
 /** A JSON path's value: `a.b`, `a[0].b`, `$body.a` (the leading `$body.` read as the root). */
 function at(value, path) {
+    if (value && typeof value === 'object' && Object.hasOwn(value, path))
+        return 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')
@@ -16,20 +20,84 @@ function at(value, path) {
     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;
+const parse = (r) => {
+    if (r.body && r.body.trimStart().startsWith('<'))
+        return fromXml(r.body);
+    try {
+        return r.body ? parseExactJson(r.body) : undefined;
+    }
+    catch {
+        return r.body;
+    }
+};
+/** Link header relations and extension parameters, with commas and escapes inside quoted values preserved. */
+function linkRelations(value) {
+    const links = [];
+    let rest = value.trim();
+    while (rest) {
+        const target = /^<([^<>]+)>/.exec(rest);
+        if (!target)
+            throw new Error('refresh continuation has a malformed Link header; nothing folded');
+        rest = rest.slice(target[0].length).trimStart();
+        const params = {};
+        while (rest.startsWith(';')) {
+            const param = /^;\s*([\w!#$%&'*+.^`|~-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s;,]+))\s*/.exec(rest);
+            if (!param)
+                throw new Error('refresh continuation has a malformed Link parameter; nothing folded');
+            const name = param[1].toLowerCase();
+            if (name in params)
+                throw new Error('refresh continuation repeats a Link parameter; nothing folded');
+            params[name] = param[2] !== undefined ? param[2].replace(/\\(.)/g, '$1') : param[3];
+            rest = rest.slice(param[0].length);
+        }
+        links.push({ url: target[1], params });
+        if (rest && !rest.startsWith(','))
+            throw new Error('refresh continuation has a malformed Link separator; nothing folded');
+        if (rest) {
+            rest = rest.slice(1).trimStart();
+            if (!rest)
+                throw new Error('refresh continuation ends with a Link separator; nothing folded');
+        }
+    }
+    return links;
+}
+/** An XML answer (S3's lists: ListObjectsV2, ListMultipartUploads, ListParts) read as JSON, so a refresh scope names its
+ *  items as it does a JSON answer's (`ListBucketResult.Contents`): an element with children is an object of them, a
+ *  child repeated a list of them, a leaf its text; attributes, declarations and comments are not read. */
+function fromXml(text) {
+    const decode = (t) => t.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n))).replace(/&amp;/g, '&');
+    const stack = [{ name: '', obj: {}, text: '', children: false }];
+    const put = (parent, name, value) => {
+        const held = parent.obj[name];
+        parent.obj[name] = held === undefined ? value : Array.isArray(held) ? [...held, value] : [held, value];
+        parent.children = true;
+    };
+    for (const m of text.matchAll(/<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<!\[CDATA\[([\s\S]*?)\]\]>|<(\/?)([A-Za-z_][\w:.-]*)[^>]*?(\/?)>|([^<]+)/g)) {
+        const top = stack.at(-1);
+        if (m[1] !== undefined)
+            top.text += m[1];
+        else if (m[5] !== undefined)
+            top.text += decode(m[5]);
+        else if (m[3] !== undefined && m[4] === '/')
+            put(top, m[3], '');
+        else if (m[3] !== undefined && m[2] !== '/')
+            stack.push({ name: m[3], obj: {}, text: '', children: false });
+        else if (m[3] !== undefined && stack.length > 1) {
+            const node = stack.pop();
+            put(stack.at(-1), node.name, node.children ? node.obj : node.text.trim());
+        }
+    }
+    return stack[0].obj;
 }
-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);
+    const normalized = (name) => name.replace(/_/g, '').toLowerCase();
+    const lower = normalized(schema);
+    return Object.keys(m.resources).find((r) => normalized(r) === lower || normalized(storedType(m, r)) === 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). */
@@ -68,6 +136,12 @@ function refusalWords(m, body) {
     walk(m.error, '');
     return found ?? (typeof body === 'string' ? body : JSON.stringify(body ?? null)).slice(0, 300);
 }
+/** Whether an answer is the vendor's refusal whatever its status: it holds every fixed leaf of the error template (Slack's
+ *  `ok: false`), as a perform reads it ("Refresh": a 200 refusal is never folded as an empty page). */
+function refusedIn(m, body) {
+    const shape = refusalShape(m);
+    return shape.length > 0 && shape.every(([p, v]) => at(body, p) === v);
+}
 /** 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')
@@ -104,6 +178,36 @@ async function multipart(body, files, ctx) {
     }
     return { body: out, type: `multipart/form-data; boundary=${boundary}` };
 }
+/** What every call of an operation carries beyond its parameters: its query discriminator (S3's `?uploads`, a bare key
+ *  where its value is null) and its fixed headers (AWS JSON's `x-amz-target`), as the route that serves it reads them. */
+function marked(op, path) {
+    const query = new URLSearchParams(path.includes('?') ? path.slice(path.indexOf('?') + 1) : '');
+    const marks = Object.entries(op.discriminator ?? {}).filter(([k]) => !query.has(k)).map(([k, v]) => (v === null ? encodeURIComponent(k) : `${encodeURIComponent(k)}=${encodeURIComponent(v)}`));
+    return marks.length ? `${path}${path.includes('?') ? '&' : '?'}${marks.join('&')}` : path;
+}
+/** Where a unit's call goes: a lane on a host of its own (`remoteHost`, the real-system adapters "Lanes") to that host,
+ *  filled from the call's parameters, as an absolute URL the executor admits only on a host the descriptor declares; any
+ *  other call to its path on the root's origin. A parameter is one host label, or the literal `values` maps it to. */
+function sentTo(m, path, params) {
+    if (!m.remoteHost)
+        return path;
+    const { template, values } = m.remoteHost;
+    const host = template.replace(/\{([^}]+)\}/g, (_, name) => {
+        const raw = params[name] === undefined || params[name] === null ? '' : String(params[name]);
+        const mapped = values?.[name];
+        if (mapped) {
+            const literal = mapped[raw];
+            if (literal === undefined)
+                throw new Error(`${m.vendor}: the remote host has no value for ${name} ${JSON.stringify(raw)}`);
+            return literal;
+        }
+        if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/i.test(raw))
+            throw new Error(`${m.vendor}: the remote host's ${name} is missing or is not a host label`);
+        return raw;
+    });
+    return `https://${host}${path}`;
+}
+const fixedHeaders = (op) => Object.fromEntries(Object.entries(op.headers ?? {}).filter((e) => typeof e[1] === 'string'));
 /** The body as the operation's encoding sends it. */
 function encode(op, body) {
     if (body === undefined || op.bodyEncoding === 'none')
@@ -124,6 +228,68 @@ function unitOf(units, input) {
         ?? units.find((u) => u.surface.operations.some((o) => o.id === id))
         ?? (input.graphql ? units[0] : undefined);
 }
+/** Read the schema-selected resource through response aliases and fragment selections. */
+async function graphqlAnswers(m, surface, input, parsed) {
+    if (!surface.graphql)
+        throw new Error('a GraphQL perform needs the vendored schema on its derived surface');
+    const g = await import('graphql');
+    const schema = g.buildSchema(surface.graphql.sdl, { assumeValidSDL: true });
+    const sent = object(input.graphql);
+    const document = g.parse(String(sent.query));
+    const operation = g.getOperationAST(document, typeof sent.operationName === 'string' ? sent.operationName : undefined);
+    if (!operation || operation.operation !== 'mutation')
+        throw new Error('the recorded GraphQL write has no selected mutation');
+    const fragments = new Map(document.definitions.filter((d) => d.kind === 'FragmentDefinition').map((d) => [d.name.value, d]));
+    const fields = (selection, seen = new Set()) => selection.selections.flatMap((node) => {
+        if (node.kind === 'Field')
+            return [node];
+        if (node.kind === 'InlineFragment')
+            return fields(node.selectionSet, seen);
+        if (seen.has(node.name.value))
+            return [];
+        const fragment = fragments.get(node.name.value);
+        return fragment ? fields(fragment.selectionSet, new Set([...seen, node.name.value])) : [];
+    });
+    const decode = (value, selection) => {
+        if (Array.isArray(value))
+            return value.map((v) => decode(v, selection));
+        const row = object(value);
+        if (!row || !selection)
+            return value;
+        const decoded = {};
+        for (const field of fields(selection)) {
+            const key = field.alias?.value ?? field.name.value;
+            if (key in row)
+                decoded[field.name.value] = decode(row[key], field.selectionSet);
+        }
+        return decoded;
+    };
+    const answers = [];
+    for (const root of fields(operation.selectionSet)) {
+        const definition = schema.getMutationType()?.getFields()[root.name.value];
+        if (!definition)
+            continue;
+        const type = g.getNamedType(definition.type);
+        const value = object(at(parsed, `data.${root.alias?.value ?? root.name.value}`));
+        // Skipped selections (directives) have no answer and adopt nothing.
+        if (!value)
+            continue;
+        const resource = resourceOf(m, type.name);
+        if (resource) {
+            answers.push({ resource, value: object(decode(value, root.selectionSet)) });
+            continue;
+        }
+        if (g.isObjectType(type) && root.selectionSet)
+            for (const child of fields(root.selectionSet)) {
+                const field = type.getFields()[child.name.value];
+                const resource = field ? resourceOf(m, g.getNamedType(field.type).name) : undefined;
+                const selected = object(value[child.alias?.value ?? child.name.value]);
+                if (resource && selected)
+                    answers.push({ resource, value: object(decode(selected, child.selectionSet)) });
+            }
+    }
+    return answers;
+}
 /** The account a root is, before a perform sends a path naming the World's ("The account a root is"): the World's
  *  account its own doors made, unadopted, adopts the one account the root's credential lists. Read once per deploy (an
  *  adopted account is not asked again); a list the vendor refuses, or one naming several accounts, adopts none. */
@@ -141,7 +307,7 @@ async function adoptAccount(units, execute, ctx) {
         const op = scope && 'list' in scope ? u.surface.operations.find((o) => o.id === scope.list) : undefined;
         if (!local.length || !op)
             continue;
-        const answer = await execute({ method: op.method.toUpperCase(), path: `${op.basePath ?? u.surface.basePath ?? ''}${op.path}`, ...(u.lane ? { lane: u.lane } : {}) });
+        const answer = await execute({ method: op.method.toUpperCase(), path: sentTo(m, marked(op, `${op.basePath ?? u.surface.basePath ?? ''}${op.path}`), {}), ...(u.lane ? { lane: u.lane } : {}), headers: fixedHeaders(op) });
         if (answer.status >= 400)
             continue;
         const items = itemsOf(op, parse(answer));
@@ -170,11 +336,16 @@ function performOf(units) {
         let path;
         let body;
         let op;
+        // the parameters a lane's own host is filled from, as the vendor names them
+        let hostParams = {};
         if (input.graphql) {
             const gql = m.graphql;
             method = 'POST';
             path = gql?.paths[0] ?? '/graphql';
-            body = resolvedDeep(input.graphql, resolve);
+            const g = await import('graphql');
+            const recorded = object(input.graphql);
+            const query = g.print(g.visit(g.parse(String(recorded.query)), { StringValue(node) { const value = resolve(node.value); return value === node.value ? undefined : { ...node, value }; } }));
+            body = { ...recorded, query, variables: resolvedDeep(recorded.variables, resolve) };
         }
         else {
             op = surface.operations.find((o) => o.id === input.operationId);
@@ -205,7 +376,9 @@ function performOf(units) {
             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}`;
+            path = marked(op, path);
             body = sentBody === undefined ? undefined : resolvedDeep(sentBody, resolve);
+            hostParams = Object.fromEntries(Object.entries(params).map(([k, v]) => [k, resolve(String(v))]));
         }
         const files = Array.isArray(input.files) ? input.files : [];
         // a body recorded as it came (not JSON) goes as it came
@@ -213,26 +386,54 @@ function performOf(units) {
         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 || op?.bodyEncoding === 'multipart' ? 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 } : {}) };
+        const headers = { ...(op ? fixedHeaders(op) : {}), ...(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 } : {}), ...(unit.lane ? { lane: unit.lane } : {}) });
+        const answer = await execute({ method, path: sentTo(m, path, hostParams), ...(unit.lane ? { lane: unit.lane } : {}), 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));
+        const gqlErrors = input.graphql && Array.isArray(at(parsed, 'errors')) ? at(parsed, 'errors') : [];
         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 (gqlErrors.length)
+            throw new RefusedWriteError('vendor', `400: ${gqlErrors.map((e) => String(e.message)).join('; ')}`, first.id);
+        const refused = answer.status >= 400 || refusedIn(m, parsed);
         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) ?? {};
+        if (input.graphql) {
+            const answers = await graphqlAnswers(m, surface, input, parsed);
+            const remaining = [...group];
+            const adopted = [];
+            for (const answer of answers) {
+                const index = remaining.findIndex((entry) => entry.subject.type === storedType(m, answer.resource));
+                if (index < 0)
+                    continue;
+                const entry = remaining.splice(index, 1)[0];
+                const decl = m.resources[answer.resource];
+                const data = answer.value ?? {};
+                const externalId = entry.fields?.deleted === true ? ctx.resolve(entry.subject.type, entry.subject.id) : storedIdOf(decl, data) ?? '';
+                adopted.push({ actionId: entry.id, externalId, data });
+            }
+            const primary = adopted.shift();
+            return primary ? { ...primary, ...(adopted.length ? { also: adopted } : {}) } : { externalId: '', actionId: group.at(-1).id };
+        }
+        // an XML answer is read through its document element (S3's `InitiateMultipartUploadResult`), as a JSON one under its key
+        const documentElement = () => {
+            const root = object(parsed);
+            const names = root ? Object.keys(root) : [];
+            return answer.body.trimStart().startsWith('<') && names.length === 1 ? object(root[names[0]]) : undefined;
+        };
+        const obj = object(key ? at(parsed, key) : parsed === undefined ? undefined : documentElement() ?? 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;
+        // an answer naming no resource of the manifest (an operation's own output structure: Secrets Manager's
+        // CreateSecretResponse, S3's CreateMultipartUploadOutput) is the group's subject's, its id read by that resource
+        const subjectDecl = () => Object.entries(m.resources).find(([r]) => storedType(m, r) === group.at(-1).subject.type)?.[1];
+        const decl = resource ? m.resources[resource] : subjectDecl();
         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
@@ -247,9 +448,9 @@ function performOf(units) {
         // 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) ?? '';
+            : keyed?.key ? storedIdOf(keyed, { ...(object(parsed) ?? {}), ...obj }) ?? '' : idOf(obj, decl) ?? (ctx.resolve(primary.subject.type, primary.subject.id) !== primary.subject.id ? ctx.resolve(primary.subject.type, primary.subject.id) : '');
         const also = [];
-        for (const [companion, where] of Object.entries(decl?.companions ?? {})) {
+        for (const [companion, where] of Object.entries(decl?.companions ?? keyed?.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')
@@ -296,7 +497,7 @@ function vendorFieldParams(m, resource, params, ctx) {
     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 localParent = where.length ? tree.find((r) => r.type === parentType && where.every(([f, , v]) => String(at(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);
@@ -311,16 +512,42 @@ function vendorFieldParams(m, resource, params, ctx) {
     if (parentCopy)
         for (const [field, template] of where) {
             const one = /^\{([^}]+)\}$/.exec(template);
-            if (one && parentCopy[field] !== undefined)
-                params[one[1]] = String(parentCopy[field]);
+            const value = at(parentCopy, field);
+            if (one && value !== undefined)
+                params[one[1]] = String(value);
         }
 }
 /** The items of a list's answer: under the operation's key, else the answer when it is a list. */
+/** The items a scope names: a list, or one item where XML names a lone child (an S3 list of one object), or none. */
+const listed = (v) => (Array.isArray(v) ? v : v === undefined || v === null || v === '' ? [] : [v]);
 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);
 }
+/** A vendor response may hold download links in an object map or an array. Missing optional paths yield none. */
+function valuesAt(value, keys) {
+    if (!keys.length)
+        return value === undefined || value === null ? [] : [value];
+    if (!value || typeof value !== 'object')
+        return [];
+    const [key, ...rest] = keys;
+    return key === '*' ? Object.values(value).flatMap((v) => valuesAt(v, rest)) : valuesAt(value[key], rest);
+}
+/** The field a refresh scope's answer names its subject by, where it differs from the resource's (`refresh.idAs`: the
+ *  Hub's repo read carries the creation's ObjectId as `_id` and its own `namespace/name` as `id`). */
+function scopeIdOf(scope, fields) {
+    const field = scope.idAs;
+    if (field?.includes('{'))
+        return field.replace(/\{([^}]+)\}/g, (_, name) => {
+            const value = at(fields, name);
+            if (value === undefined || value === null || value === '')
+                throw new Error(`refresh identity lacks ${name}; nothing folded`);
+            return String(value);
+        });
+    const value = field ? at(fields, field) : undefined;
+    return value === undefined || value === null || value === '' ? undefined : String(value);
+}
 function refreshOf(units, service) {
     return async (execute, opts) => {
         const observed = [];
@@ -328,114 +555,489 @@ function refreshOf(units, service) {
         // what the root's credential may not read (a token scoped to some of the account): left as the World holds it, said
         const unread = [];
         let answered = 0;
-        for (const unit of units) {
-            const { manifest: m, surface } = unit;
+        for (const { manifest: m, surface, lane } of units) {
+            const onLane = lane ? { lane } : {};
             // 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;
+                if ('none' in scope)
+                    continue;
+                if ('graphql' in scope && scope.graphql) {
+                    await refreshGraphql(m, resource, decl, scope, execute, opts.scope, observed, complete);
+                    answered += 1;
+                    continue;
+                }
                 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;;) {
-                        let unfilled = false;
-                        const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n) => { const v = n === decl.parent?.param && parent !== undefined ? String(parent) : ''; if (!v)
-                            unfilled = true; return encodeURIComponent(v); });
-                        // 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, ...(unit.lane ? { lane: unit.lane } : {}) });
+                // the known, read one by one: a vendor that lists no whole type (Volter Identity's people and organizations) is
+                // read back subject by subject: each the vendor is known to hold (the parent tree: landed or observed, never a
+                // World-only subject, which a 404 would wrongly remove), by the vendor's id, its other path parameters filled
+                // from its own fields; a 404 is one the vendor no longer has, and only the subjects read are whole
+                if ('get' in scope && scope.known) {
+                    const aliases = aliasesFrom(parentEntries(service, opts.root));
+                    const held = [...readParentTreeMap(service, opts.root)].filter(([, r]) => r.type === type && r.fields.deleted !== true);
+                    const read = [];
+                    // a 403 leaves the type as the World holds it, never complete
+                    let refused = false;
+                    for (const [key, r] of held) {
+                        const subject = { ...r.fields, id: r.id };
+                        const vendorId = aliases.get(key) ?? String(r.id);
+                        for (const [name, template] of Object.entries(scope.params ?? {}))
+                            subject[name] = template.replace(/\{([^}]+)\}/g, (_, field) => {
+                                if (field === 'id')
+                                    return vendorId;
+                                if (subject[field] === undefined || subject[field] === null)
+                                    throw new Error(`${m.vendor}: ${resource}'s refresh parameter ${name} lacks ${field}; nothing folded`);
+                                return String(subject[field]);
+                            });
+                        // each path parameter is the subject's own field of that name (the Hub's {namespace} and {repo}); one the subject
+                        // holds no field for, or `id`, is the vendor's id for it
+                        const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n) => encodeURIComponent(String(n === 'id' || subject[n] === undefined || subject[n] === null ? vendorId : subject[n])));
+                        // a read naming its subject in the query (an RPC method: Telegram's getChat?chat_id=): the scope's `query`, each
+                        // `{name}` filled as a path parameter is
+                        const fillSubject = (t) => t.replace(/\{([^}]+)\}/g, (_, n) => String(n === 'id' || subject[n] === undefined || subject[n] === null ? vendorId : subject[n]));
+                        const asked = Object.entries(scope.query ?? {}).map(([k, t]) => [k, fillSubject(t)]);
+                        const target = marked(op, path);
+                        const sent = asked.length ? `${target}${target.includes('?') ? '&' : '?'}${new URLSearchParams(asked)}` : target;
+                        const answer = await execute({ method: op.method.toUpperCase(), path: sentTo(m, sent, subject), ...onLane, headers: fixedHeaders(op) });
                         if (answer.status === 401)
                             throw new Error(`401: the vendor refused the root's credential (${op.method.toUpperCase()} ${path}); nothing folded`);
                         if (answer.status === 403) {
                             unread.push({ type, path, status: 403 });
-                            whole = false;
+                            refused = true;
                             break;
                         }
                         if (answer.status === 429)
                             throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
-                        // one subject read by its parent and not there (an account with no workers.dev subdomain): nothing to observe. A
-                        // path missing a parameter (an empty segment) is the kernel's mistake, never the vendor's absence
-                        if ('get' in scope && answer.status === 404 && !unfilled) {
-                            answered += 1;
-                            break;
-                        }
-                        if (answer.status >= 400)
-                            throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);
+                        read.push(String(subject.id));
                         answered += 1;
-                        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) };
+                        if (answer.status === 404)
                             continue;
+                        if (answer.status >= 400 || refusedIn(m, parse(answer)))
+                            throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);
+                        const full = object(op.answers?.key ? at(parse(answer), op.answers.key) : parse(answer)) ?? {};
+                        const local = m.worldFields?.[resource] ?? {};
+                        const fields = Object.fromEntries(Object.entries(full).filter(([k]) => !(k in local)));
+                        if (decl.parent) {
+                            if (r.fields[decl.parent.field] !== undefined)
+                                fields[decl.parent.field] = r.fields[decl.parent.field];
+                            for (const [name, template] of Object.entries(decl.parent.keep ?? {})) {
+                                if (!name.startsWith('_'))
+                                    throw new Error(`${m.vendor}: ${resource}'s parent.keep names a non-private field; nothing folded`);
+                                fields[name] = fillSubject(template);
+                            }
                         }
-                        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;
-                        }
+                        // the subject asked for, where its answer names no id of its own (a singleton under its account)
+                        const id = scopeIdOf(scope, fields) ?? storedIdOf(decl, fields) ?? String(r.id);
+                        observed.push({ type, id, fields: fields });
                     }
+                    if (!refused)
+                        complete.push({ type, ids: read });
+                    continue;
                 }
+                // each parent observed: the path parameters it fills and the value the child's parent field holds (its id, or for
+                // a parent the path names by several parameters, `parent.value` filled from them as the twin stores it)
+                const parents = decl.parent ? parentsOf(decl.parent, observed.filter((o) => o.type === storedType(m, decl.parent.resource))) : [undefined];
+                let whole = 'list' in scope && scope.complete !== false;
+                for (const under of parents)
+                    for (const variant of scope.variants ?? [{ headers: {} }]) {
+                        const parent = under?.value;
+                        // the list's own headers, `{name}` its parent's parameter, and the variant's
+                        const filled = (t) => t.replace(/\{([^}]+)\}/g, (_, n) => under?.params[n] ?? '');
+                        const listHeaders = { ...Object.fromEntries(Object.entries(scope.headers ?? {}).map(([n, t]) => [n, filled(t)])), ...variant.headers };
+                        // what a child keeps of its parent's parameters, private
+                        const kept = Object.fromEntries(Object.entries(decl.parent?.keep ?? {}).map(([f, t]) => {
+                            if (!f.startsWith('_'))
+                                throw new Error(`${m.vendor}: ${resource}'s parent.keep names ${f}, which is not private`);
+                            return [f, filled(t)];
+                        }));
+                        // a list asked by POST (an RPC list) carries its page in its body, as the operation's encoding sends it
+                        const rpc = op.method.toLowerCase() !== 'get';
+                        const unpaginated = 'list' in scope && scope.unpaginated === true;
+                        const limit = !unpaginated && m.list?.limit && [...(op.query ?? []), ...(rpc ? op.body ?? [] : [])].some((q) => q.name === m.list.limit.param) ? { [m.list.limit.param]: String(m.list.limit.max) } : {};
+                        let page = { ...scope.query, ...limit };
+                        const seenLinks = new Set();
+                        for (let taken = 0;;) {
+                            let unfilled = false;
+                            const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n) => { const v = under?.params[n] ?? ''; if (!v)
+                                unfilled = true; return encodeURIComponent(v); });
+                            // a parent the operation names in its query, not its path (Slack's conversations.history `channel`)
+                            // and a parent named by several parameters, each the path does not take that the operation declares in its query
+                            // (Slack's reactions.get: a message's `channel` and `timestamp`)
+                            const byQuery = decl.parent?.param && parent !== undefined && !op.path.includes(`{${decl.parent.param}}`) ? { [decl.parent.param]: String(parent) }
+                                : decl.parent?.params?.length && under ? Object.fromEntries(Object.entries(under.params).filter(([n]) => !op.path.includes(`{${n}}`) && (op.query ?? []).some((x) => x.name === n))) : {};
+                            // a list asked by POST carries its parent in its body too, unless the operation reads it from its query
+                            const parentInQuery = !rpc || (op.query ?? []).some((x) => x.name === decl.parent?.param);
+                            const q = new URLSearchParams(rpc ? (parentInQuery ? byQuery : {}) : { ...page, ...byQuery });
+                            // Fixed parameters and cursors take the operation's body types, not their manifest string encoding.
+                            const typedPage = Object.fromEntries(Object.entries(page).map(([k, v]) => {
+                                const type = (op.body ?? []).find((b) => b.name === k)?.type;
+                                const value = type === 'integer' ? exactInteger(v) : type === 'number' ? Number(v)
+                                    : type === 'boolean' && (v === 'true' || v === 'false') ? v === 'true' : v;
+                                return [k, value];
+                            }));
+                            const sent = rpc ? encode(op, { ...typedPage, ...(parentInQuery ? {} : byQuery) }) : undefined;
+                            const answer = await execute({
+                                method: op.method.toUpperCase(), path: sentTo(m, marked(op, [...q].length ? `${path}?${q}` : path), under?.params ?? {}), ...onLane,
+                                headers: { ...fixedHeaders(op), ...listHeaders, ...(sent?.type ? { 'content-type': sent.type } : {}) }, ...(sent?.body !== undefined ? { body: sent.body } : {}),
+                            });
+                            if (answer.status === 401)
+                                throw new Error(`401: the vendor refused the root's credential (${op.method.toUpperCase()} ${path}); nothing folded`);
+                            if (answer.status === 403) {
+                                unread.push({ type, path, status: 403 });
+                                whole = false;
+                                break;
+                            }
+                            if (answer.status === 429)
+                                throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
+                            // one subject read by its parent and not there (an account with no workers.dev subdomain): nothing to observe. A
+                            // path missing a parameter (an empty segment) is the kernel's mistake, never the vendor's absence
+                            if ('get' in scope && answer.status === 404 && !unfilled) {
+                                answered += 1;
+                                break;
+                            }
+                            if (answer.status >= 400 || refusedIn(m, parse(answer)))
+                                throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);
+                            answered += 1;
+                            const parsed = parse(answer);
+                            const shape = 'list' in scope ? scope.shape : undefined;
+                            const items = 'get' in scope ? [object(op.answers?.key ? at(parsed, op.answers.key) : parsed) ?? {}]
+                                : 'items' in scope && scope.items ? listed(at(parsed, scope.items)).map((x) => object(x)).filter((x) => x !== undefined) : itemsOf(op, parsed);
+                            const keyed = 'list' in scope && scope.keyed === true;
+                            const map = keyed ? object(at(parsed, scope.items ?? '$body')) : undefined;
+                            if (keyed && (!map || Object.values(map).some((value) => (shape?.value ? object(value) !== undefined : !object(value)))))
+                                throw new Error(`${m.vendor}: ${resource}'s keyed refresh must return an object of ${shape?.value ? 'scalars' : 'resource objects'}; nothing folded`);
+                            // the answer's items as subjects' fields (refresh.shape): a scalar item or map value named, a nested array spread
+                            let entries = keyed
+                                ? Object.entries(map).map(([key, value]) => (shape?.value
+                                    ? [shape.keyAs ? undefined : key, { [shape.value]: value, ...(shape.keyAs ? { [shape.keyAs]: key } : {}) }]
+                                    : [key, object(value)]))
+                                : shape?.scalar && 'items' in scope && scope.items
+                                    ? listed(at(parsed, scope.items)).filter((x) => x !== null && typeof x !== 'object').map((x) => [undefined, { [shape.scalar]: x }])
+                                    : items.map((item) => [undefined, item]);
+                            // paging reads the answer's own items, before any spread
+                            const pageItems = entries;
+                            if (shape?.spread) {
+                                const { path: inner, as, carry } = shape.spread;
+                                entries = entries.flatMap(([, item]) => {
+                                    const carried = Object.fromEntries(Object.entries(carry ?? {}).map(([f, p]) => [f, at(item, p)]));
+                                    return listed(at(item, inner)).flatMap((el) => {
+                                        const own = object(el) ?? (as && el !== null && el !== undefined ? { [as]: el } : undefined);
+                                        return own ? [[undefined, { ...carried, ...own }]] : [];
+                                    });
+                                });
+                            }
+                            for (const [mapId, item] of entries) {
+                                let full = item;
+                                if ('list' in scope && scope.detail) {
+                                    const detail = surface.operations.find((o) => o.id === scope.detail);
+                                    if (!detail)
+                                        throw new Error(`${m.vendor}: ${resource}'s refresh detail names ${scope.detail}, no operation of the surface`);
+                                    const id = mapId ?? storedIdOf(decl, item);
+                                    const path = `${detail.basePath ?? surface.basePath ?? ''}${detail.path}`.replace(/\{([^}]+)\}/g, (_, n) => {
+                                        const value = under?.params[n] ?? item[n] ?? id;
+                                        if (value === undefined)
+                                            throw new Error(`${m.vendor}: ${resource}'s refresh detail has no value for ${n}`);
+                                        return encodeURIComponent(String(value));
+                                    });
+                                    // the subject a detail read names in its body or query (`detailWith`: AWS JSON's DescribeSecret, `{ SecretId }`)
+                                    const withValues = Object.fromEntries(Object.entries(scope.detailWith ?? {}).map(([k, t]) => [k, t.replace(/\{([^}]+)\}/g, (_, n) => String(n === 'id' ? id : item[n] ?? ''))]));
+                                    const detailRpc = detail.method.toLowerCase() !== 'get';
+                                    const detailQuery = { ...(scope.query ?? {}), ...(detailRpc ? {} : withValues) };
+                                    const detailSent = detailRpc && Object.keys(withValues).length ? encode(detail, withValues) : undefined;
+                                    const answer = await execute({ method: detail.method.toUpperCase(), path: sentTo(m, marked(detail, Object.keys(detailQuery).length ? `${path}?${new URLSearchParams(detailQuery)}` : path), { ...item, ...under?.params }), ...onLane, headers: { ...fixedHeaders(detail), ...(detailSent?.type ? { 'content-type': detailSent.type } : {}) }, ...(detailSent?.body !== undefined ? { body: detailSent.body } : {}) });
+                                    if (answer.status >= 400 || refusedIn(m, parse(answer)))
+                                        throw new Error(`${answer.status}: ${refusalWords(m, parse(answer)) || 'the vendor refused the refresh detail; nothing folded'}`);
+                                    const detailBody = parse(answer);
+                                    const detailKey = scope.detailMerge ?? detail.answers?.key;
+                                    const fragment = object(detailKey ? at(detailBody, detailKey) : detailBody);
+                                    if (scope.detailMerge && !fragment)
+                                        throw new Error(`${m.vendor}: ${resource}'s refresh detail fragment is not an object; nothing folded`);
+                                    const detailFields = fragment ?? {};
+                                    full = scope.detailMerge ? { ...item, ...detailFields } : detailFields;
+                                }
+                                // the vendor's shape alone: a World field the twin discloses (manifest.worldFields: Substrate's
+                                // twin_local_ports) is the answering World's, never the vendor's, and is not folded in
+                                const local = m.worldFields?.[resource] ?? {};
+                                const vendorShape = Object.fromEntries(Object.entries(full).filter(([k]) => !(k in local)));
+                                const fields = { ...vendorShape, ...kept, ...(decl.parent && parent !== undefined ? { [decl.parent.field]: parent } : {}) };
+                                const id = mapId ?? scopeIdOf(scope, fields) ?? storedIdOf(decl, fields);
+                                if (id === undefined)
+                                    continue;
+                                observed.push({ type, id, fields: fields });
+                            }
+                            taken += pageItems.length;
+                            if ('get' in scope || unpaginated)
+                                break;
+                            if (taken >= 10_000) {
+                                whole = false;
+                                break;
+                            }
+                            if ('nextLink' in scope && scope.nextLink) {
+                                const nextLink = scope.nextLink;
+                                const header = Object.entries(answer.headers).find(([name]) => name.toLowerCase() === nextLink.header.toLowerCase())?.[1];
+                                const links = header ? linkRelations(header).filter((link) => link.params.rel?.split(/\s+/).includes(nextLink.rel)) : [];
+                                if (links.length > 1)
+                                    throw new Error(`${m.vendor}: ambiguous refresh Link relation; nothing folded`);
+                                const link = links[0];
+                                if (!link || Object.entries(nextLink.when ?? {}).some(([name, value]) => link.params[name.toLowerCase()] !== value))
+                                    break;
+                                let marker;
+                                try {
+                                    marker = new URL(link.url).searchParams.get(nextLink.query);
+                                }
+                                catch {
+                                    throw new Error(`${m.vendor}: refresh Link continuation is not an absolute URL; nothing folded`);
+                                }
+                                if (!marker)
+                                    throw new Error(`${m.vendor}: refresh Link URL lacks its declared cursor; nothing folded`);
+                                const param = scope.cursor ?? nextLink.query;
+                                if (page[param] === marker || seenLinks.has(marker))
+                                    throw new Error(`${m.vendor}: ${resource}'s list repeated its continuation; nothing folded`);
+                                seenLinks.add(marker);
+                                page = { ...page, [param]: marker };
+                                continue;
+                            }
+                            // 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.
+                            // the cursor the scope names (AWS's NextToken), sent back as its parameter
+                            if ('next' in scope && scope.next) {
+                                // the vendor's own flag that no page follows ends it, whatever cursor the page names
+                                if ('more' in scope && scope.more !== undefined && !['true', true].includes(at(parsed, scope.more)))
+                                    break;
+                                const markers = typeof scope.next === 'string' ? { [scope.cursor ?? scope.next]: scope.next } : scope.next;
+                                const next = Object.fromEntries(Object.entries(markers).flatMap(([param, where]) => {
+                                    const marker = at(parsed, where);
+                                    return marker === undefined || marker === null || marker === '' ? [] : [[param, String(marker)]];
+                                }));
+                                if (!Object.keys(next).length)
+                                    break;
+                                // a page that names the cursor it was asked with would be read forever: nothing folds
+                                if (Object.entries(next).every(([k, v]) => page[k] === v))
+                                    throw new Error(`${m.vendor}: ${resource}'s list repeated its continuation; nothing folded`);
+                                page = { ...page, ...next };
+                                continue;
+                            }
+                            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 (!pageItems.length || (size && pageItems.length < size))
+                                break;
+                            if (!size) {
+                                whole = false;
+                                break;
+                            }
+                            const last = pageItems.at(-1)[0] ?? pageItems.at(-1)[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) });
+                    complete.push({ type, field: decl.parent.field, within: parents.map((p) => p.value) });
             }
         }
         // every read refused is a credential the vendor refuses, never an account that holds nothing
         if (unread.length && !answered)
             throw new Error(`403: the vendor refused the root's credential for every read (${unread.map((u) => u.path).join(', ')}); nothing folded`);
+        const downloads = [];
+        for (const { manifest: m, surface, lane } of units)
+            for (const [resource, decl] of Object.entries(m.resources)) {
+                const scope = decl.refresh;
+                if (!scope || 'none' in scope || !scope.blobs?.length)
+                    continue;
+                for (const row of observed.filter((o) => o.type === storedType(m, resource)))
+                    for (const blob of scope.blobs) {
+                        // the bytes an operation of the unit answers for the subject (R2's GetObject: its list names no download link)
+                        if ('operation' in blob) {
+                            if (!blob.field.startsWith('_') || (blob.headersField !== undefined && !blob.headersField.startsWith('_')))
+                                throw new Error(`${m.vendor}: ${resource}'s refresh blob fields must be private`);
+                            const op = surface.operations.find((o) => o.id === blob.operation);
+                            if (!op || op.method.toUpperCase() !== 'GET')
+                                throw new Error(`${m.vendor}: ${resource}'s refresh blob names ${blob.operation}, no GET of the surface`);
+                            const under = decl.parent ? parentsOf(decl.parent, observed.filter((o) => o.type === storedType(m, decl.parent.resource))).find((p) => p.value === row.fields[decl.parent.field]) : undefined;
+                            const values = { ...row.fields, ...under?.params, id: row.id };
+                            const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n) => {
+                                if (values[n] === undefined || values[n] === null)
+                                    throw new Error(`${m.vendor}: ${resource}'s refresh blob has no value for ${n}`);
+                                return encodeURIComponent(String(values[n]));
+                            });
+                            const answer = await execute({ method: 'GET', path: sentTo(m, marked(op, path), values), ...(lane ? { lane } : {}), headers: { ...fixedHeaders(op), ...blob.headers }, responseType: 'bytes' });
+                            if (answer.status < 200 || answer.status >= 300 || !answer.bodyBytes)
+                                throw new Error(`${m.vendor}: refresh blob ${blob.operation} answered ${answer.status}; nothing folded`);
+                            const key = `refresh/${encodeURIComponent(row.type)}/${encodeURIComponent(row.id)}`;
+                            // only the headers the scope names: the answer's own (its date, its length) would change every read
+                            const keptHeaders = Object.fromEntries(Object.entries(answer.headers).filter(([h]) => (blob.keepHeaders ?? []).some((n) => (n.endsWith('*') ? h.toLowerCase().startsWith(n.slice(0, -1).toLowerCase()) : h.toLowerCase() === n.toLowerCase()))).map(([h, v]) => [h.toLowerCase(), v]));
+                            row.fields = { ...row.fields, [blob.field]: key, ...(blob.headersField ? { [blob.headersField]: keptHeaders } : {}) };
+                            downloads.push({ key, bytes: answer.bodyBytes });
+                            continue;
+                        }
+                        for (const value of valuesAt(row.fields, blob.path.split('.'))) {
+                            if (typeof value !== 'string')
+                                throw new Error(`${m.vendor}: refresh blob ${blob.path} is not a URL`);
+                            let url = new URL(value);
+                            const boundUrl = readRoot(service, opts.root)?.url;
+                            const bound = boundUrl ? new URL(boundUrl) : undefined;
+                            const prefix = bound?.pathname.replace(/\/+$/, '') ?? '';
+                            const primary = m.origin?.placeholder ? new URL(m.origin.placeholder).hostname : m.descriptor?.hosts?.find((h) => 'host' in h && !h.exclude);
+                            const primaryHost = typeof primary === 'string' ? primary : primary && 'host' in primary ? primary.host : undefined;
+                            let answer;
+                            let pathname = '';
+                            for (let hops = 0; hops <= 5; hops++) {
+                                const fromRoot = !!bound && url.origin === bound.origin && (url.pathname === prefix || url.pathname.startsWith(prefix + '/'));
+                                pathname = fromRoot ? url.pathname.slice(prefix.length) || '/' : url.pathname;
+                                if (url.username || url.password || (!fromRoot && (url.protocol !== 'https:' || (url.port && url.port !== '443'))) || (!fromRoot && !m.descriptor?.hosts?.some((h) => 'host' in h && !h.exclude && h.host === url.hostname && (!h.pathPattern || new RegExp(h.pathPattern).test(url.pathname)))))
+                                    throw new Error(`${m.vendor}: refresh blob host is not declared: ${url.hostname}`);
+                                answer = await execute({ method: 'GET', path: fromRoot || url.hostname === primaryHost ? pathname + url.search : url.href, headers: { host: url.host }, responseType: 'bytes' });
+                                if (![301, 302, 303, 307, 308].includes(answer.status))
+                                    break;
+                                if (hops === 5 || !answer.headers.location)
+                                    throw new Error(`${m.vendor}: invalid refresh blob redirect; nothing folded`);
+                                url = new URL(answer.headers.location, url);
+                            }
+                            if (!answer || answer.status < 200 || answer.status >= 300 || !answer.bodyBytes)
+                                throw new Error(`${m.vendor}: refresh blob ${blob.path} answered ${answer?.status}; nothing folded`);
+                            const fill = (template, key = '') => template.replace(/\{pathname\}/g, decodeURIComponent(pathname)).replace(/\{key\}/g, key).replace(/\{header:([^}]+)\}/g, (_, name) => {
+                                const value = answer.headers[name.toLowerCase()];
+                                if (value === undefined)
+                                    throw new Error(`${m.vendor}: refresh blob header ${name} is missing; nothing folded`);
+                                return value;
+                            });
+                            const key = fill(blob.key);
+                            if (!key || key.startsWith('/') || key.includes('\0') || key.split(/[\\/]/).includes('..') || /\{[^}]+\}/.test(key))
+                                throw new Error(`${m.vendor}: invalid refresh blob key`);
+                            if (blob.resource) {
+                                if (!blob.resource.startsWith('_') || !m.resources[blob.resource])
+                                    throw new Error(`${m.vendor}: refresh blob metadata requires a declared bookkeeping resource`);
+                                observed.push({ type: storedType(m, blob.resource), id: key, fields: Object.fromEntries(Object.entries(blob.fields ?? {}).map(([name, template]) => [name, fill(template, key)])) });
+                            }
+                            downloads.push({ key, bytes: answer.bodyBytes });
+                        }
+                    }
+            }
+        for (const download of downloads)
+            await writeResourceBlob(service, download.key, download.bytes, opts.root);
         adopt(service, opts.root, units, observed);
         const report = observeResources(service, observed, { ...(opts.root !== undefined ? { root: opts.root } : {}), complete });
         return unread.length ? { ...report, unread } : report;
     };
 }
+/** A declared GraphQL read over the same executor and atomic observation batch as REST. */
+async function refreshGraphql(m, resource, decl, scope, execute, rootScope, observed, complete) {
+    const gql = scope.graphql;
+    const endpoint = m.graphql?.paths[0];
+    if (!endpoint)
+        throw new Error(`${m.vendor}: a GraphQL refresh needs a GraphQL endpoint`);
+    const type = storedType(m, resource);
+    const parents = decl.parent ? parentsOf(decl.parent, observed.filter((o) => o.type === storedType(m, decl.parent.resource))) : [undefined];
+    let whole = 'list' in scope && scope.complete !== false;
+    for (const under of parents) {
+        const substitute = (v) => typeof v === 'string' && /^\{[^}]+\}$/.test(v) ? under?.params[v.slice(1, -1)] ?? v
+            : Array.isArray(v) ? v.map(substitute) : object(v) ? Object.fromEntries(Object.entries(object(v)).map(([k, x]) => [k, substitute(x)])) : v;
+        const variables = substitute(gql.variables ?? {});
+        const cursors = new Set();
+        for (let taken = 0;;) {
+            const answer = await execute({ method: 'POST', path: endpoint, headers: { 'content-type': 'application/json' }, body: JSON.stringify({ query: gql.query, variables }) });
+            const parsed = parse(answer);
+            if (answer.status >= 400 || (Array.isArray(at(parsed, 'errors')) && at(parsed, 'errors').length))
+                throw new Error(`${answer.status}: the vendor refused the GraphQL refresh; nothing folded: ${JSON.stringify(parsed)}`);
+            const value = at(parsed, gql.items);
+            if (value === undefined)
+                throw new Error(`${m.vendor}: the GraphQL refresh returned no ${gql.items}; nothing folded`);
+            const items = listed(value).map(object).filter((x) => x !== undefined);
+            for (const item of items) {
+                const fields = { ...item, ...(decl.parent && under ? { [decl.parent.field]: under.value } : {}) };
+                const id = storedIdOf(decl, fields);
+                if (id !== undefined)
+                    observed.push({ type, id, fields: fields });
+            }
+            taken += items.length;
+            if ('get' in scope || ('list' in scope && scope.unpaginated))
+                break;
+            if (!gql.pageInfo) {
+                whole = false;
+                break;
+            }
+            const info = object(at(parsed, gql.pageInfo));
+            if (!info || typeof info.hasNextPage !== 'boolean')
+                throw new Error(`${m.vendor}: missing GraphQL page information; nothing folded`);
+            if (!info.hasNextPage)
+                break;
+            if (taken >= 10_000) {
+                whole = false;
+                break;
+            }
+            const cursor = info.endCursor;
+            if (typeof cursor !== 'string' || !cursor || cursors.has(cursor))
+                throw new Error(`${m.vendor}: invalid GraphQL continuation; nothing folded`);
+            cursors.add(cursor);
+            variables[gql.cursor ?? 'after'] = cursor;
+        }
+    }
+    if (whole && !decl.parent && !rootScope)
+        complete.push(type);
+    else if (whole && parents.length && decl.parent)
+        complete.push({ type, field: decl.parent.field, within: parents.map((p) => p.value) });
+}
+/** The parents a child type is listed under, from the parent type's observations: the path parameters each fills and
+ *  the value the child's `parent.field` holds. A single `param` is the parent's id. A parent the path names by several
+ *  parameters (`params`, GitHub's `{owner}/{repo}`) reads each from the parent's fields through its `where` templates
+ *  (`full_name: '{owner}/{repo}'`), and the child holds `value` filled from them (the parameters joined by `/` when it
+ *  names none), as the derived core stores it ("Refresh"). A parent whose fields fill not every parameter is skipped. */
+function parentsOf(parent, observations) {
+    const out = new Map();
+    for (const o of observations) {
+        if (!parent.params?.length) {
+            out.set(o.id, { params: parent.param ? { [parent.param]: o.id } : {}, value: o.id });
+            continue;
+        }
+        const params = {};
+        for (const [field, template] of Object.entries(parent.where ?? {})) {
+            const names = [];
+            // a template that is one parameter whole takes the field whole, its slashes included (an S3 key)
+            const whole = /^\{([^}]+)\}$/.exec(template);
+            if (whole) {
+                const v = at(o.fields, field);
+                if (v !== undefined && v !== null && v !== '')
+                    params[whole[1]] = String(v);
+                continue;
+            }
+            const pattern = template.replace(/\{([^}]+)\}|[.*+?^$()|[\]\\]/g, (m, n) => (n ? (names.push(n), '([^/]+)') : `\\${m}`));
+            const got = new RegExp(`^${pattern}$`).exec(String(at(o.fields, field) ?? ''));
+            if (got)
+                names.forEach((n, i) => { params[n] = got[i + 1]; });
+        }
+        if (!parent.params.every((n) => params[n] !== undefined))
+            continue;
+        const value = (parent.value ?? parent.params.map((n) => `{${n}}`).join('/')).replace(/\{([^}]+)\}/g, (_, n) => params[n] ?? '');
+        out.set(value, { params, value });
+    }
+    return [...out.values()];
+}
 /** 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) {
@@ -503,7 +1105,7 @@ function adopt(service, root, units, observed) {
         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 keys = decl?.adoptBy ?? 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;
@@ -534,6 +1136,8 @@ function older(theirs, held) {
         return false;
     const a = Number(theirs);
     const b = Number(held);
+    if (/^-?\d+$/.test(String(theirs)) && /^-?\d+$/.test(String(held)))
+        return compareExactNumbers(theirs, held) < 0;
     if (String(theirs).trim() !== '' && String(held).trim() !== '' && Number.isFinite(a) && Number.isFinite(b))
         return a < b;
     const ta = Date.parse(String(theirs));
@@ -552,7 +1156,7 @@ function ingestOf(units, decl, service) {
             return Response.json({ error: 'invalid signature' }, { status: 401 });
         let event;
         try {
-            event = JSON.parse(body);
+            event = parseExactJson(body);
         }
         catch {
             return Response.json({ error: 'the event is not JSON' }, { status: 400 });
@@ -567,9 +1171,16 @@ function ingestOf(units, decl, service) {
             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;
+            // the object where its type carries it, with its parent's value where the event names the parent beside it
+            const carried = object(at(event, found.object ?? decl.object));
+            const parent = found.parent && d.parent ? at(event, found.parent) : undefined;
+            const withParent = carried && (typeof parent === 'string' || typeof parent === 'number') ? { ...carried, [d.parent.field]: String(parent) } : carried;
+            // the subject's id where the type names it (kept out of the fields: the vendor's object carries no such field), and
+            // what the type itself says of the subject
+            const named = found.id && withParent ? at(withParent, found.id) : undefined;
+            const item = withParent ? { ...(found.id && !found.id.includes('.') ? Object.fromEntries(Object.entries(withParent).filter(([k]) => k !== found.id)) : withParent), ...(found.fields ?? {}) } : undefined;
+            const id = found.id ? (typeof named === 'string' || typeof named === 'number' ? String(named) : undefined) : item ? storedIdOf(d, item) : undefined;
             if (!item || id === undefined)
                 break;
             const stored = storedType(m, found.resource);