@superbee/core 0.2.0-pre.5 → 0.2.0-pre.8

package/dist/platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}

package/dist/platform.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AA2KH,sDAAsD;AACtD,MAAM,UAAU,eAAe,CAAC,UAAsB;IACpD,QAAQ,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,KAAK,kBAAkB;YACrB,OAAO,QAAQ,CAAC;QAClB,KAAK,eAAe;YAClB,OAAO,SAAS,CAAC;QACnB,KAAK,gBAAgB;YACnB,OAAO,UAAU,CAAC;IACtB,CAAC;AACH,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,iBAAiB,CAAC,UAAsB;IACtD,OAAO,UAAU,CAAC,KAAK,KAAK,kBAAkB,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,eAAwB,OAAO;IAC/E,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,IAAoB,EAAE,SAAiB;IACpF,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,IAAoB,EAAE,MAAsB,EAAE,SAAiB;IAC7G,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACvE,CAAC"}
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAkLH,sDAAsD;AACtD,MAAM,UAAU,eAAe,CAAC,UAAsB;IACpD,QAAQ,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,KAAK,kBAAkB;YACrB,OAAO,QAAQ,CAAC;QAClB,KAAK,eAAe;YAClB,OAAO,SAAS,CAAC;QACnB,KAAK,gBAAgB;YACnB,OAAO,UAAU,CAAC;IACtB,CAAC;AACH,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,iBAAiB,CAAC,UAAsB;IACtD,OAAO,UAAU,CAAC,KAAK,KAAK,kBAAkB,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,eAAwB,OAAO;IAC/E,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,IAAoB,EAAE,SAAiB;IACpF,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,IAAoB,EAAE,MAAsB,EAAE,SAAiB;IAC7G,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACvE,CAAC"}

package/dist/query-order.d.ts

@@ -0,0 +1,22 @@
+export interface MeaningfulChangeOrderKey {
+    id: string;
+    /** The raw selected clock when it is a string, else `""`. */
+    timestamp: string;
+    /** The clock parsed under the bundle's OKF edition, or `null` when missing or invalid. */
+    timestampMs: number | null;
+}
+export declare function meaningfulChangeOrderKey(id: string, frontmatter: {
+    readonly generated?: unknown;
+    readonly timestamp?: unknown;
+}, okfVersion?: string | null): MeaningfulChangeOrderKey;
+/** Newest usable meaningful-change time first; canonical ID in code-unit order for all ties. */
+export declare function compareByMeaningfulChange(a: MeaningfulChangeOrderKey, b: MeaningfulChangeOrderKey): number;
+/** Return a new array of `rows` in newest-first order; the input array is left untouched. */
+export declare function sortByMeaningfulChange<T extends {
+    id: string;
+    frontmatter: {
+        readonly generated?: unknown;
+        readonly timestamp?: unknown;
+    };
+}>(rows: readonly T[], okfVersion?: string | null): T[];
+//# sourceMappingURL=query-order.d.ts.map

package/dist/query-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-order.d.ts","sourceRoot":"","sources":["../src/query-order.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,EAC3E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,wBAAwB,CAO1B;AAED,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,wBAAwB,EAAE,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAS1G;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,EAC1I,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,CAAC,EAAE,CAKL"}

package/dist/query-order.js

