@volter/world-core 3.0.38 → 3.0.40

package/src/derived-real.ts

@@ -1,3 +1,4 @@
+import { parseExactJson, exactInteger, compareExactNumbers } from './exact-json.ts';
 // THE REAL-SYSTEM ADAPTERS, DERIVED (docs/contributing/architecture.md, "The real-system adapters"): a pack's perform,
 // refresh and ingest made by the kernel from its manifest and its generated surface, so no pack writes adapter code.
 // They run over the kernel executor (`RemoteExecute`), which applies the sealed credential; the credential never
@@ -8,17 +9,18 @@ import { storedType, type DerivedManifest, type IngestDecl, type ResourceDecl, t
 import type { DerivedOperation, DerivedSurface } from './derived.ts';
 import { verifyEvent, type EventScheme } from './events.ts';
 import { hashFieldValue } from './hash.ts';
-import { readResourceBlob } from './resource-blob.ts';
+import { readResourceBlob, writeResourceBlob } from './resource-blob.ts';
 import { RefusedWriteError, type PerformAction, type PerformContext, type PushOutcome } from './head.ts';
 import { observeResources, type Completed, type ObservedResource } from './observe.ts';
 import type { RemoteExecute, RemoteExecuteResponse } from './remote-execute.ts';
-import type { StateSystemAdapters } from './state-system.ts';
+import { readRoot, type StateSystemAdapters } from './state-system.ts';
 
 type Unit = { manifest: DerivedManifest; surface: DerivedSurface; lane?: string };
 type Row = Record<string, unknown>;
 
 /** A JSON path's value: `a.b`, `a[0].b`, `$body.a` (the leading `$body.` read as the root). */
 function at(value: unknown, path: string): unknown {
+  if (value && typeof value === 'object' && Object.hasOwn(value, path)) return (value as Row)[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;
@@ -27,14 +29,68 @@ function at(value: unknown, path: string): unknown {
   return cur;
 }
 const object = (v: unknown): Row | undefined => (v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Row) : undefined);
-const parse = (r: RemoteExecuteResponse): unknown => { try { return r.body ? JSON.parse(r.body) : undefined; } catch { return r.body; } };
+const parse = (r: RemoteExecuteResponse): unknown => {
+  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: string): Array<{ url: string; params: Record<string, string> }> {
+  const links: Array<{ url: string; params: Record<string, string> }> = [];
+  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: Record<string, string> = {};
+    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: string): Row {
+  const decode = (t: string): string => t.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&#(\d+);/g, (_, n: string) => String.fromCodePoint(Number(n))).replace(/&amp;/g, '&');
+  type Node = { name: string; obj: Row; text: string; children: boolean };
+  const stack: Node[] = [{ name: '', obj: {}, text: '', children: false }];
+  const put = (parent: Node, name: string, value: unknown): void => {
+    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;
+}
 
 /** The manifest's resource a surface schema answers (the operation's `answers.resource` is the spec's schema name). */
 function resourceOf(m: DerivedManifest, schema: string | undefined): string | undefined {
   if (!schema) return undefined;
   if (m.resources[schema]) return schema;
-  const lower = schema.toLowerCase();
-  return Object.keys(m.resources).find((r) => r.toLowerCase() === lower || storedType(m, r).toLowerCase() === lower);
+  const normalized = (name: string): string => 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
@@ -62,6 +118,13 @@ function refusalWords(m: DerivedManifest, body: unknown): string {
   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: DerivedManifest, body: unknown): boolean {
+  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: unknown, resolve: (v: string) => string): unknown {
   if (typeof value === 'string') return resolve(value);
@@ -92,6 +155,30 @@ async function multipart(body: unknown, files: Row[], ctx: PerformContext): Prom
   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: DerivedOperation, path: string): string {
+  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: DerivedManifest, path: string, params: Record<string, unknown>): string {
+  if (!m.remoteHost) return path;
+  const { template, values } = m.remoteHost;
+  const host = template.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    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: DerivedOperation): Record<string, string> => Object.fromEntries(Object.entries(op.headers ?? {}).filter((e): e is [string, string] => typeof e[1] === 'string'));
+
 /** The body as the operation's encoding sends it. */
 function encode(op: DerivedOperation, body: unknown): { body?: string; type?: string } {
   if (body === undefined || op.bodyEncoding === 'none') return {};
@@ -111,6 +198,54 @@ function unitOf(units: Unit[], input: Row): Unit | undefined {
     ?? (input.graphql ? units[0] : undefined);
 }
 
+/** Read the schema-selected resource through response aliases and fragment selections. */
+async function graphqlAnswers(m: DerivedManifest, surface: DerivedSurface, input: Row, parsed: unknown): Promise<Array<{ resource: string; value?: Row }>> {
+  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 is import('graphql').FragmentDefinitionNode => d.kind === 'FragmentDefinition').map((d) => [d.name.value, d]));
+  const fields = (selection: import('graphql').SelectionSetNode, seen = new Set<string>()): import('graphql').FieldNode[] => 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: unknown, selection?: import('graphql').SelectionSetNode): unknown => {
+    if (Array.isArray(value)) return value.map((v) => decode(v, selection));
+    const row = object(value);
+    if (!row || !selection) return value;
+    const decoded: Row = {};
+    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: Array<{ resource: string; value?: Row }> = [];
+  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. */
@@ -125,7 +260,7 @@ async function adoptAccount(units: Unit[], execute: RemoteExecute, ctx: PerformC
     const scope = decl.refresh;
     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));
     const id = items.length === 1 ? storedIdOf(decl, items[0]!) : undefined;
@@ -145,9 +280,15 @@ function performOf(units: Unit[]): PerformAction {
     const types = [...new Set(Object.keys(m.resources).map((r) => storedType(m, r)))];
     const resolve = (v: string): string => { for (const t of types) { const r = ctx.resolve(t, v); if (r !== v) return r; } return v; };
     let method: string; let path: string; let body: unknown; let op: DerivedOperation | undefined;
+    // the parameters a lane's own host is filled from, as the vendor names them
+    let hostParams: Record<string, unknown> = {};
     if (input.graphql) {
       const gql = (m as { graphql?: { paths: string[] } }).graphql;
-      method = 'POST'; path = gql?.paths[0] ?? '/graphql'; body = resolvedDeep(input.graphql, resolve);
+      method = 'POST'; path = gql?.paths[0] ?? '/graphql';
+      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)!;
       method = op.method.toUpperCase();
@@ -171,7 +312,9 @@ function performOf(units: Unit[]): PerformAction {
       path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, name: string) => encodeURIComponent(resolve(String(params[name] ?? ''))));
       const query = new URLSearchParams(Object.entries(queried).flatMap(([k, v]) => (Array.isArray(v) ? v : [v]).map((x): [string, string] => [k, resolve(String(x))])));
       if ([...query].length) path += `?${query}`;
+      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 as Row[]) : [];
     // a body recorded as it came (not JSON) goes as it came
@@ -179,23 +322,49 @@ function performOf(units: Unit[]): PerformAction {
     const raw = asCame && typeof asCame.$text === 'string' ? { body: asCame.$text as string } : asCame && typeof asCame.$base64 === 'string' ? { body: new Uint8Array(Buffer.from(asCame.$base64 as string, 'base64')) } : undefined;
     const sent: { body?: string | Uint8Array; type?: string } = raw ? { ...raw, ...(typeof input.contentType === 'string' ? { type: input.contentType } : {}) }
       : files.length || op?.bodyEncoding === 'multipart' ? await multipart(body, files, ctx) : op ? encode(op, body) : { body: JSON.stringify(body), type: 'application/json' };
-    const headers: Record<string, string> = { ...((object(input.headers) ?? {}) as Record<string, string>), ...(sent.type ? { 'content-type': sent.type } : {}) };
+    const headers: Record<string, string> = { ...(op ? fixedHeaders(op) : {}), ...((object(input.headers) ?? {}) as Record<string, string>), ...(sent.type ? { 'content-type': sent.type } : {}) };
     // a retried deploy makes nothing twice, and two Worlds deploying into one account never collide
     if (m.idempotency) headers[m.idempotency.header] = hashFieldValue({ credential: ctx.credential ?? '', entry: first.id });
-    const answer = await execute({ method, path, headers, ...(sent.body !== undefined ? { body: sent.body } : {}), ...(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') as Row[] : [];
     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: Array<{ actionId: string; externalId: string; data: Row }> = [];
+      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 = (): Row | undefined => {
+      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: ResourceDecl | undefined = 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 = (): ResourceDecl | undefined => Object.entries(m.resources).find(([r]) => storedType(m, r) === group.at(-1)!.subject.type)?.[1];
+    const decl: ResourceDecl | undefined = resource ? m.resources[resource] : subjectDecl();
     const idOf = (o: Row | undefined, d: ResourceDecl | undefined): string | undefined => { const v = o?.[d?.idAs ?? 'id']; return typeof v === 'string' ? v : undefined; };
     // the group's entry the answer is: of the answered resource's stored type (a cascade writes children first), else
     // the last; a delete answers its subject's own vendor id
@@ -209,9 +378,9 @@ function performOf(units: Unit[]): PerformAction {
     // 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: Array<{ actionId: string; externalId: string }> = [];
-    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') also.push({ actionId: entry.id, externalId: id });
@@ -255,7 +424,7 @@ function vendorFieldParams(m: DerivedManifest, resource: string, params: Record<
   const parent = decl.parent;
   const parentType = parent ? storedType(m, parent.resource) : undefined;
   const where = Object.entries(parent?.where ?? {}).map(([field, template]) => [field, template, fill(template)] as const);
-  const localParent = where.length ? tree.find((r) => r.type === parentType && where.every(([f, , v]) => String(r[f]) === v)) : undefined;
+  const 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);
@@ -266,16 +435,40 @@ function vendorFieldParams(m: DerivedManifest, resource: string, params: Record<
     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]); }
+  if (parentCopy) for (const [field, template] of where) { const one = /^\{([^}]+)\}$/.exec(template); 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: unknown): unknown[] => (Array.isArray(v) ? v : v === undefined || v === null || v === '' ? [] : [v]);
+
 function itemsOf(op: DerivedOperation, parsed: unknown): Row[] {
   const v = op.answers?.key ? at(parsed, op.answers.key) : parsed;
   const list = Array.isArray(v) ? v : Array.isArray(at(parsed, 'data')) ? (at(parsed, 'data') as unknown[]) : Array.isArray(at(parsed, 'results')) ? (at(parsed, 'results') as unknown[]) : [];
   return list.map(object).filter((x): x is Row => x !== undefined);
 }
 
+/** A vendor response may hold download links in an object map or an array. Missing optional paths yield none. */
+function valuesAt(value: unknown, keys: readonly string[]): unknown[] {
+  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 as Row)[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: object, fields: Record<string, unknown>): string | undefined {
+  const field = (scope as { idAs?: string }).idAs;
+  if (field?.includes('{')) return field.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    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: Unit[], service: string): NonNullable<StateSystemAdapters['refresh']> {
   return async (execute, opts) => {
     const observed: ObservedResource[] = [];
@@ -283,53 +476,228 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
     // 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: Array<{ type: string; path: string; status: number }> = [];
     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: string, seen = new Set<string>()): number => { const p = m.resources[r]?.parent?.resource; return p && !seen.has(p) ? 1 + depth(p, seen.add(r)) : 0; };
       const order = scoped.sort(([a], [b]) => depth(a) - depth(b));
       for (const [resource, decl] of order) {
         const scope = decl.refresh!;
+        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];
+        // 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: string[] = [];
+          // 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 } as Row;
+            const vendorId = aliases.get(key) ?? String(r.id);
+            for (const [name, template] of Object.entries(scope.params ?? {})) subject[name] = template.replace(/\{([^}]+)\}/g, (_, field: string) => {
+              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: string) =>
+              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: string): string => t.replace(/\{([^}]+)\}/g, (_, n: string) => 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 }); refused = true; break; }
+            if (answer.status === 429) throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
+            read.push(String(subject.id));
+            answered += 1;
+            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 as { worldFields?: Record<string, Record<string, unknown>> }).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);
+              }
+            }
+            // 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 as ObservedResource['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 parent of parents) {
-          const limit = m.list?.limit && (op.query ?? []).some((q) => q.name === m.list!.limit.param) ? { [m.list.limit.param]: String(m.list.limit.max) } : {};
-          let page: Record<string, string> = { ...limit };
+        for (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: string): string => t.replace(/\{([^}]+)\}/g, (_, n: string) => 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: Record<string, string> = { ...scope.query, ...limit };
+          const seenLinks = new Set<string>();
           for (let taken = 0; ;) {
             let unfilled = false;
-            const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n: string) => { const v = n === decl.parent?.param && parent !== undefined ? String(parent) : ''; if (!v) unfilled = true; return encodeURIComponent(v); });
+            const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n: string) => { 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`)
-            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 } : {}) });
+            // 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) throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);
+            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 ? ((at(parsed, scope.items) as unknown[] | undefined) ?? []).map((x) => object(x)).filter((x): x is Row => x !== undefined) : itemsOf(op, parsed);
-            for (const item of items) {
-              const fields = { ...item, ...(decl.parent && parent !== undefined ? { [decl.parent.field]: parent } : {}) };
-              const id = storedIdOf(decl, fields);
+              : 'items' in scope && scope.items ? listed(at(parsed, scope.items)).map((x) => object(x)).filter((x): x is Row => 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: Array<[string | undefined, Row]> = keyed
+              ? Object.entries(map!).map(([key, value]): [string | undefined, Row] => (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, Row] => [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): Array<[undefined, Row]> => {
+                  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: string) => {
+                  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) => 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 as { worldFields?: Record<string, Record<string, unknown>> }).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 as ObservedResource['fields'] });
             }
-            taken += items.length;
-            if ('get' in scope) break;
+            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: string | null;
+              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) as string | boolean)) 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;
@@ -337,9 +705,9 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
               continue;
             }
             const size = Number(limit[m.list?.limit.param ?? ''] ?? 0);
-            if (!items.length || (size && items.length < size)) break;
+            if (!pageItems.length || (size && pageItems.length < size)) break;
             if (!size) { whole = false; break; }
-            const last = items.at(-1)![decl.idAs ?? 'id'];
+            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) };
@@ -350,17 +718,151 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
         // 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) });
+        else if (whole && parents.length) 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: Array<{ key: string; bytes: Uint8Array }> = [];
+    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 = { ...row.fields, ...under?.params, id: row.id };
+          const path = `${op.basePath ?? surface.basePath ?? ''}${op.path}`.replace(/\{([^}]+)\}/g, (_, n: string) => {
+            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 } : {}) } as ObservedResource['fields'];
+          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: RemoteExecuteResponse | undefined;
+          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: string, key = ''): string => template.replace(/\{pathname\}/g, decodeURIComponent(pathname)).replace(/\{key\}/g, key).replace(/\{header:([^}]+)\}/g, (_, name: string) => {
+            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 as object), unread } : report;
   };
 }
 
+/** A declared GraphQL read over the same executor and atomic observation batch as REST. */
+async function refreshGraphql(m: DerivedManifest, resource: string, decl: ResourceDecl,
+  scope: Exclude<NonNullable<ResourceDecl['refresh']>, { none: string }>, execute: RemoteExecute,
+  rootScope: string | undefined, observed: ObservedResource[], complete: Completed[]): Promise<void> {
+  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: unknown): unknown => 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 ?? {}) as Row;
+    const cursors = new Set<string>();
+    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') as unknown[]).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 is Row => 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 as ObservedResource['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: NonNullable<ResourceDecl['parent']>, observations: ObservedResource[]): Array<{ params: Record<string, string>; value: string }> {
+  const out = new Map<string, { params: Record<string, string>; value: string }>();
+  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: Record<string, string> = {};
+    for (const [field, template] of Object.entries(parent.where ?? {})) {
+      const names: string[] = [];
+      // 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?: string) => (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: string) => 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: ResourceDecl, fields: Row): string | undefined {
@@ -414,7 +916,7 @@ function adopt(service: string, root: string | undefined, units: Unit[], observe
     const parentType = decl?.parent && m ? storedType(m, decl.parent.resource) : undefined;
     const resolved = (v: unknown): string => aliases.get(`${parentType}:${String(v)}`) ?? String(v);
     const siblings = pool.filter((p) => parentField === undefined || resolved(p.fields[parentField]) === String(o.fields[parentField]));
-    const keys = decl?.alternateKeys ?? [];
+    const 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;
     o.adopts = match[0]!.id;
@@ -425,7 +927,7 @@ function adopt(service: string, root: string | undefined, units: Unit[], observe
 }
 
 /** The event's resource: the declared `types`, else the manifest's events read backwards, else `<resource>.created|updated|deleted`. */
-function eventResource(m: DerivedManifest, decl: IngestDecl, type: string): { resource: string; deleted?: true } | undefined {
+function eventResource(m: DerivedManifest, decl: IngestDecl, type: string): NonNullable<IngestDecl['types']>[string] | undefined {
   if (decl.types?.[type]) return decl.types[type];
   for (const [operation, sent] of Object.entries(m.events?.types ?? {})) {
     if ((Array.isArray(sent) ? sent : [sent]).includes(type)) { const r = resourceOf(m, operation.split('.')[0]); if (r) return { resource: r, ...(/\.delete/.test(operation) ? { deleted: true as const } : {}) }; }
@@ -439,6 +941,7 @@ function eventResource(m: DerivedManifest, decl: IngestDecl, type: string): { re
 function older(theirs: unknown, held: unknown): boolean {
   if (theirs === undefined || theirs === null || held === undefined || held === null) return false;
   const a = Number(theirs); const b = Number(held);
+  if (/^-?\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)); const tb = Date.parse(String(held));
   if (Number.isFinite(ta) && Number.isFinite(tb)) return ta < tb;
@@ -453,7 +956,7 @@ function ingestOf(units: Unit[], decl: IngestDecl, service: string): NonNullable
     const schemes = (Array.isArray(decl.scheme) ? decl.scheme : [decl.scheme]) as EventScheme[];
     if (!ctx.secret || !schemes.some((s) => verifyEvent(s, ctx.secret!, body, headers, { now, tolerance: 300 }))) return Response.json({ error: 'invalid signature' }, { status: 401 });
     let event: unknown;
-    try { event = JSON.parse(body); } catch { return Response.json({ error: 'the event is not JSON' }, { status: 400 }); }
+    try { event = parseExactJson(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 });
@@ -463,9 +966,16 @@ function ingestOf(units: Unit[], decl: IngestDecl, service: string): NonNullable
     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;
+      // 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);
       // an event older than the root's copy folds nothing