@superbee/core 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/remote-backend.js

@@ -2,12 +2,14 @@
  * `RemoteBackend` — a {@link StorageBackend} implemented over the wire-protocol v0
  * reference contract (`docs/WIRE-PROTOCOL.md`, `@superbee/server`).
  *
- * This is the client half of the seam over HTTP: every method maps directly to a wire endpoint,
- * and response versions remain the same content-addressed {@link Version} tokens local backends
- * produce. Tri-backend contract tests pin that invariant.
+ * This is the client half of the seam over HTTP: every method maps directly to a wire endpoint
+ * (a guarded document write may first ask `GET /v0/capabilities` whether the host records
+ * outcomes; see {@link RemoteBackendOptions.maxRetries}), and response versions remain the same
+ * content-addressed {@link Version} tokens local backends produce. Tri-backend contract tests pin
+ * that invariant.
  *
  * Zero new dependencies: it calls an injectable {@link FetchLike} transport
- * (defaulting to the global `fetch`, available on Node >= 20) with a constructed
+ * (defaulting to the global `fetch`, available in every supported Node runtime) with a constructed
  * `Request`. That means the SAME adapter runs against a real HTTP server, or — in
  * tests — directly against an in-process `createRouter(bundle)` function with no
  * sockets: `createRouter` returns exactly the `(req: Request) => Promise<Response>`
@@ -42,29 +44,16 @@
  */
 import { DEFAULT_BLOB_CONTENT_TYPE } from "./content-type.js";
 import { InvalidInputError } from "./errors.js";
-import { headsDigest, isHeadsDigest } from "./heads-digest.js";
+import { MalformedDocumentError } from "./frontmatter-contract.js";
+import { encodeRemoteDocument } from "./remote-document-codec.js";
+import { RemoteError, malformed } from "./remote-error.js";
+import { SNAPSHOT_TRUNCATED, parseHeadsAnswer, readSnapshotStream } from "./remote-parsers.js";
 import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, assertSafeReservedFilename, compareStorageKeys } from "./paths.js";