@@ -0,0 +1,42 @@
+/**
+ * Newest-first order shared by `list`, `home` and the View Bridge `order: "newest"` query.
+ *
+ * Rows sort by their parsed meaningful-change time (`generated.at`, else legacy `timestamp`),
+ * newest first. Rows with a missing or unparseable time follow every timed row. Every tie,
+ * including the untimed tail, breaks on the canonical ID in UTF-16 code-unit order, which every
+ * host computes identically; `localeCompare` depends on the platform's ICU data.
+ *
+ * Browser-safe and pure.
+ */
+import { parseTimestamp } from "./freshness.js";
+import { meaningfulChangeTimeValue } from "./meaningful-change-time.js";
+export function meaningfulChangeOrderKey(id, frontmatter, okfVersion) {
+    const value = meaningfulChangeTimeValue(frontmatter);
+    return {
+        id,
+        timestamp: typeof value === "string" ? value : "",
+        timestampMs: parseTimestamp(value, okfVersion ?? undefined),
+    };
+}
+/** Newest usable meaningful-change time first; canonical ID in code-unit order for all ties. */
+export function compareByMeaningfulChange(a, b) {
+    if (a.timestampMs !== null && b.timestampMs !== null) {
+        if (a.timestampMs !== b.timestampMs)
+            return b.timestampMs - a.timestampMs;
+    }
+    else if (a.timestampMs !== null) {
+        return -1;
+    }
+    else if (b.timestampMs !== null) {
+        return 1;
+    }
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** Return a new array of `rows` in newest-first order; the input array is left untouched. */
+export function sortByMeaningfulChange(rows, okfVersion) {
+    return rows
+        .map((row) => ({ row, key: meaningfulChangeOrderKey(row.id, row.frontmatter, okfVersion) }))
+        .sort((a, b) => compareByMeaningfulChange(a.key, b.key))
+        .map(({ row }) => row);
+}
+//# sourceMappingURL=query-order.js.map

package/dist/query-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-order.js","sourceRoot":"","sources":["../src/query-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAUxE,MAAM,UAAU,wBAAwB,CACtC,EAAU,EACV,WAA2E,EAC3E,UAA0B;IAE1B,MAAM,KAAK,GAAG,yBAAyB,CAAC,WAAW,CAAC,CAAC;IACrD,OAAO;QACL,EAAE;QACF,SAAS,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QACjD,WAAW,EAAE,cAAc,CAAC,KAAK,EAAE,UAAU,IAAI,SAAS,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,yBAAyB,CAAC,CAA2B,EAAE,CAA2B;IAChG,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;YAAE,OAAO,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IAC5E,CAAC;SAAM,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;SAAM,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,sBAAsB,CACpC,IAAkB,EAClB,UAA0B;IAE1B,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,wBAAwB,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;SAC3F,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/dist/remote-backend.d.ts

@@ -2,9 +2,11 @@
  * `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
@@ -69,9 +71,24 @@ export interface RemoteBackendOptions {
      * e.g. a Cloudflare D1 cold-start's 500 "storage caused object to be reset" when a hibernated
      * database is first hit) or a network/transport error. Each retry backs off exponentially with
      * jitter. A 4xx (incl. 412 VersionConflict), 401, or any 2xx is a REAL result, never retried.
-     * Default 3; set 0 to disable. Safe because every op is content-addressed + CAS: a retried write
-     * lands the same version or a conflict — possibly SPURIOUS, if a prior attempt actually committed
-     * before its response was lost — but never silent data loss; and a retried read is idempotent.
+     * Default 3; set 0 to disable. A retried read is idempotent.
+     *
+     * A guarded document write (`write` with `expectedVersion`, or `delete` with a content-version
+     * `expectedVersion`) travels with an `Idempotency-Key`: the caller's `requestId`, or else, when
+     * the host's capabilities report `operations`, one minted for that call. Every retry of the
+     * request carries the same key, so while the host keeps the record a retry is answered from the
+     * recorded outcome and cannot apply the write a second time.
+     *
+     * Other guarded writes retry as a plain resubmission: a guarded document write sent without a key
+     * (to a host without `operations`, after a capability question that ended in a transient status,
+     * or resent after the host refused a key minted under a stale answer), a `delete` whose
+     * `expectedVersion` is not a content version, and every guarded reserved-file and blob write,
+     * none of which the wire identifies. Such a retry lands the same version or a conflict, possibly
+     * SPURIOUS if a prior attempt committed before its response was lost. It is not free of lost
+     * updates: versions are content hashes, so if another writer returns the document to the exact
+     * state the premise names before a retry arrives, the retry applies the write again over that
+     * change and reports success. An unconditional write carries no minted key and can simply be
+     * repeated.
      */
     maxRetries?: number;
 }
@@ -106,6 +123,8 @@ export declare class RemoteBackend implements StorageBackend {
     private readonly fetchImpl;
     private readonly authToken?;
     private readonly maxRetries;
+    /** The pending or settled answer to whether this host records outcomes; see {@link recordsOutcomes}. */
+    private operationsSupport?;
     constructor(options: RemoteBackendOptions);
     /** The authority's base URL as configured, without a trailing slash. */
     get origin(): string;
@@ -119,12 +138,33 @@ export declare class RemoteBackend implements StorageBackend {
     write(id: ConceptId, doc: OkfDocument, options?: WriteOptions): Promise<Version>;
     /**
      * `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`.
      */
     wireCapabilities(): Promise<WireCapabilities>;
+    /**
+     * 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}.
+     */
+    private recordsOutcomes;
+    private probeOperations;
+    /**
+     * 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.
+     */
+    private sendDocWrite;
     /**
      * `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
@@ -174,7 +214,12 @@ export declare class RemoteBackend implements StorageBackend {
      * `docs/WIRE-PROTOCOL.md`); the engine's `queryHeads` re-filter covers it, per the
      * seam contract (over-returning is fine; semantics live in core).
      */
-    queryHeads(filter?: QueryFilter): Promise<HeadResult[]>;
+    queryHeads(filter?: QueryFilter, options?: {
+        onSkip?: (skip: {
+            id: ConceptId;
+            reason: string;
+        }) => void;
+    }): Promise<HeadResult[]>;
     versions(id: ConceptId): Promise<VersionInfo[]>;
     readReserved(dir: string, name: ReservedFilename): Promise<ReservedReadResult | null>;
     writeReserved(dir: string, name: ReservedFilename, content: string, options?: WriteOptions): Promise<Version>;

package/dist/remote-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-backend.d.ts","sourceRoot":"","sources":["../src/remote-backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remote-backend.d.ts","sourceRoot":"","sources":["../src/remote-backend.ts"],"names":[],"mappings":"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"}

package/dist/remote-backend.js

@@ -2,9 +2,11 @@
  * `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
@@ -42,12 +44,13 @@
  */
 import { DEFAULT_BLOB_CONTENT_TYPE } from "./content-type.js";
 import { InvalidInputError } from "./errors.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";
+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";
@@ -97,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
@@ -120,6 +135,18 @@ function etagForm(token) {
  * 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;
@@ -165,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;
@@ -195,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;
                 }
@@ -236,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-
@@ -300,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: encodeRemoteDocument(doc.frontmatter, 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());
@@ -316,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");
@@ -338,6 +382,56 @@ 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
@@ -416,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();
@@ -430,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;
@@ -440,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
@@ -453,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)
@@ -462,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);
@@ -528,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());