@volter/world-core 3.0.163 → 3.0.165

package/dist/src/events.js

@@ -7,6 +7,7 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
+import { resolve } from 'node:path';
 import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from "./serve.js";
 import { equalSecrets as same, ksuidFrom } from "./signing.js";
 import { deliveryTraceHeaders } from "./trace-context.js";
@@ -223,6 +224,28 @@ const worldTransport = async (url, body, headers) => {
         return 0;
     }
 };
+const pendingDeliveries = new WeakMap();
+function forgetDeliveries(store, root, deliveries) {
+    const roots = pendingDeliveries.get(store), pending = roots?.get(root);
+    if (!pending)
+        return;
+    for (const delivery of deliveries)
+        pending.delete(delivery);
+    if (!pending.size)
+        roots.delete(root);
+    if (!roots.size)
+        pendingDeliveries.delete(store);
+}
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export async function settleEventDeliveries(root) {
+    const store = getActiveWorldStore(), path = resolve(root);
+    const deliveries = [...(pendingDeliveries.get(store)?.get(path) ?? [])];
+    const outcomes = await Promise.allSettled(deliveries);
+    forgetDeliveries(store, path, deliveries);
+    const failures = outcomes.flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+    if (failures.length)
+        throw new AggregateError(failures, 'Declared-event dispatch failed');
+}
 let deliveryObserver;
 export function setDeliveryObserver(observer) {
     const previous = deliveryObserver;
@@ -266,12 +289,16 @@ export async function askApplication(url, init, within, standIn) {
 }
 /** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
  *  that takes it, and recorded. */
-export async function deliverEvents(service, decl, write, data, transport = worldTransport, values) {
+export async function deliverEvents(service, decl, write, data, transport = worldTransport, values, application) {
     if (write.storedType === decl.store)
         return [];
+    const dispatch = application ? async (url, body, headers) => {
+        const answer = await application(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+        return answer === undefined ? transport(url, body, headers) : answer === 'unreachable' ? 0 : answer.status;
+    } : transport;
     const sent = [];
     for (const type of eventTypesOf(decl, write.operation))
-        sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type)));
+        sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type)));
     return sent;
 }
 /** One event type a write sends: to the live endpoints that take it, stored when the vendor keeps its events. */
@@ -364,11 +391,29 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     const store = getActiveWorldStore(), deliveryRoot = worldPaths(service, write.root).root;
     for (const d of sent)
         deliveryObserver?.({ ...d, service });
-    for (const packet of recorded)
-        setTimeout(() => {
-            // Persistence failure leaves a queued/sending claim for explicit recovery;
-            // it must not fail the already-committed vendor write or cause a blind resend.
-            void withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace)).catch(() => { });
+    const roots = pendingDeliveries.get(store) ?? new Map();
+    pendingDeliveries.set(store, roots);
+    const pending = roots.get(deliveryRoot) ?? new Set();
+    roots.set(deliveryRoot, pending);
+    for (const packet of recorded) {
+        let finish;
+        let fail;
+        const dispatched = new Promise((done, reject) => { finish = done; fail = reject; });
+        // Live writes return before dispatch; an explicit settlement reports persistence failures.
+        void dispatched.catch(() => { });
+        pending.add(dispatched);
+        setTimeout(async () => {
+            try {
+                await withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace));
+                finish();
+                forgetDeliveries(store, deliveryRoot, [dispatched]);
+            }
+            catch (error) {
+                // Keep the rejection until explicit settlement consumes it. The queued/sending claim remains for
+                // native recovery; this must not fail the already-committed vendor write or cause a blind resend.
+                fail(error);
+            }
         }, 0);
+    }
     return sent;
 }

package/dist/src/executor.d.ts