-import { isRequestIdentity } from "./uncertain-write.js";
-import { VersionConflict, stripETagWrapper } from "./version-transport.js";
-/**
- * A non-2xx wire response that is neither a `404` (ENOENT-shaped) nor a `412`
- * ({@link VersionConflict}) — the generic case, carrying the error envelope's `code` alongside
- * the raw HTTP `status`, so a caller can distinguish e.g.
- * `AUTH_REQUIRED` (401, an unauthenticated/misconfigured `--remote`) from `RUNTIME` (5xx, a
- * genuine server-side bug) instead of both collapsing into a generically-classified `Error`.
- */
-export class RemoteError extends Error {
-    /** The envelope's `code` field, or a status-derived guess when the envelope is missing/unparseable. */
-    code;
-    /** The raw HTTP status that produced this error. */
-    status;
-    constructor(message, code, status, cause) {
-        super(message, cause === undefined ? undefined : { cause });
-        this.name = "RemoteError";
-        this.code = code;
-        this.status = status;
-    }
-}
+import { isRequestIdentity, mintRequestId } from "./uncertain-write.js";
+import { VersionConflict, isContentVersion, stripETagWrapper } from "./version-transport.js";
+// The typed rejection lives in `remote-error.ts`, shared with the heads and snapshot parsers this
+// backend calls; it stays importable from here for every existing consumer.
+export { RemoteError } from "./remote-error.js";
 /** An ENOENT-shaped rejection so missing-document handling matches the local adapters. */
 function notFound(id) {
     const err = new Error(`no concept document '${id}'`);
@@ -111,6 +100,18 @@ function assertValidExpectedVersion(expectedVersion) {
 }
 /** The header that carries a write's durable request identity (`docs/WIRE-PROTOCOL.md`). */
 const IDENTITY_HEADER = "Idempotency-Key";
+/** The wire's `400 USAGE` message from a host that records no outcomes, answering any request that carries a key. */
+const IDENTITY_UNSUPPORTED = "request identity is not supported by this host";
+/** Whether `res` is a host's refusal of request identity itself, as opposed to a recorded or document refusal. */
+async function refusesIdentity(res) {
+    try {
+        const envelope = (await res.json());
+        return envelope?.error?.code === "USAGE" && envelope.error.message === IDENTITY_UNSUPPORTED;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Reject a request identity the wire would refuse before any request is sent, so a malformed
  * key is a caller-side `InvalidInputError` rather than a `400` the caller might mistake for a
@@ -123,129 +124,10 @@ function assertRequestIdentity(requestId) {
 }
 /** The lookup route's `200` body: a recorded outcome, never `unknown`. */
 const RECORDED_OUTCOME_KINDS = new Set(["committed", "conflict", "refused"]);
-/** A snapshot body that ended, or failed, before its terminator arrived with the announced count. */
-const SNAPSHOT_TRUNCATED = "SNAPSHOT_TRUNCATED";
-/**
- * A snapshot whose body arrived whole, with its terminator and the announced count, but whose
- * rows digest to something other than the header announced. Not truncation: re-requesting will
- * not necessarily repair it, since the authority contradicted itself. A consumer discards the
- * documents' claim to the header digest either way.
- */
-const SNAPSHOT_DIGEST_MISMATCH = "SNAPSHOT_DIGEST_MISMATCH";
-function isDocumentHead(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    const head = value;
-    return typeof head.id === "string" && typeof head.version === "string";
-}
-/** A wire payload the authority produced but the contract does not admit: not retried, not truncation. */
-function malformed(message) {
-    return new RemoteError(message, "RUNTIME", 502);
-}
 /** Quote a bare digest for `If-None-Match`; an already quoted or weak form passes through. */
 function etagForm(token) {
     return token.startsWith('"') || token.startsWith("W/") ? token : `"${token}"`;
 }
-/**
- * Split a response body into its NDJSON lines as they arrive, decoding UTF-8 across chunk
- * boundaries. Only `TextDecoder` and the Web Streams reader are used, so the same code runs in a
- * browser. A partial trailing line at the end of the body is a cut line and is not yielded; a
- * transport failure while reading is reported as truncation, since either way the terminator
- * never arrived. Leaving the loop early cancels the reader so the connection is released.
- */
-async function* ndjsonLines(body, status) {
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let buffered = "";
-    try {
-        for (;;) {
-            let chunk;
-            try {
-                chunk = await reader.read();
-            }
-            catch (cause) {
-                throw new RemoteError("snapshot body failed before its end line arrived", SNAPSHOT_TRUNCATED, status, cause);
-            }
-            buffered += decoder.decode(chunk.value, { stream: !chunk.done });
-            let start = 0;
-            for (let newline = buffered.indexOf("\n"); newline !== -1; newline = buffered.indexOf("\n", start)) {
-                yield buffered.slice(start, newline);
-                start = newline + 1;
-            }
-            buffered = buffered.slice(start);
-            if (chunk.done)
-                return;
-        }
-    }
-    finally {
-        await reader.cancel().catch(() => undefined);
-    }
-}
-function parseSnapshotLine(line) {
-    let record;
-    try {
-        record = JSON.parse(line);
-    }
-    catch {
-        throw malformed("snapshot line is not JSON");
-    }
-    if (typeof record !== "object" || record === null)
-        throw malformed("snapshot line is not a JSON object");
-    return record;
-}
-function parseSnapshotHeader(line) {
-    const record = parseSnapshotLine(line);
-    if (record.kind !== "snapshot")
-        throw malformed("snapshot did not begin with its header line");
-    if (typeof record.count !== "number" || !Number.isInteger(record.count) || record.count < 0) {
-        throw malformed("snapshot header carries no document count");
-    }
-    if (!isHeadsDigest(record.digest))
-        throw malformed("snapshot header carries no well-formed digest");
-    return { count: record.count, digest: record.digest };
-}
-/**
- * The document lines of a snapshot, ending normally only at an `end` line whose count equals
- * both the header's announcement and the documents actually seen, and only when the digest
- * recomputed over the received heads equals the header's. Anything else is a rejection: a body
- * that ends first is `SNAPSHOT_TRUNCATED`; a whole body whose heads digest differently is
- * `SNAPSHOT_DIGEST_MISMATCH`; a line the contract does not admit is malformed. The digest is the
- * client's own check of the listing it is about to trust: a count and a terminator say the body
- * is whole, only the recipe says it is the state the header named.
- */
-async function* snapshotDocuments(lines, header, status) {
-    let seen = 0;
-    const received = [];
-    for await (const line of lines) {
-        const record = parseSnapshotLine(line);
-        if (record.kind === "doc") {
-            if (typeof record.id !== "string" || typeof record.version !== "string" || typeof record.body !== "string") {
-                throw malformed("snapshot doc line lacks id, version, or body");
-            }
-            if (typeof record.frontmatter !== "object" || record.frontmatter === null || Array.isArray(record.frontmatter)) {
-                throw malformed("snapshot doc line lacks a frontmatter object");
-            }
-            seen += 1;
-            if (seen > header.count)
-                throw malformed(`snapshot delivered more than the ${header.count} announced document(s)`);
-            received.push({ id: record.id, version: record.version });
-            yield { id: record.id, version: record.version, frontmatter: record.frontmatter, body: record.body };
-            continue;
-        }
-        if (record.kind === "end") {
-            if (record.count !== seen || seen !== header.count) {
-                throw new RemoteError(`snapshot end line counts ${String(record.count)} document(s), but ${seen} of ${header.count} announced arrived`, SNAPSHOT_TRUNCATED, status);
-            }
-            const recomputed = headsDigest(received);
-            if (recomputed !== header.digest) {
-                throw new RemoteError(`snapshot header announced digest ${header.digest}, but its ${seen} document(s) digest to ${recomputed}`, SNAPSHOT_DIGEST_MISMATCH, status);
-            }
-            return;
-        }
-        throw malformed(`snapshot line has unexpected kind ${JSON.stringify(record.kind)}`);
-    }
-    throw new RemoteError(`snapshot ended after ${seen} of ${header.count} document(s) without its end line`, SNAPSHOT_TRUNCATED, status);
-}
 /**
  * Transient HTTP statuses worth retrying: 500 (a Cloudflare D1 cold-start surfaces as a 500
  * "storage caused object to be reset" the first time a hibernated database is hit), plus the edge
@@ -253,6 +135,18 @@ async function* snapshotDocuments(lines, header, status) {
  * REAL result, never retried; 501/505 are terminal server bugs, not transient, so also excluded.
  */
 const RETRIABLE_STATUS = new Set([500, 502, 503, 504]);
+/** A `500` naming a stored document that does not parse: a retry reads the same bytes again. */
+async function namesMalformedDocument(res) {
+    if (res.status !== 500)
+        return false;
+    try {
+        const envelope = (await res.clone().json());
+        return typeof envelope?.error?.details?.malformed?.reason === "string";
+    }
+    catch {
+        return false;
+    }
+}
 /** Retry-backoff timing: exponential base doubling, capped, with jitter to avoid a thundering herd. */
 const RETRY_BASE_MS = 150;
 const RETRY_CAP_MS = 2000;
@@ -298,6 +192,8 @@ export class RemoteBackend {
     fetchImpl;
     authToken;
     maxRetries;
+    /** The pending or settled answer to whether this host records outcomes; see {@link recordsOutcomes}. */
+    operationsSupport;
     constructor(options) {
         this.baseUrl = trimTrailingSlashes(options.baseUrl);
         this.bundle = options.bundle;
@@ -328,19 +224,23 @@ export class RemoteBackend {
         // object reset" when a hibernated database is first hit; also 502/503/504 from the edge) or a
         // network/transport error — with exponential backoff + jitter, so a hibernated-backend hiccup is
         // transparent instead of a hard failure. A REAL result (2xx, or 4xx incl. 412 VersionConflict,
-        // or 401) returns/throws immediately, never retried. Safe because every op is content-addressed
-        // + CAS: a retried write lands the same version or a conflict (possibly SPURIOUS — a prior
-        // attempt may have committed before its response was lost — but never silent data loss); a
-        // retried read is idempotent. `send` rebuilds the Request per attempt from `init` (bodies are
-        // strings/bytes, so reusable — no consumed-stream hazard).
+        // or 401) returns/throws immediately, never retried. A retried read is idempotent. `send`
+        // rebuilds the Request per attempt from the same `init` (bodies are strings/bytes, so reusable —
+        // no consumed-stream hazard), so every attempt carries the same headers, `Idempotency-Key`
+        // included.
         //
-        // A write that carries `Idempotency-Key` is different again: its transient retries are true
-        // replays, answered from the authority's recorded outcome, so a retry after a lost response
+        // A write that carries `Idempotency-Key` is therefore retried as a true replay, answered from
+        // the authority's recorded outcome while it keeps that record: a retry after a lost response
         // can neither apply twice nor surface a spurious conflict against its own earlier application.
+        // `write` and `delete` attach one to guarded document writes on a host with `operations` (see
+        // `maxRetries` for which). A guarded write without one lands the same version or a conflict
+        // (possibly SPURIOUS — a prior attempt may have committed before its response was lost), except
+        // that a document returned in between to exactly the state its premise names (the same bytes
+        // hash to the same version) lets the retry apply again over that change.
         for (let attempt = 0;; attempt++) {
             try {
                 const res = await this.fetchImpl(new Request(url, init));
-                if (RETRIABLE_STATUS.has(res.status) && attempt < this.maxRetries) {
+                if (RETRIABLE_STATUS.has(res.status) && attempt < this.maxRetries && !(await namesMalformedDocument(res))) {
                     await delay(retryDelayMs(attempt));
                     continue;
                 }
@@ -369,6 +269,12 @@ export class RemoteBackend {
             const actual = envelope?.error?.details?.actual ?? null;
             return new VersionConflict(fallbackId, expected, actual);
         }
+        const malformedDoc = envelope?.error?.details?.malformed;
+        if (malformedDoc && typeof malformedDoc.reason === "string") {
+            // The server could read the request but not the stored document: the same failure a local
+            // scan raises, so `onSkip` callers can set this one document aside.
+            return new MalformedDocumentError(typeof malformedDoc.id === "string" ? malformedDoc.id : fallbackId, new Error(malformedDoc.reason));
+        }
         const message = envelope?.error?.message ?? `wire request failed with status ${res.status}`;
         // The envelope's own `code` wins when present (every route in this repo's servers emits
         // one); a status-derived guess covers a malformed/absent envelope or a conformant-but-
@@ -433,15 +339,19 @@ export class RemoteBackend {
             headers["If-Match"] = options.expectedVersion;
         if (options.actor)
             headers["X-Actor"] = options.actor;
+        // Captured before the capability question can yield, so the payload is the document as it
+        // stood when `write` was called and an unencodable one is refused before any request.
+        const body = encodeRemoteDocument(doc.frontmatter, doc.body ?? "");
+        let minted = false;
         if (options.requestId !== undefined) {
             assertRequestIdentity(options.requestId);
             headers[IDENTITY_HEADER] = options.requestId;
         }
-        const res = await this.send(`/docs/${encodeId(id)}`, {
-            method: "PUT",
-            headers,
-            body: JSON.stringify({ frontmatter: doc.frontmatter, body: doc.body ?? "" }),
-        });
+        else if (options.expectedVersion !== undefined && (await this.recordsOutcomes())) {
+            headers[IDENTITY_HEADER] = mintRequestId();
+            minted = true;
+        }
+        const res = await this.sendDocWrite(`/docs/${encodeId(id)}`, { method: "PUT", headers, body }, minted);
         if (!res.ok)
             throw await this.toError(res, id);
         const payload = (await res.json());
@@ -449,10 +359,11 @@ export class RemoteBackend {
     }
     /**
      * `GET /v0/capabilities`, deployment-scoped: what this authority implements. `operations` says
-     * whether it records outcomes by request identity. A host without it ignores `Idempotency-Key`
-     * and answers the lookup route with a route-miss `404`, which {@link lookupOperation} cannot
-     * tell from "never recorded"; a consumer that relies on identity checks this once before it
-     * sends any intent. Missing booleans read as `false`.
+     * whether it records outcomes by request identity. The reference router without it refuses any
+     * request carrying `Idempotency-Key`, and the lookup route, with `400 USAGE`; a host that lacks
+     * the lookup route altogether answers it with a route-miss `404`, which {@link lookupOperation}
+     * cannot tell from "never recorded". A consumer that relies on identity checks this once before
+     * it sends any intent. Missing booleans read as `false`.
      */
     async wireCapabilities() {
         const res = await this.send("/v0/capabilities", { method: "GET" }, "deployment");
@@ -471,16 +382,65 @@ export class RemoteBackend {
             snapshot: flag("snapshot"),
         };
     }
+    /**
+     * Whether this host records outcomes by request identity, asked through `GET /v0/capabilities`
+     * and shared by concurrent callers. A host that answers anything but a `2xx` with
+     * `operations: true` is treated as not recording them, since a host that does not record them
+     * refuses a key with `400`. That answer is kept for the backend's lifetime, except that a
+     * transient status still returned after `send`'s retries, or a transport failure, is not kept:
+     * the former sends this write unidentified, and the latter rejects the write before it is sent.
+     * A kept yes is also dropped when a minted key meets the host's identity refusal; see
+     * {@link sendDocWrite}.
+     */
+    recordsOutcomes() {
+        this.operationsSupport ??= this.probeOperations();
+        return this.operationsSupport;
+    }
+    async probeOperations() {
+        let res;
+        try {
+            res = await this.send("/v0/capabilities", { method: "GET" }, "deployment");
+        }
+        catch (err) {
+            this.operationsSupport = undefined;
+            throw err;
+        }
+        if (RETRIABLE_STATUS.has(res.status))
+            this.operationsSupport = undefined;
+        if (!res.ok)
+            return false;
+        try {
+            const payload = (await res.json());
+            return payload?.operations === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Send a document `PUT` or `DELETE`. When its `Idempotency-Key` was minted here, a kept
+     * `operations` answer may be stale: a host that has since lost its outcome store refuses every
+     * key with the wire's `400` {@link IDENTITY_UNSUPPORTED} before applying anything. That answer
+     * is dropped and the write is sent once more without a key, as to any host without
+     * `operations`. A caller's own `requestId` is never dropped, so its refusal is the answer.
+     */
+    async sendDocWrite(path, init, minted) {
+        const res = await this.send(path, init);
+        if (!minted || res.status !== 400 || !(await refusesIdentity(res.clone())))
+            return res;
+        this.operationsSupport = undefined;
+        const { [IDENTITY_HEADER]: _refused, ...headers } = init.headers;
+        return this.send(path, { ...init, headers });
+    }
     /**
      * `GET /heads`: every document id and version the authority holds, under one digest, or
      * `null` when `ifNoneMatch` named the digest it still holds (a `304`: nothing changed). A
      * `200` is diffed against the caller's own copy: an id missing from `heads` was deleted, a
      * differing version changed. A `200` without a well-formed digest, whose `count` and rows
      * disagree, or whose rows digest by the documented recipe to something other than the served
-     * digest, is rejected rather than trusted, as is a `304` to a request that sent no
-     * `ifNoneMatch`. The recomputation is what stops a listing that is whole by its own count
-     * but not the state its digest names (a shortened listing under the real digest) from being
-     * diffed as a mass deletion. Not part of the {@link StorageBackend} seam.
+     * digest, is rejected rather than trusted ({@link parseHeadsAnswer} owns that admission), as
+     * is a `304` to a request that sent no `ifNoneMatch`. Not part of the {@link StorageBackend}
+     * seam.
      */
     async heads(options = {}) {
         const headers = {};
@@ -496,21 +456,7 @@ export class RemoteBackend {
         }
         if (!res.ok)
             throw await this.toError(res, "heads");
-        const payload = (await res.json());
-        if (!isHeadsDigest(payload?.digest))
-            throw malformed("wire heads answered without a well-formed digest");
-        if (!Array.isArray(payload.heads) || !payload.heads.every(isDocumentHead)) {
-            throw malformed("wire heads answered without a heads array of { id, version } rows");
-        }
-        if (payload.count !== payload.heads.length) {
-            throw malformed(`wire heads count ${String(payload.count)} disagrees with its ${payload.heads.length} row(s)`);
-        }
-        const heads = payload.heads.map(({ id, version }) => ({ id, version }));
-        const recomputed = headsDigest(heads);
-        if (recomputed !== payload.digest) {
-            throw malformed(`wire heads served digest ${payload.digest}, but its ${heads.length} row(s) digest to ${recomputed}`);
-        }
-        return { digest: payload.digest, heads };
+        return parseHeadsAnswer(await res.json());
     }
     /**
      * `GET /snapshot`: the whole bundle in one response. The header line is parsed before this
@@ -518,8 +464,9 @@ export class RemoteBackend {
      * the documents then stream through {@link RemoteSnapshot.docs}. Transient retry applies only
      * to obtaining the response: a body cut mid-stream is reported to the consumer as
      * `SNAPSHOT_TRUNCATED`, a whole body whose heads do not digest to the header's announcement as
-     * `SNAPSHOT_DIGEST_MISMATCH`, and re-requesting is the consumer's decision. Reserved files are
-     * not part of a snapshot. Not part of the {@link StorageBackend} seam.
+     * `SNAPSHOT_DIGEST_MISMATCH` ({@link readSnapshotStream} owns the grammar), and re-requesting
+     * is the consumer's decision. Reserved files are not part of a snapshot. Not part of the
+     * {@link StorageBackend} seam.
      */
     async snapshot() {
         const res = await this.send("/snapshot", { method: "GET" });
@@ -527,19 +474,7 @@ export class RemoteBackend {
             throw await this.toError(res, "snapshot");
         if (!res.body)
             throw new RemoteError("snapshot response carried no body", SNAPSHOT_TRUNCATED, res.status);
-        const lines = ndjsonLines(res.body, res.status);
-        const first = await lines.next();
-        if (first.done)
-            throw new RemoteError("snapshot ended before its header line", SNAPSHOT_TRUNCATED, res.status);
-        let header;
-        try {
-            header = parseSnapshotHeader(first.value);
-        }
-        catch (err) {
-            await lines.return(undefined);
-            throw err;
-        }
-        return { header, docs: snapshotDocuments(lines, header, res.status) };
+        return readSnapshotStream(res.body, { status: res.status });
     }
     /**
      * `GET /operations/{requestId}`: the authority's recorded outcome for an identified write, or
@@ -575,11 +510,14 @@ export class RemoteBackend {
      * {@link RemoteBackend.queryHeads} are both thin row-mappings over it, so a wire
      * pagination change cannot make the two scans silently paginate differently.
      */
-    async pageDocs(baseParams, mapRow, errorContext) {
+    async pageDocs(baseParams, mapRow, errorContext, skipped) {
         const rows = [];
         let cursor;
         for (;;) {
             const params = new URLSearchParams(baseParams);
+            // Ask the server to leave an unparsable document out and name it, rather than fail the page.
+            if (skipped)
+                params.set("malformed", "skip");
             if (cursor)
                 params.set("cursor", cursor);
             const qs = params.toString();
@@ -589,6 +527,13 @@ export class RemoteBackend {
             const payload = (await res.json());
             for (const row of payload.docs)
                 rows.push(mapRow(row));
+            if (skipped && Array.isArray(payload.skipped)) {
+                for (const entry of payload.skipped) {
+                    if (typeof entry?.id !== "string")
+                        continue;
+                    skipped.set(entry.id, typeof entry.reason === "string" ? entry.reason : "malformed frontmatter");
+                }
+            }
             if (!payload.next_cursor)
                 break;
             cursor = payload.next_cursor;
@@ -599,7 +544,11 @@ export class RemoteBackend {
         const params = new URLSearchParams();
         if (prefix)
             params.set("prefix", prefix);
-        return (await this.pageDocs(params, (row) => row.id, prefix ?? "")).sort(compareStorageKeys);
+        // A document the server could not parse still exists: it is listed, and reading it raises
+        // the same MalformedDocumentError a local read does.
+        const skipped = new Map();
+        const ids = await this.pageDocs(params, (row) => row.id, prefix ?? "", skipped);
+        return [...new Set([...ids, ...skipped.keys()])].sort(compareStorageKeys);
     }
     /**
      * The seam's OPTIONAL head-projection push-down, over the SAME `GET /docs` route
@@ -612,7 +561,7 @@ export class RemoteBackend {
      * `docs/WIRE-PROTOCOL.md`); the engine's `queryHeads` re-filter covers it, per the
      * seam contract (over-returning is fine; semantics live in core).
      */
-    async queryHeads(filter = {}) {
+    async queryHeads(filter = {}, options = {}) {
         const params = new URLSearchParams();
         params.set("fields", "frontmatter");
         if (filter.prefix)
@@ -621,7 +570,17 @@ export class RemoteBackend {
             params.set("type", filter.type);
         for (const tag of filter.tags ?? [])
             params.append("tag", tag);
-        return this.pageDocs(params, (row) => ({ id: row.id, frontmatter: row.frontmatter, version: row.version }), filter.prefix ?? "");
+        const skipped = new Map();
+        const rows = await this.pageDocs(params, (row) => ({ id: row.id, frontmatter: row.frontmatter, version: row.version }), filter.prefix ?? "", skipped);
+        // The server leaves a malformed document out of the listing and names it. A caller that
+        // asked for no skip report keeps the scan's fail-loud contract.
+        const named = [...skipped].sort(([a], [b]) => compareStorageKeys(a, b));
+        if (named.length > 0 && !options.onSkip) {
+            throw new MalformedDocumentError(named[0][0], new Error(named[0][1]));
+        }
+        for (const [id, reason] of named)
+            options.onSkip?.({ id, reason });
+        return rows;
     }
     async versions(id) {
         assertSafeConceptId(id);
@@ -687,11 +646,20 @@ export class RemoteBackend {
         const headers = {};
         if (options.expectedVersion !== undefined)
             headers["If-Match"] = options.expectedVersion;
+        let minted = false;
         if (options.requestId !== undefined) {
             assertRequestIdentity(options.requestId);
             headers[IDENTITY_HEADER] = options.requestId;
         }
-        const res = await this.send(`/docs/${encodeId(id)}`, { method: "DELETE", headers });
+        else if (options.expectedVersion !== undefined &&
+            isContentVersion(stripETagWrapper(options.expectedVersion)) &&
+            (await this.recordsOutcomes())) {
+            // The wire identifies a delete only under a content-version premise; any other premise
+            // stays an unidentified request rather than becoming a `400`.
+            headers[IDENTITY_HEADER] = mintRequestId();
+            minted = true;
+        }
+        const res = await this.sendDocWrite(`/docs/${encodeId(id)}`, { method: "DELETE", headers }, minted);
         if (!res.ok)
             throw await this.toError(res, id);
         const payload = (await res.json());