@superbee/server 0.1.6 → 0.2.0-pre.10

package/dist/router.js

@@ -16,10 +16,80 @@
  * See `docs/WIRE-PROTOCOL.md` "Implemented by reference" section for the exact
  * endpoint set and any recorded deviations from the draft.
  */
-import { InvalidInputError, VersionConflict, assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, isReservedFile, pathFromConceptId, stripETagWrapper, } from "@superbee/core/storage";
+import { InvalidInputError, MalformedDocumentError, VersionConflict, assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, headsDigest, sortHeads, isReservedFile, isContentVersion, pathFromConceptId, stripETagWrapper, } from "@superbee/core/storage";
 import { queryHeads, writeDocVersioned } from "@superbee/core/engine";
+import { isRequestIdentity } from "@superbee/core/storage";
+import { captureRemoteFrontmatter, RemoteDocumentValueError } from "@superbee/core/document-codec";
 /** Default page size for `GET /docs` when `limit` is not supplied. */
 const DEFAULT_LIST_LIMIT = 50;
+/** Documents read per backend batch while a snapshot streams; one NDJSON chunk per batch. */
+const SNAPSHOT_BATCH_SIZE = 50;
+/** The snapshot body's media type: one JSON object per line (`docs/WIRE-PROTOCOL.md`, "Heads and snapshot"). */
+const NDJSON_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
+/** The header that carries a document write's durable request identity (`docs/WIRE-PROTOCOL.md`, "Identified writes"). */
+const IDENTITY_HEADER = "Idempotency-Key";
+/** The only endpoints that accept {@link IDENTITY_HEADER}; every other endpoint refuses it as `400 USAGE`. */
+const IDENTIFIED_ENDPOINTS = new Set(["doc-write", "doc-delete"]);
+/** The one answer for identity on a host that records no outcomes; a client must never mistake it for silent acceptance. */
+const IDENTITY_UNSUPPORTED = "request identity is not supported by this host";
+/** A request identity from an `operations/{key}` path segment: decoded once, then held to the wire's key rule. */
+function decodeOperationKey(rawSegment) {
+    let key;
+    try {
+        key = decodeURIComponent(rawSegment);
+    }
+    catch {
+        throw new InvalidInputError(`invalid percent-encoding in operation key '${rawSegment}'`);
+    }
+    assertRequestIdentity(key);
+    return key;
+}
+function assertRequestIdentity(key) {
+    if (!isRequestIdentity(key)) {
+        throw new InvalidInputError("Idempotency-Key must be 1 to 128 printable ASCII characters with no space");
+    }
+}
+/** Capture a response so it can be recorded and replayed verbatim to a duplicate submission. */
+async function recordableResponse(response) {
+    const headers = [];
+    response.headers.forEach((value, name) => headers.push([name, value]));
+    return { status: response.status, headers, body: await response.text() };
+}
+function replayResponse(recorded) {
+    return new Response(recorded.body, { status: recorded.status, headers: recorded.headers });
+}
+/**
+ * The outcome a recorded response reports through the lookup route: a success is `committed`
+ * at the version the response carried, a `412` is `conflict` at the envelope's `actual`, and
+ * anything else is `refused` with the envelope's code. The same mapping a client applies to a
+ * live response, so a looked-up outcome and a replayed response never disagree.
+ */
+function outcomeOf(recorded) {
+    let payload = {};
+    try {
+        payload = JSON.parse(recorded.body);
+    }
+    catch {
+        payload = {};
+    }
+    if (recorded.status === 200 || recorded.status === 201) {
+        const version = recorded.headers.find(([name]) => name.toLowerCase() === "x-version")?.[1];
+        if (!version)
+            throw new Error("an identified write produced a success response that carries no version");
+        return { kind: "committed", version };
+    }
+    if (recorded.status === 412) {
+        const actual = payload.error?.details?.actual;
+        return { kind: "conflict", actual: typeof actual === "string" ? actual : null };
+    }
+    const code = payload.error?.code;
+    const message = payload.error?.message;
+    return {
+        kind: "refused",
+        code: typeof code === "string" ? code : "RUNTIME",
+        message: typeof message === "string" ? message : `status ${recorded.status}`,
+    };
+}
 /** True when `err` carries the `ENOENT`-shaped `.code` the seam's adapters use for "absent". */
 function isEnoent(err) {
     return typeof err === "object" && err !== null && err.code === "ENOENT";
@@ -60,11 +130,42 @@ function decodeBlobKey(rawPathTail) {
  * principle 4: OKF/id-safety invariants are enforced server-side too).
  */
 function assertValidDocId(id) {
+    if (hasControlCharacter(id)) {
+        throw new InvalidInputError("document ids cannot contain control characters");
+    }
     assertSafeConceptId(id);
     if (isReservedFile(pathFromConceptId(id))) {
         throw new InvalidInputError(`'${id}' is a reserved file, not a concept document`);
     }
 }
+/**
+ * True when `id` holds any code unit below U+0020 or equal to U+007F. The core id rule admits
+ * such characters (a local bundle may hold `"line\nbreak"`), but the heads digest concatenates
+ * `id`, `\n`, `version`, `\n` per row and is injective only when no id contains a line feed. The
+ * wire therefore refuses the whole control range on every document route
+ * ({@link assertValidDocId}) and refuses to list such an id ({@link UnservableIdError}), so no
+ * digest is ever minted over a listing the recipe cannot tell apart from another.
+ */
+function hasControlCharacter(id) {
+    for (let i = 0; i < id.length; i += 1) {
+        const unit = id.charCodeAt(i);
+        if (unit < 0x20 || unit === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * A bundle written outside the wire holds a document id the wire cannot serve through heads or
+ * snapshot (see {@link hasControlCharacter}). Mapped to `500 RUNTIME` with this message: the
+ * request is well formed, the bundle is what cannot be served, and the listing fails closed
+ * rather than minting a non-injective digest.
+ */
+class UnservableIdError extends Error {
+    constructor() {
+        super("bundle holds a document id the wire cannot serve");
+        this.name = "UnservableIdError";
+    }
+}
 /** Build a JSON `Response` with the standard `content-type`, merging in any extra headers. */
 function jsonResponse(status, body, headers = {}) {
     return new Response(JSON.stringify(body), {
@@ -91,9 +192,24 @@ function errorFromCaught(err) {
     if (isEnoent(err)) {
         return errorResponse(404, "NOT_FOUND", "document or blob not found");
     }
+    if (err instanceof RemoteDocumentValueError) {
+        return errorResponse(500, "RUNTIME", err.message);
+    }
     if (err instanceof InvalidInputError) {
         return errorResponse(400, "USAGE", err.message);
     }
+    if (err instanceof UnservableIdError) {
+        return errorResponse(500, "RUNTIME", err.message);
+    }
+    if (err instanceof MalformedDocumentError) {
+        // The request is well formed; the stored document is what cannot be served. Naming it lets
+        // a client report the one document to fix instead of an opaque server failure.
+        // Backends attribute the error to the document's path or its id; the wire names the id.
+        const id = err.context === undefined ? undefined : err.context.endsWith(".md") ? err.context.slice(0, -3) : err.context;
+        return errorResponse(500, "RUNTIME", err.message, {
+            malformed: { ...(id === undefined ? {} : { id }), reason: err.detail },
+        });
+    }
     return errorResponse(500, "RUNTIME", "internal server error");
 }
 /**
@@ -170,6 +286,20 @@ export const WIRE_ENDPOINTS = [
         path: "/v0/bundles/{bundle}/docs:read-many",
         accessClass: "read",
     },
+    {
+        id: "docs-heads",
+        resource: "docs-heads",
+        method: "GET",
+        path: "/v0/bundles/{bundle}/heads",
+        accessClass: "read",
+    },
+    {
+        id: "docs-snapshot",
+        resource: "docs-snapshot",
+        method: "GET",
+        path: "/v0/bundles/{bundle}/snapshot",
+        accessClass: "read",
+    },
     {
         id: "doc-read",
         resource: "doc",
@@ -254,6 +384,13 @@ export const WIRE_ENDPOINTS = [
         path: "/v0/bundles/{bundle}/blobs/{key...}",
         accessClass: "write",
     },
+    {
+        id: "operation-lookup",
+        resource: "operation",
+        method: "GET",
+        path: "/v0/bundles/{bundle}/operations/{key}",
+        accessClass: "write",
+    },
 ];
 /** Typed resolution failure retained as a stable host-side rejection seam. */
 export class WireRequestResolutionError extends Error {
@@ -312,6 +449,10 @@ function resourceFromMatch(resource, params, searchParams) {
             return { kind: "docs" };
         case "docs-read-many":
             return { kind: "docs-read-many" };
+        case "docs-heads":
+            return { kind: "docs-heads" };
+        case "docs-snapshot":
+            return { kind: "docs-snapshot" };
         case "doc": {
             const id = decodeId(params.id);
             assertValidDocId(id);
@@ -338,6 +479,8 @@ function resourceFromMatch(resource, params, searchParams) {
             assertSafeBlobKey(key);
             return { kind: "blob", key };
         }
+        case "operation":
+            return { kind: "operation", key: decodeOperationKey(params.key) };
     }
 }
 function invalidBundleFromPath(pathname) {
@@ -423,6 +566,12 @@ function routeLabel(resource) {
         case "docs-read-many":
             label = "/docs:read-many";
             break;
+        case "docs-heads":
+            label = "/heads";
+            break;
+        case "docs-snapshot":
+            label = "/snapshot";
+            break;
         case "doc":
         case "doc-versions":
             label = "a doc route";
@@ -436,6 +585,9 @@ function routeLabel(resource) {
         case "blob":
             label = "a blob route";
             break;
+        case "operation":
+            label = "an operation route";
+            break;
         case "capabilities":
             label = "/v0/capabilities";
             break;
@@ -496,7 +648,7 @@ function buildRouter(options) {
         assertValidDocId(id);
         try {
             const { doc, version } = await backend.read(id);
-            return jsonResponse(200, { id: doc.id, frontmatter: doc.frontmatter, body: doc.body }, versionHeaders(version));
+            return jsonResponse(200, { id: doc.id, frontmatter: captureRemoteFrontmatter(doc.frontmatter), body: doc.body }, versionHeaders(version));
         }
         catch (err) {
             if (isEnoent(err))
@@ -551,12 +703,98 @@ function buildRouter(options) {
      * catch-all (`VersionConflict` -> `412` via `errorFromCaught`, same as a write). `200
      * { deleted }` unconditionally — never a `404`, matching the wire's absence-is-success
      * contract (AXI P6).
+     *
+     * A delete that carried `If-Match` answers with the version headers naming that token: the
+     * revision the delete acted on, and the version an identified delete's recorded outcome is
+     * committed at. When the target was already absent the delete is still the idempotent success
+     * the wire promises, and the token the client supplied is still the revision its outcome
+     * names. An unconditional delete has no revision to name and sends no version headers.
      */
     async function handleDeleteDoc(backend, id, req) {
         assertValidDocId(id);
         const options = deleteOptionsFromHeaders(req);
         const deleted = await backend.delete(id, options);
-        return jsonResponse(200, { deleted });
+        const headers = options.expectedVersion === undefined ? {} : versionHeaders(options.expectedVersion);
+        return jsonResponse(200, { deleted }, headers);
+    }
+    /**
+     * Apply one identified write at most once under `key`. The key is claimed before `apply`
+     * runs; a duplicate that finds the key recorded replays the recorded response, and one that
+     * finds the first application still in progress waits for it. A typed rejection thrown by the
+     * engine (`412`, `400`, `404`) is the write's answer and is recorded like a returned response;
+     * a runtime failure produced no answer, so the claim is released with nothing recorded and a
+     * later submission applies fresh. A recorded outcome is bound to its method and document id,
+     * so the same key resubmitted for a different operation is refused, never replayed.
+     */
+    async function applyIdentified(scope, key, method, id, apply) {
+        try {
+            assertRequestIdentity(key);
+        }
+        catch (err) {
+            return errorFromCaught(err);
+        }
+        const store = options.outcomes;
+        if (!store)
+            return errorResponse(400, "USAGE", IDENTITY_UNSUPPORTED);
+        for (;;) {
+            const claim = await store.claim(scope, key);
+            if (claim.kind === "recorded")
+                return replayRecorded(claim.operation, method, id);
+            if (claim.kind === "in_progress") {
+                const settled = await claim.settled;
+                if (settled === null)
+                    continue;
+                return replayRecorded(settled, method, id);
+            }
+            let response;
+            try {
+                response = await apply();
+            }
+            catch (err) {
+                if (!(err instanceof VersionConflict || err instanceof InvalidInputError || isEnoent(err))) {
+                    await settleOutcomeClaim(() => claim.release());
+                    throw err;
+                }
+                response = errorFromCaught(err);
+            }
+            let recorded;
+            let outcome;
+            try {
+                recorded = await recordableResponse(response);
+                outcome = outcomeOf(recorded);
+            }
+            catch (err) {
+                await settleOutcomeClaim(() => claim.release());
+                throw err;
+            }
+            await settleOutcomeClaim(() => claim.record({ method, id, response: recorded, outcome }));
+            return replayResponse(recorded);
+        }
+    }
+    /** Persistence errors are not document refusals, even when an adapter uses engine error types. */
+    async function settleOutcomeClaim(settle) {
+        try {
+            await settle();
+        }
+        catch (cause) {
+            throw new Error("operation outcome persistence failed", { cause });
+        }
+    }
+    function replayRecorded(operation, method, id) {
+        if (operation.method !== method || operation.id !== id) {
+            return errorResponse(400, "USAGE", `Idempotency-Key was recorded for ${operation.method} '${operation.id}', not ${method} '${id}'`, { recorded: { method: operation.method, id: operation.id } });
+        }
+        return replayResponse(operation.response);
+    }
+    /** `GET /operations/{key}`: the recorded outcome, or `404` when the store holds nothing under the key. */
+    async function handleOperationLookup(scope, key) {
+        const store = options.outcomes;
+        if (!store)
+            return errorResponse(400, "USAGE", IDENTITY_UNSUPPORTED);
+        const operation = await store.lookup(scope, key);
+        if (!operation)
+            return errorResponse(404, "NOT_FOUND", `no recorded outcome for '${key}'`);
+        return jsonResponse(200, operation.outcome);
     }
     async function handleVersions(backend, id) {
         assertValidDocId(id);
@@ -583,8 +821,9 @@ function buildRouter(options) {
             try {
                 assertValidDocId(id);
             }
-            catch {
-                return errorResponse(400, "USAGE", `invalid document id '${id}'`, { id });
+            catch (err) {
+                const reason = err instanceof InvalidInputError ? err.message : `invalid document id '${id}'`;
+                return errorResponse(400, "USAGE", reason, { id });
             }
         }
         // Determine the missing set up front (§ readMany: "404 + { missing }" if ANY id is
@@ -596,7 +835,7 @@ function buildRouter(options) {
         }
         const results = await backend.readMany(ids);
         return jsonResponse(200, {
-            results: results.map((r) => ({ id: r.doc.id, frontmatter: r.doc.frontmatter, body: r.doc.body, version: r.version })),
+            results: results.map((r) => ({ id: r.doc.id, frontmatter: captureRemoteFrontmatter(r.doc.frontmatter), body: r.doc.body, version: r.version })),
         });
     }
     async function handleList(backend, searchParams) {
@@ -613,11 +852,13 @@ function buildRouter(options) {
         // push-down (an indexed adapter can answer without reading bodies),
         // re-applies the canonical `matchesFilter` to whatever came back, and falls back to
         // the delete-tolerant `list` + batch-read walk for every other backend (a doc deleted
-        // mid-scan is SKIPPED, not a scan-failing 404 — the server half of STATUS item 33; a
-        // MALFORMED doc still fails loudly, since quarantining it over the wire needs a
-        // `skipped` response shape — recorded as an open question). The router deliberately
-        // does NOT re-implement the prefer-else-fallback dance itself.
-        const heads = await queryHeads(backend, { prefix, type, tags });
+        // mid-scan is SKIPPED, not a scan-failing 404 — the server half of STATUS item 33). With
+        // `malformed=skip`, a MALFORMED doc is left out of the rows and named in `skipped` on every
+        // page, so one bad file never fails the listing; without it (a client that cannot read
+        // `skipped`) the listing fails naming the document, so no client silently loses one. The
+        // router deliberately does NOT re-implement the prefer-else-fallback dance itself.
+        const skipped = [];
+        const heads = await queryHeads(backend, { prefix, type, tags }, searchParams.get("malformed") === "skip" ? { onSkip: (skip) => skipped.push(skip) } : {});
         const count = heads.length;
         let page = heads;
         if (cursor) {
@@ -630,16 +871,168 @@ function buildRouter(options) {
         }
         const limited = page.slice(0, limit);
         const nextCursor = page.length > limit ? (limited[limited.length - 1]?.id ?? null) : null;
-        const docs = limited.map(({ id, frontmatter, version }) => fields === "frontmatter"
-            ? { id, version, frontmatter }
-            : {
-                id,
-                version,
-                type: frontmatter.type,
-                title: frontmatter.title,
-                timestamp: frontmatter.timestamp,
+        const docs = limited.map(({ id, frontmatter, version }) => {
+            if (fields === "frontmatter")
+                return { id, version, frontmatter: captureRemoteFrontmatter(frontmatter) };
+            // Only emitted fields need wire compatibility. Copy descriptors so projecting a field
+            // cannot invoke its getter before the shared capture checks it; absent fields stay absent.
+            const projected = Object.create(null);
+            for (const key of ["type", "title", "timestamp"]) {
+                const descriptor = Object.getOwnPropertyDescriptor(frontmatter, key);
+                if (descriptor)
+                    Object.defineProperty(projected, key, { ...descriptor, enumerable: true });
+            }
+            return { id, version, ...captureRemoteFrontmatter(projected) };
+        });
+        return jsonResponse(200, {
+            count,
+            docs,
+            next_cursor: nextCursor,
+            ...(skipped.length > 0 ? { skipped: skipped.map(({ id, reason }) => ({ id, reason })) } : {}),
+        });
+    }
+    /**
+     * Every document's id and current version, in the wire's id order. The one listing behind
+     * both `GET /heads` and `GET /snapshot`: `list` for the ids, then `readMany` in batches of
+     * `SNAPSHOT_BATCH_SIZE`, keeping only each result's version and dropping the bodies with the
+     * batch. Neither reference backend pushes `queryHeads` down, and the engine's scan reads every
+     * body in one `readMany`, which is why the listing is computed here rather than through it.
+     * Every document is still read once for the listing. A document deleted between `list` and
+     * its batch is simply not a head, as in the engine's scan; a malformed document fails the
+     * listing, naming it (deviation 4): a working copy reads a missing head as a deletion, so heads
+     * cannot skip a document the way `GET /docs` does.
+     * An id the wire cannot serve (a control character, which the digest recipe cannot delimit)
+     * fails the listing closed before any document is read: heads answers `500 RUNTIME`, and the
+     * snapshot fails before its header line exists, so the client sees no snapshot rather than
+     * a digest that another listing could share.
+     */
+    async function listHeads(backend) {
+        const ids = await backend.list();
+        if (ids.some(hasControlCharacter))
+            throw new UnservableIdError();
+        const heads = [];
+        for (let offset = 0; offset < ids.length; offset += SNAPSHOT_BATCH_SIZE) {
+            const batch = ids.slice(offset, offset + SNAPSHOT_BATCH_SIZE);
+            for (const { id, version } of await readBatchExisting(backend, batch))
+                heads.push({ id, version });
+        }
+        return sortHeads(heads);
+    }
+    /**
+     * `readMany` for one batch, tolerating a document that vanished after `list` named it: on an
+     * ENOENT-shaped failure the batch is re-read one id at a time and absent ids are dropped.
+     * Any other failure (a malformed document included) propagates.
+     */
+    async function readBatchExisting(backend, ids) {
+        try {
+            const results = await backend.readMany(ids);
+            assertBatchShape(results.length, ids.length);
+            return results.map((result, index) => ({ id: ids[index], version: result.version }));
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+        const out = [];
+        for (const id of ids) {
+            try {
+                out.push({ id, version: (await backend.read(id)).version });
+            }
+            catch (err) {
+                if (!isEnoent(err))
+                    throw err;
+            }
+        }
+        return out;
+    }
+    /** A conforming `readMany` answers one result per id, in order; anything else is a backend defect, never silently paired. */
+    function assertBatchShape(resultCount, idCount) {
+        if (resultCount !== idCount) {
+            throw new Error(`readMany answered ${resultCount} result(s) for ${idCount} id(s); results are paired to ids by index`);
+        }
+    }
+    /** True when `If-None-Match` names `digest` in bare, quoted, or weak form, alone or in a list. */
+    function ifNoneMatchNames(req, digest) {
+        const header = req.headers.get("If-None-Match");
+        if (header === null)
+            return false;
+        return header.split(",").some((token) => stripETagWrapper(token) === digest);
+    }
+    /**
+     * `GET /heads`: `{ count, digest, heads }` with the digest as a quoted `ETag`, or a bodyless
+     * `304` when the client already holds that digest. A `304` means nothing changed; a `200` is
+     * diffed by the client against its own copy (a missing id is a deletion, a differing version a
+     * change). No pagination: the whole listing is the point of the route.
+     */
+    async function handleHeads(backend, req) {
+        const heads = await listHeads(backend);
+        const digest = headsDigest(heads);
+        if (ifNoneMatchNames(req, digest)) {
+            return new Response(null, { status: 304, headers: { ETag: `"${digest}"` } });
+        }
+        return jsonResponse(200, { count: heads.length, digest, heads }, { ETag: `"${digest}"` });
+    }
+    /**
+     * The snapshot's NDJSON lines: the header, one chunk of document lines per backend batch, and
+     * the `end` terminator. The listing holds only ids and versions; bodies are read in batches of
+     * `SNAPSHOT_BATCH_SIZE` after the header has been produced and encoded as each batch arrives,
+     * so at most one batch of bodies is held at a time. A document that vanishes between the heads
+     * listing and its batch makes the batch read throw, which errors the stream: the client then
+     * sees a body without its terminator and treats the snapshot as truncated. A document that
+     * changes in that window is caught the same way: its read version no longer matches the listed
+     * head, and the stream errors rather than emitting a line the header digest does not describe,
+     * so the digest always describes exactly the emitted lines and the client retries.
+     */
+    async function* snapshotLines(backend, heads, digest) {
+        yield `${JSON.stringify({ kind: "snapshot", count: heads.length, digest })}\n`;
+        for (let offset = 0; offset < heads.length; offset += SNAPSHOT_BATCH_SIZE) {
+            const batch = heads.slice(offset, offset + SNAPSHOT_BATCH_SIZE);
+            const results = await backend.readMany(batch.map((head) => head.id));
+            assertBatchShape(results.length, batch.length);
+            let chunk = "";
+            results.forEach((result, index) => {
+                // The heads listing owns identity, as the read-many route does: never a payload id.
+                const head = batch[index];
+                if (result.version !== head.version) {
+                    throw new Error(`document '${head.id}' changed from version ${head.version} to ${result.version} while the snapshot streamed`);
+                }
+                const line = { kind: "doc", id: head.id, version: head.version, frontmatter: captureRemoteFrontmatter(result.doc.frontmatter), body: result.doc.body };
+                chunk += `${JSON.stringify(line)}\n`;
             });
-        return jsonResponse(200, { count, docs, next_cursor: nextCursor });
+            yield chunk;
+        }
+        yield `${JSON.stringify({ kind: "end", count: heads.length })}\n`;
+    }
+    /** Encode produced lines into a pull-driven byte stream: one enqueue per produced chunk, nothing buffered ahead of the reader. */
+    function ndjsonStream(lines) {
+        const encoder = new TextEncoder();
+        return new ReadableStream({
+            async pull(controller) {
+                const next = await lines.next();
+                if (next.done)
+                    controller.close();
+                else
+                    controller.enqueue(encoder.encode(next.value));
+            },
+            async cancel() {
+                await lines.return(undefined);
+            },
+        });
+    }
+    /**
+     * `GET /snapshot`: every document as a streamed NDJSON body whose header carries the same
+     * digest `GET /heads` would return for this state, so a bootstrap can start its later heads
+     * checks from it. The heads listing (and so a malformed-document failure) completes before any
+     * byte of the response exists; only the batched body reads stream. Reserved files are not part
+     * of a snapshot.
+     */
+    async function handleSnapshot(backend) {
+        const heads = await listHeads(backend);
+        const digest = headsDigest(heads);
+        return new Response(ndjsonStream(snapshotLines(backend, heads, digest)), {
+            status: 200,
+            headers: { "content-type": NDJSON_CONTENT_TYPE, ETag: `"${digest}"` },
+        });
     }
     async function handleReadReserved(backend, dir, name) {
         assertSafeReservedDir(dir);
@@ -748,9 +1141,19 @@ function buildRouter(options) {
             projections: caps.projections ?? true,
             backlinks: caps.backlinks ?? false,
             blobs: caps.blobs,
+            operations: options.outcomes !== undefined,
+            heads: true,
+            snapshot: true,
         });
     }
     return registeredWireRouter(async (req, { resolved }) => {
+        // Identity is refused wherever it is not honored, so a client never believes an
+        // unsupported write was identified. The refusal precedes context resolution the way route
+        // resolution does; on the two identified endpoints the host's own answer comes first.
+        const identity = req.headers.get(IDENTITY_HEADER);
+        if (identity !== null && !IDENTIFIED_ENDPOINTS.has(resolved.endpointId)) {
+            return errorResponse(400, "USAGE", "Idempotency-Key is accepted only on document PUT and DELETE");
+        }
         if (resolved.scope === "deployment")
             return handleCapabilities();
         const context = await options.resolveContext(req, resolved);
@@ -764,16 +1167,37 @@ function buildRouter(options) {
                 return await handleList(backend, resolved.searchParams);
             case "docs-read-many":
                 return await handleReadMany(backend, req);
+            case "docs-heads":
+                return await handleHeads(backend, req);
+            case "docs-snapshot":
+                return await handleSnapshot(backend);
             case "doc-versions":
                 return await handleVersions(backend, resolved.resource.id);
             case "doc-read":
                 return await handleReadDoc(backend, resolved.resource.id);
-            case "doc-write":
-                return await handleWriteDoc(backend, attribution, resolved.resource.id, req);
+            case "doc-write": {
+                const { id } = resolved.resource;
+                const write = () => handleWriteDoc(backend, attribution, id, req);
+                return identity === null ? await write() : await applyIdentified(resolved.bundleId, identity, "PUT", id, write);
+            }
             case "doc-head":
                 return await handleHeadDoc(backend, resolved.resource.id);
-            case "doc-delete":
-                return await handleDeleteDoc(backend, resolved.resource.id, req);
+            case "doc-delete": {
+                const { id } = resolved.resource;
+                if (identity !== null) {
+                    // The token becomes the version the recorded outcome is committed at and the version
+                    // headers the answer carries, so it must be a real content-addressed version, checked
+                    // before the key is claimed: an absent, empty or malformed premise records nothing.
+                    const premise = req.headers.get("If-Match");
+                    if (premise === null || !isContentVersion(stripETagWrapper(premise))) {
+                        return errorResponse(400, "USAGE", "an identified delete must carry a well-formed If-Match token");
+                    }
+                }
+                const remove = () => handleDeleteDoc(backend, id, req);
+                return identity === null ? await remove() : await applyIdentified(resolved.bundleId, identity, "DELETE", id, remove);
+            }
+            case "operation-lookup":
+                return await handleOperationLookup(resolved.bundleId, resolved.resource.key);
             case "reserved-read": {
                 const resource = resolved.resource;
                 return await handleReadReserved(backend, resource.dir, resource.name);