@@ -132,8 +132,8 @@ export declare function validateRemoteOrigin(origin: string, opts?: {
 /** `vendorHosts`: the pack's declared vendor host rules (its descriptor's `hosts`). An absolute https URL
  *  on one of them — an exact `host` rule whose `pathPattern` the path matches — is a second host of the
  *  same vendor that takes the credential (LinkedIn's image uploads on www.linkedin.com/dms-uploads,
- *  Instagram's rupload host); it is sent credentialed like an anchored call. Any other absolute URL is
- *  refused, as before. */
+ *  Instagram's rupload host); it is sent credentialed like an anchored call, as HTTP Basic when a rule naming
+ *  it names a `basic` user. Any other absolute URL is refused. */
 /** Where a credential is kept (the head's and refresh's root: head.ts rootCustody): `key` names the credential stably
  *  across rotations and anew when another is sealed in its place (the token cache is keyed by it, not by the secret's value), `open` reads it as sealed now, `seal` keeps a rotated one. */
 /** `unsealed`: where a rotation the seal failed to keep is recorded durably (the field and the cause, never a value), since

package/dist/src/executor.js

@@ -224,6 +224,8 @@ function direct(origin, credential, auth, vendorHosts, now = () => new Date()) {
         let target;
         // the vendor's own URL, where a loopback root stands in for it: what a signature is made over
         let vendorUrl;
+        // the user a host that takes the token as HTTP Basic's password names it under (HostRule.basic)
+        let basicUser;
         if (/^https:\/\//i.test(path) && vendorHosts?.length) {
             // a second host the pack declares for this vendor, on a path its rule names: validated as the root is
             target = new URL(path);
@@ -235,6 +237,7 @@ function direct(origin, credential, auth, vendorHosts, now = () => new Date()) {
             const declared = vendorHosts.some((r) => !r.exclude && named(r)) && !vendorHosts.some((r) => r.exclude && named(r));
             if (!declared)
                 throw new Error(`remote execute: ${target.host}${target.pathname.slice(0, 64)} is not a host this vendor's pack declares for this path`);
+            basicUser = vendorHosts.find((r) => !r.exclude && r.basic !== undefined && named(r))?.basic;
             // A loopback root is the vendor substitute. Preserve the vendor Host while retaining
             // the already-validated root's mounted path; an absolute URL never escapes that root.
             if (isLoopbackHost(origin.hostname)) {
@@ -258,6 +261,16 @@ function direct(origin, credential, auth, vendorHosts, now = () => new Date()) {
         else
             for (const [name, value] of Object.entries(credential.headers))
                 outbound.set(name, value);
+        // A HOST THAT TAKES THE TOKEN AS HTTP BASIC: the sealed authorization header's credentials, after its scheme, are
+        // Basic's password under the rule's user; one sealed as Basic goes as it is, and none sealed refuses before egress
+        if (issued === undefined && basicUser !== undefined) {
+            const sealed = outbound.get('authorization') ?? '';
+            const token = /^\S+\s+(\S.*)$/.exec(sealed)?.[1];
+            if (token === undefined)
+                throw new Error(`remote execute: ${target.host} takes the credential as HTTP Basic, and the sealed credential carries no authorization header`);
+            if (!/^basic\s/i.test(sealed))
+                outbound.set('authorization', `Basic ${btoa(`${basicUser}:${token}`)}`);
+        }
         // the vendor's host, kept over any the credential carries (a loopback twin routes by it, as the World's proxy's)
         if (vendorUrl) {
             outbound.set('host', vendorUrl.host);

package/dist/src/file-response.d.ts

@@ -5,6 +5,10 @@ export declare function fileResponse(path: string, init?: ResponseInit): Respons
  * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
  * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
  * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
- * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
-export declare function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl?: string): Response;
+export declare function bytesResponse(request: Request, bytes: Uint8Array | {
+    size: number;
+    range(start: number, end: number): Promise<Uint8Array | null>;
+}, contentType: string, cacheControl?: string): Response;

package/dist/src/file-response.js

@@ -24,10 +24,11 @@ export function fileResponse(path, init) {
  * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
  * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
  * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
- * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
 export function bytesResponse(request, bytes, contentType, cacheControl = 'public, max-age=604800, immutable') {
-    const total = bytes.length;
+    const total = bytes instanceof Uint8Array ? bytes.length : bytes.size;
     const base = { 'content-type': contentType, 'x-content-type-options': 'nosniff', 'accept-ranges': 'bytes', 'cache-control': cacheControl };
     const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
     let start = 0;
@@ -47,9 +48,32 @@ export function bytesResponse(request, bytes, contentType, cacheControl = 'publi
     // every satisfiable range is answered as one, the whole body's `bytes=0-` included: a media player (Safari's) reads a
     // 206 with its Content-Range as the server taking ranges, and a 200 as one it cannot seek in
     const partial = valid;
-    const body = bytes.slice(start, end + 1);
-    return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
+    let body = null;
+    if (request.method !== 'HEAD') {
+        if (bytes instanceof Uint8Array)
+            body = new Blob([bytes.slice(start, end + 1)]);
+        else {
+            let at = start;
+            body = new ReadableStream({
+                async pull(controller) {
+                    if (at > end) {
+                        controller.close();
+                        return;
+                    }
+                    const last = Math.min(at + 8 * 1024 * 1024 - 1, end);
+                    const chunk = await bytes.range(at, last);
+                    if (!chunk) {
+                        controller.error(new Error('stored bytes are gone'));
+                        return;
+                    }
+                    controller.enqueue(chunk);
+                    at = last + 1;
+                },
+            });
+        }
+    }
+    return new Response(body, {
         status: partial ? 206 : 200,
-        headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+        headers: { ...base, 'content-length': String(end + 1 - start), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
     });
 }

package/dist/src/git/index.d.ts

@@ -6,3 +6,4 @@ export * from './smart-http.js';
 export * from './history.js';
 export * from './lfs.js';
 export * from './format.js';
+export * from './smart-http-client.js';

package/dist/src/git/index.js

@@ -6,3 +6,4 @@ export * from "./smart-http.js";
 export * from "./history.js";
 export * from "./lfs.js";
 export * from "./format.js";
+export * from "./smart-http-client.js";

package/dist/src/git/smart-http-client.d.ts

@@ -0,0 +1,28 @@
+import { type GitObjectStore } from './objects.js';
+import { type Service } from './smart-http.js';
+/** One exchange: `GET info/refs?service=<service>` when there is no body, `POST <service>` when there is. It answers
+ *  the response's bytes, and throws when the server did not answer 200. */
+export type SmartHttpTransport = (request: {
+    service: Service;
+    body?: Uint8Array;
+}) => Promise<Uint8Array>;
+/** What a server advertises: its refs (peeled `^{}` lines dropped), the ref its HEAD names, and its capabilities. */
+export type RemoteRefs = {
+    refs: Map<string, string>;
+    head: string | null;
+    caps: string[];
+};
+/** `GET info/refs?service=<service>`, read. */
+export declare function lsRemote(transport: SmartHttpTransport, service: Service): Promise<RemoteRefs>;
+/** `POST git-upload-pack` with `done`: every object `wants` reach and `haves` do not, read into `store`. */
+export declare function fetchPack(transport: SmartHttpTransport, store: GitObjectStore, wants: string[], haves: string[]): Promise<void>;
+/** One ref update a push asks for: `old` is the server's value as advertised (ZERO_SHA to create), `new` the object
+ *  to point it at (ZERO_SHA to delete). */
+export type PushCommand = {
+    name: string;
+    old: string;
+    new: string;
+};
+/** `POST git-receive-pack`: the commands and the pack of what they need beyond `haves`, atomic when `atomic` (the
+ *  server offered it). Answers each command's outcome by ref name: null when the server took it, else its reason. */
+export declare function sendPack(transport: SmartHttpTransport, store: GitObjectStore, commands: PushCommand[], haves: string[], atomic?: boolean): Promise<Map<string, string | null>>;

package/dist/src/git/smart-http-client.js

@@ -0,0 +1,95 @@
+// THE CLIENT HALF OF SMART HTTP (gitprotocol-http, protocol v0): what `git fetch` and `git push` send to a server,
+// over a transport the caller supplies. The library opens no socket, holds no credential and names no host; a root's
+// refresh and deploy reach the vendor's git through it over the kernel executor (derived-real.ts, ADR 0031). It asks
+// only for what it reads: no side-band (the pack arrives bare), no multi_ack (one answer), no thin pack (every delta
+// base is in the pack or the store), ofs-delta (readPack resolves both delta kinds), and on a push report-status, with
+// atomic when the server offers it.
+import { concat } from "./objects.js";
+import { readPack } from "./pack.js";
+import { FLUSH, ZERO_SHA, packObjects, pktLine, readPktLines } from "./smart-http.js";
+const DEC = new TextDecoder();
+const SHA = /^[0-9a-f]{40}$/;
+/** `GET info/refs?service=<service>`, read. */
+export async function lsRemote(transport, service) {
+    let { lines, rest } = readPktLines(await transport({ service }));
+    if (lines[0]?.startsWith('# service='))
+        ({ lines, rest } = readPktLines(rest));
+    const refs = new Map();
+    let head = null;
+    let caps = [];
+    for (const raw of lines) {
+        const [line, offered] = raw.replace(/\n$/, '').split('\0');
+        if (line.startsWith('ERR '))
+            throw new Error(`git ${service}: ${line.slice(4)}`);
+        if (offered !== undefined) {
+            caps = offered.split(' ').filter(Boolean);
+            const symref = caps.find((c) => c.startsWith('symref=HEAD:'));
+            if (symref)
+                head = symref.slice('symref=HEAD:'.length);
+        }
+        const sha = line.slice(0, 40);
+        const name = line.slice(41);
+        if (!SHA.test(sha) || sha === ZERO_SHA || name === 'HEAD' || name.endsWith('^{}'))
+            continue;
+        refs.set(name, sha);
+    }
+    return { refs, head, caps };
+}
+const isPack = (bytes, at) => DEC.decode(bytes.subarray(at, at + 4)) === 'PACK';
+/** `POST git-upload-pack` with `done`: every object `wants` reach and `haves` do not, read into `store`. */
+export async function fetchPack(transport, store, wants, haves) {
+    if (wants.length === 0)
+        return;
+    const answer = await transport({
+        service: 'git-upload-pack',
+        body: concat(pktLine(`want ${wants[0]} ofs-delta no-progress agent=volter-twin\n`), ...wants.slice(1).map((w) => pktLine(`want ${w}\n`)), FLUSH, ...haves.map((h) => pktLine(`have ${h}\n`)), pktLine('done\n')),
+    });
+    // the negotiation's ACK / NAK lines, then the pack
+    let at = 0;
+    while (at + 4 <= answer.length && !isPack(answer, at)) {
+        const len = parseInt(DEC.decode(answer.subarray(at, at + 4)), 16);
+        if (Number.isNaN(len))
+            break;
+        if (len < 4) {
+            at += 4;
+            continue;
+        }
+        const line = DEC.decode(answer.subarray(at + 4, at + len));
+        if (line.startsWith('ERR '))
+            throw new Error(`git upload-pack: ${line.slice(4).trim()}`);
+        at += len;
+    }
+    if (!isPack(answer, at))
+        throw new Error('git upload-pack: the server answered no pack');
+    await readPack(answer.subarray(at), store);
+}
+/** `POST git-receive-pack`: the commands and the pack of what they need beyond `haves`, atomic when `atomic` (the
+ *  server offered it). Answers each command's outcome by ref name: null when the server took it, else its reason. */
+export async function sendPack(transport, store, commands, haves, atomic = false) {
+    const updates = commands.filter((c) => c.new !== ZERO_SHA).map((c) => c.new);
+    const caps = `report-status${atomic ? ' atomic' : ''} agent=volter-twin`;
+    const answer = await transport({
+        service: 'git-receive-pack',
+        body: concat(...commands.map((c, i) => pktLine(`${c.old} ${c.new} ${c.name}${i === 0 ? `\0${caps}` : ''}\n`)), FLUSH, 
+        // a push of deletions alone sends no pack (gitprotocol-pack, "Pushing data to a server")
+        ...(updates.length ? [await packObjects(store, updates, haves)] : [])),
+    });
+    const report = readPktLines(answer).lines.map((l) => l.replace(/\n$/, ''));
+    const failure = report.find((l) => l.startsWith('ERR '));
+    if (failure)
+        throw new Error(`git receive-pack: ${failure.slice(4)}`);
+    const unpack = report.find((l) => l.startsWith('unpack '))?.slice('unpack '.length);
+    if (unpack === undefined)
+        throw new Error('git receive-pack: the server sent no report');
+    const out = new Map(commands.map((c) => [c.name, unpack === 'ok' ? 'the server reported nothing for it' : `unpacker error: ${unpack}`]));
+    for (const l of report) {
+        if (l.startsWith('ok '))
+            out.set(l.slice(3), null);
+        else if (l.startsWith('ng ')) {
+            const rest = l.slice(3);
+            const sp = rest.indexOf(' ');
+            out.set(sp === -1 ? rest : rest.slice(0, sp), sp === -1 ? 'refused' : rest.slice(sp + 1));
+        }
+    }
+    return out;
+}

package/dist/src/git/smart-http.d.ts

@@ -16,6 +16,9 @@ export declare function readAllPktLines(bytes: Uint8Array): {
 export type Service = 'git-upload-pack' | 'git-receive-pack';
 /** `GET info/refs?service=<service>`: the ref advertisement, HEAD first as a symref. */
 export declare function advertisement(service: Service, refs: GitRefs): Uint8Array;
+/** The pack of every object `wants` reach that the `haves` the store holds do not: what a push sends (a client's
+ *  send-pack, smart-http-client.ts). */
+export declare function packObjects(store: GitObjectStore, wants: string[], haves: string[]): Promise<Uint8Array>;
 /** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. A request with `deepen <n>` is shallow:
  *  its answer opens with the shallow-update section (`shallow <sha>` for each boundary commit, `unshallow <sha>` for a
  *  commit the client held shallow whose parents it now receives, then a flush), and its pack stops at the boundary. */

package/dist/src/git/smart-http.js

@@ -105,6 +105,15 @@ async function closure(store, roots, seen) {
     return out;
 }
 async function reachable(store, roots) { const seen = new Set(); await closure(store, roots, seen); return seen; }
+/** The pack of every object `wants` reach that the `haves` the store holds do not: what a push sends (a client's
+ *  send-pack, smart-http-client.ts). */
+export async function packObjects(store, wants, haves) {
+    const known = [];
+    for (const h of haves)
+        if (await store.has(h))
+            known.push(h);
+    return writePack(await closure(store, wants, await reachable(store, known)));
+}
 /**
  * A shallow request's commits (gitprotocol-pack, "Shallow requests"): every commit within `depth` of a want (a want is
  * depth 1), and the boundary, the commits whose parents the client will not have. The client's own shallow commits it

package/dist/src/head.d.ts

@@ -19,6 +19,12 @@ export type PushOutcome = {
         externalId: string;
         data?: Record<string, unknown>;
     }>;
+    /** the group's entries the vendor refused while it took the rest (a git push to a root without `atomic`, each ref its
+     *  own outcome: ADR 0031); each settles refused with its reason */
+    refused?: Array<{
+        actionId: string;
+        reason: string;
+    }>;
 };
 /** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an
  *  entry authored against `twin-1` crosses against `REAL-42` once that subject's landing adopted it). */
@@ -140,6 +146,11 @@ export type DeployReport = {
         actionId: string;
         error: string;
     };
+    /** a group the vendor took in part: its entries it refused, each with its reason; nothing after it was attempted */
+    partial?: Array<{
+        actionId: string;
+        reason: string;
+    }>;
     /** entries after the refusal or failure, not attempted */
     skipped: string[];
     /** entries whose landed copy already said `deployed` — not performed again */
@@ -149,7 +160,7 @@ export type DeployReport = {
 };
 /** The branch entries a root twin still has to settle: `set` rows, not reverted, whose landed copy is absent or says
  *  `failed`/`skipped` (a `deployed` or `refused` copy settles the entry), split into what is offered to the vendor (a
- *  surface write on a subject the vendor can have) and what is the World's own: a write a door, a screen, the gap, the
+ *  surface write or a git push on a subject the vendor can have) and what is the World's own: a write a door, a screen, the gap, the
  *  clock or a seed made, and any write on a subject only the World's own writes made. */
 export declare function settlingEntries(service: string, root?: string): {
     offered: TwinAction[];
@@ -196,6 +207,10 @@ export declare function deferPerform<T>(request: string, fn: () => Promise<T>):
 export declare function performRequestGroup(service: string, request: string, root?: string): Promise<{
     ids: Map<string, string>;
     response?: RemoteExecuteResponse;
+    refused?: Array<{
+        actionId: string;
+        reason: string;
+    }>;
 } | RefusedWriteError | VendorWriteError>;
 /** Wrap a pack's fetch: a `RefusedWriteError` or `VendorWriteError` the head raised becomes the
  *  vendor's own error body (the pack's `shape`), so an app under live use sees what the vendor

package/dist/src/head.js

@@ -262,11 +262,12 @@ function receiptsByEntry(parent) {
 /** Whether an entry records a call of the vendor's surface (an operation or a GraphQL mutation): what a perform can send
  *  again (the real-system adapters, "What the derived core records with a write"). */
 function surfaceWrite(e) {
-    return typeof e.input?.operationId === 'string' || (e.input?.graphql !== undefined && e.input.graphql !== null);
+    // a push to a World repository is the vendor's too: a deploy sends it as a git push (derived-core.ts pushedInput)
+    return typeof e.input?.operationId === 'string' || (e.input?.graphql !== undefined && e.input.graphql !== null) || (e.input?.git !== undefined && e.input.git !== null);
 }
 /** The branch entries a root twin still has to settle: `set` rows, not reverted, whose landed copy is absent or says
  *  `failed`/`skipped` (a `deployed` or `refused` copy settles the entry), split into what is offered to the vendor (a
- *  surface write on a subject the vendor can have) and what is the World's own: a write a door, a screen, the gap, the
+ *  surface write or a git push on a subject the vendor can have) and what is the World's own: a write a door, a screen, the gap, the
  *  clock or a seed made, and any write on a subject only the World's own writes made. */
 export function settlingEntries(service, root) {
     const parent = parentEntries(service, root);
@@ -435,7 +436,14 @@ async function performNow(opts) {
             const answered = outcome.data !== null && typeof outcome.data === 'object' && !Array.isArray(outcome.data) ? outcome.data : {};
             const primary = resolved.find((a) => a.id === outcome.actionId) ?? resolved[0];
             const also = new Map((outcome.also ?? []).map((a) => [a.actionId, a]));
+            const refusedHere = new Map((outcome.refused ?? []).map((r) => [r.actionId, r.reason]));
             for (const action of resolved) {
+                const refusal = refusedHere.get(action.id);
+                if (refusal !== undefined) {
+                    settle(action, at, { status: 'refused', reason: refusal });
+                    refusedIds.add(action.subject.id);
+                    continue;
+                }
                 const answeredId = action === primary ? outcome.externalId : also.get(action.id)?.externalId;
                 const externalId = answeredId || aliases.get(`${action.subject.type}:${action.subject.id}`);
                 settle(action, at, { status: 'deployed', ...(action === primary && outcome.url ? { url: outcome.url } : {}) }, { ...action.fields, ...(action === primary ? answered : also.get(action.id)?.data ?? {}) }, externalId || undefined);
@@ -443,6 +451,10 @@ async function performNow(opts) {
                 report.pushed += 1;
                 report.deployed.push({ actionId: action.id, at, ...(externalId ? { externalId } : {}), ...(data !== undefined ? { data } : {}), ...(action === primary && outcome.response ? { response: outcome.response } : {}) });
             }
+            if (refusedHere.size) {
+                report.partial = [...refusedHere].map(([actionId, reason]) => ({ actionId, reason }));
+                stopped = true;
+            }
         }
         catch (error) {
             // a write the vendor refuses (a 4xx: it can never be sent as it is) settles the group refused, as a check's
@@ -545,24 +557,57 @@ export async function performRequestGroup(service, request, root) {
     }
     catch (error) {
         if (error instanceof DeploymentOrderError) {
-            for (const e of [...group].reverse())
-                revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+            revertRequest(service, request, group, root);
             return new VendorWriteError(`An earlier ${service} write is still pending; this request was rolled back before reaching the vendor. Retry after that write finishes.`, group[0].id);
         }
         throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error));
     }
     if (report.refused || report.failed) {
-        for (const e of [...group].reverse())
-            revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+        revertRequest(service, request, group, root);
         return report.refused ? new RefusedWriteError(report.refused.check, report.refused.reason, report.refused.actionId) : new VendorWriteError(report.failed.error, report.failed.actionId);
     }
+    if (report.partial)
+        revertRequest(service, request, group.filter((e) => report.partial.some((r) => r.actionId === e.id)), root);
     for (const d of report.deployed) {
         const e = group.find((g) => g.id === d.actionId);
         if (e && d.externalId && d.externalId !== e.subject.id)
             ids.set(e.subject.id, d.externalId);
     }
     const response = report.deployed.find((entry) => entry.response)?.response;
-    return { ids, ...(response ? { response } : {}) };
+    return { ids, ...(response ? { response } : {}), ...(report.partial ? { refused: report.partial } : {}) };
+}
+/** Revert what a request's refused entries made, latest first. An entry that is a declared push a screen recorded
+ *  (`input.git`, ADR 0031) owns the request's writes after it up to the next such push, its push's effects (the
+ *  reactions and vendor moves the pack runs on it), which go with it; any other refused entry goes alone, as the group
+ *  it is in. */
+function revertRequest(service, request, refused, root) {
+    const pushed = (e) => e.input?.git !== undefined && e.input.git !== null;
+    const undo = new Set();
+    if (refused.some(pushed)) {
+        const made = branchEntries(service, root).filter((e) => e.correlationId === request && e.op === 'set');
+        for (const r of refused) {
+            if (!pushed(r)) {
+                undo.add(r.id);
+                continue;
+            }
+            const at = made.findIndex((e) => e.id === r.id);
+            if (at < 0) {
+                undo.add(r.id);
+                continue;
+            }
+            undo.add(r.id);
+            for (const e of made.slice(at + 1)) {
+                if (pushed(e))
+                    break;
+                undo.add(e.id);
+            }
+        }
+    }
+    else
+        for (const r of refused)
+            undo.add(r.id);
+    for (const e of branchEntries(service, root).filter((x) => undo.has(x.id)).reverse())
+        revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
 }
 /** Wrap a pack's fetch: a `RefusedWriteError` or `VendorWriteError` the head raised becomes the
  *  vendor's own error body (the pack's `shape`), so an app under live use sees what the vendor

package/dist/src/html.d.ts

@@ -0,0 +1,29 @@
+export type HtmlAttribute = {
+    name: string;
+    value: string;
+    prefix?: string;
+    namespace?: string;
+};
+export type HtmlElement = {
+    type: 'element';
+    name: string;
+    namespace: string;
+    attributes: HtmlAttribute[];
+    children: HtmlNode[];
+};
+export type HtmlText = {
+    type: 'text';
+    value: string;
+};
+export type HtmlNode = HtmlElement | HtmlText;
+export declare class HtmlError extends Error {
+    readonly code: 'parser-unavailable';
+    constructor(code: 'parser-unavailable');
+}
+/**
+ * A fragment parsed as WHATWG fragment parsing does in an HTML `<body>` context: elements and text, comments dropped,
+ * an HTML `<template>`'s content carried as that element's children. Importing this module does not load the grammar.
+ */
+export declare function parseFragment(source: string): Promise<HtmlNode[]>;
+/** Nodes serialized by the WHATWG HTML fragment serialization: its escaping, its void elements, its foreign names. */
+export declare function serialize(nodes: HtmlNode[]): Promise<string>;

package/dist/src/html.js

@@ -0,0 +1,64 @@
+export class HtmlError extends Error {
+    code;
+    constructor(code) {
+        super('HTML parser parse5 7.3.0 is unavailable');
+        this.code = code;
+        this.name = 'HtmlError';
+    }
+}
+let grammar;
+function loadGrammar() {
+    return grammar ??= import('parse5').catch(() => { grammar = undefined; throw new HtmlError('parser-unavailable'); });
+}
+/**
+ * A fragment parsed as WHATWG fragment parsing does in an HTML `<body>` context: elements and text, comments dropped,
+ * an HTML `<template>`'s content carried as that element's children. Importing this module does not load the grammar.
+ */
+export async function parseFragment(source) {
+    const { parseFragment: parse, defaultTreeAdapter: tree, html } = await loadGrammar();
+    const convert = (nodes) => {
+        const out = [];
+        for (const node of nodes) {
+            if (node.nodeName === '#text')
+                out.push({ type: 'text', value: node.value });
+            else if ('tagName' in node) {
+                const element = node;
+                // only an HTML template has content; an SVG or MathML `template` is a foreign element with children
+                const children = element.tagName === 'template' && element.namespaceURI === html.NS.HTML
+                    ? element.content.childNodes
+                    : element.childNodes;
+                out.push({
+                    type: 'element', name: element.tagName, namespace: element.namespaceURI,
+                    attributes: element.attrs.map(attr => ({ name: attr.name, value: attr.value, ...(attr.prefix ? { prefix: attr.prefix } : {}), ...(attr.namespace ? { namespace: attr.namespace } : {}) })),
+                    children: convert(children),
+                });
+            }
+        }
+        return out;
+    };
+    return convert(parse(tree.createElement('body', html.NS.HTML, []), source, {}).childNodes);
+}
+/** Nodes serialized by the WHATWG HTML fragment serialization: its escaping, its void elements, its foreign names. */
+export async function serialize(nodes) {
+    const { serialize: write, defaultTreeAdapter: tree, html } = await loadGrammar();
+    const append = (parent, list) => {
+        for (const node of list) {
+            if (node.type === 'text') {
+                tree.insertText(parent, node.value);
+                continue;
+            }
+            const element = tree.createElement(node.name, node.namespace, node.attributes.map(({ name, value, prefix, namespace }) => ({ name, value, ...(prefix ? { prefix } : {}), ...(namespace ? { namespace } : {}) })));
+            tree.appendChild(parent, element);
+            if (node.name === 'template' && node.namespace === html.NS.HTML) {
+                const content = tree.createDocumentFragment();
+                tree.setTemplateContent(element, content);
+                append(content, node.children);
+            }
+            else
+                append(element, node.children);
+        }
+    };
+    const fragment = tree.createDocumentFragment();
+    append(fragment, nodes);
+    return write(fragment);
+}