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

package/dist/platform.d.ts

@@ -17,10 +17,15 @@
  *   presentation can report shared confirmation without an acknowledgement. It says nothing
  *   about what the authority holds now: request-driven's last exchange is the request itself,
  *   browser-local's is its last sync, and the authority may have moved (or deleted the document)
- *   since. One limit of "last exchange" today: a browser-local sync pulls what the authority
- *   lists, so a document the authority deleted is not visited and stays `shared-confirmed` at
- *   its last served version until pull reconciles deletions; request-driven answers absence
- *   directly. A presentation must not read `shared-confirmed` as proof of present existence.
+ *   since. A document the authority deleted disappears from a browser-local working copy at
+ *   its next sync (pull reconciles deletions against the authority's heads) unless a local
+ *   edit holds it, in which case pull retains the local content and rewrites its base to an
+ *   absent shared version, and the document reads `local-pending` until push delivers the edit
+ *   and settles the authority's conflict answer (a 412 whose actual version is `null`) as a
+ *   conflict against an absent remote, from which point it reads `local-conflict` with
+ *   `remote: null`; request-driven answers absence directly. Between syncs a deleted document
+ *   still reads `shared-confirmed` at its last served version, so a presentation must not read
+ *   `shared-confirmed` as proof of present existence.
  * - `local-pending`: the working copy holds a local edit the authority has not accepted;
  *   `requestId` names the journaled intent that will deliver it and `base` the shared version
  *   the edit was made against.
@@ -111,6 +116,62 @@ export interface PlatformCommit {
     changed: boolean;
     provenance: Provenance;
 }
+/**
+ * Why a browser-local sync applied none of the deletions a verified listing implied:
+ * `empty-listing` names no document while the working copy holds some, `over-half` names so
+ * few that more than half of the working copy would go. Only a listing that would remove at
+ * least eight documents is bounded; fewer are applied on the authority's word.
+ */
+export type RefusedDeletionsReason = "empty-listing" | "over-half";
+/**
+ * The deletions a browser-local sync refused to apply, exactly as recorded on its last pull.
+ * `digest` names the listing that implied them; a caller that has judged the shrink genuine
+ * passes the record back as {@link PlatformSyncOptions.acceptRefusedDeletions}.
+ */
+export interface RefusedDeletions {
+    /** How many documents the listing would have removed from the working copy. */
+    deletions: number;
+    reason: RefusedDeletionsReason;
+    /** The heads digest of the listing that was refused. */
+    digest: string;
+}
+/** How the runtime's last sync ended; see {@link PlatformSyncStatus.lastSync}. */
+export interface PlatformSyncOutcome {
+    /** False when the sync rejected (a carrier failure, or an authority answer the runtime could not apply). */
+    ok: boolean;
+    /** The rejection's `name: message` when `ok` is false. */
+    error?: string;
+    /** The deletions the last completed pull refused; present until a pull applies or clears them. */
+    refusedDeletions?: RefusedDeletions;
+}
+export interface PlatformSyncOptions {
+    /**
+     * The refusal the last sync reported (`lastSync.refusedDeletions`), passed back to say the
+     * shrink it describes is genuine. Browser-local applies the deletions only when the
+     * authority's current listing still carries the same digest, count and reason; a listing
+     * that has moved since is refused afresh. Request-driven ignores it: nothing is ever
+     * refused there.
+     */
+    acceptRefusedDeletions?: RefusedDeletions;
+}
+/**
+ * The runtime's relation to the authority as of its last exchange. `online` reports the
+ * carrier: it turns false only when a request could not reach the authority, never on an
+ * answer the authority gave. `lastSync` reports the sync verb itself, and is the field a
+ * presentation must show to distinguish "synchronized" from "tried and failed": `ok` is false
+ * whenever `sync` rejected, whatever the cause, with the rejection's text in `error`.
+ *
+ * Browser-local applies a verified heads listing on the authority's word, including the
+ * documents it no longer names, with one bound: a listing that would remove at least eight
+ * documents and more than half of the working copy (or every document) is refused as a whole.
+ * The refreshes in that sync still apply, nothing is removed, `lastSync.ok` stays true, and
+ * `lastSync.refusedDeletions` carries the refusal until a later pull applies or clears it. A
+ * genuine shrink of that size therefore never reconciles on its own; the recovery path is to
+ * pass the recorded refusal back as `sync({ acceptRefusedDeletions })`, which applies the
+ * deletions if the authority still lists the same state and refuses afresh if it has moved.
+ * Request-driven has no working copy and leaves `lastSync` undefined: the status is the answer
+ * to the request that produced it.
+ */
 export interface PlatformSyncStatus {
     mode: ExecutionMode;
     /** Whether the last request to the authority succeeded; `null` before any was made. */
@@ -131,6 +192,12 @@ export interface PlatformSyncStatus {
     pausedReason?: string;
     /** The runtime's working set is complete: the authority's for request-driven, a finished bootstrap for browser-local. */
     complete: boolean;
+    /**
+     * How the last sync ended, and any deletions its pull refused. Browser-local fills it from
+     * the sync's own outcome and the pull marker (so a refusal recorded before this runtime was
+     * created still shows); request-driven leaves it undefined. Absent before any sync.
+     */
+    lastSync?: PlatformSyncOutcome;
 }
 export interface PlatformRuntime {
     capabilities(): PlatformCapabilities;
@@ -141,8 +208,12 @@ export interface PlatformRuntime {
     validate(id: ConceptId): Promise<PlatformValidation>;
     commit(id: ConceptId, edit: PlatformEdit): Promise<PlatformCommit>;
     syncStatus(): Promise<PlatformSyncStatus>;
-    /** Push pending work and pull the authority's changes; a no-op returning the status in request-driven mode. */
-    sync(): Promise<PlatformSyncStatus>;
+    /**
+     * Push pending work and pull the authority's changes; a no-op returning the status in
+     * request-driven mode. `options` carries the recovery path for refused deletions; see
+     * {@link PlatformSyncOptions}.
+     */
+    sync(options?: PlatformSyncOptions): Promise<PlatformSyncStatus>;
 }
 /** The word a presentation shows for a provenance. */
 export declare function provenanceLabel(provenance: Provenance): ProvenanceLabel;

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

@@ -17,10 +17,15 @@
  *   presentation can report shared confirmation without an acknowledgement. It says nothing
  *   about what the authority holds now: request-driven's last exchange is the request itself,
  *   browser-local's is its last sync, and the authority may have moved (or deleted the document)
- *   since. One limit of "last exchange" today: a browser-local sync pulls what the authority
- *   lists, so a document the authority deleted is not visited and stays `shared-confirmed` at
- *   its last served version until pull reconciles deletions; request-driven answers absence
- *   directly. A presentation must not read `shared-confirmed` as proof of present existence.
+ *   since. A document the authority deleted disappears from a browser-local working copy at
+ *   its next sync (pull reconciles deletions against the authority's heads) unless a local
+ *   edit holds it, in which case pull retains the local content and rewrites its base to an
+ *   absent shared version, and the document reads `local-pending` until push delivers the edit
+ *   and settles the authority's conflict answer (a 412 whose actual version is `null`) as a
+ *   conflict against an absent remote, from which point it reads `local-conflict` with
+ *   `remote: null`; request-driven answers absence directly. Between syncs a deleted document
+ *   still reads `shared-confirmed` at its last served version, so a presentation must not read
+ *   `shared-confirmed` as proof of present existence.
  * - `local-pending`: the working copy holds a local edit the authority has not accepted;
  *   `requestId` names the journaled intent that will deliver it and `base` the shared version
  *   the edit was made against.

package/dist/platform.js.map

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

package/dist/remote-backend.d.ts

@@ -40,8 +40,9 @@
  * This module touches NO filesystem and parses NO markdown — like {@link MemoryBackend},
  * it proves the engine leaks no assumptions beyond the {@link StorageBackend} contract.
  */
+import { type DocumentHead } from "./heads-digest.js";
 import { type Outcome } from "./uncertain-write.js";
-import type { BlobKey, ConceptId, DeleteOptions, HeadResult, OkfDocument, QueryFilter, ReadBlobResult, ReadResult, ReservedFilename, ReservedReadResult, StorageBackend, Version, VersionInfo, WriteOptions } from "./types.js";
+import type { BlobKey, ConceptId, DeleteOptions, Frontmatter, HeadResult, OkfDocument, QueryFilter, ReadBlobResult, ReadResult, ReservedFilename, ReservedReadResult, StorageBackend, Version, VersionInfo, WriteOptions } from "./types.js";
 /**
  * An injectable fetch-like transport: given a `Request`, resolve a `Response`. This
  * is exactly the shape {@link createRouter} (in `@superbee/server`) returns,
@@ -86,7 +87,7 @@ export declare class RemoteError extends Error {
     readonly code: string;
     /** The raw HTTP status that produced this error. */
     readonly status: number;
-    constructor(message: string, code: string, status: number);
+    constructor(message: string, code: string, status: number, cause?: unknown);
 }
 /** The deployment-scoped capability booleans a wire authority reports (`docs/WIRE-PROTOCOL.md`). */
 export interface WireCapabilities {
@@ -97,6 +98,47 @@ export interface WireCapabilities {
     blobs: boolean;
     /** Whether document writes carrying `Idempotency-Key` are recorded and readable by lookup. */
     operations: boolean;
+    /** Whether `GET /heads` answers every document id and version under one digest, with `304`. */
+    heads: boolean;
+    /** Whether `GET /snapshot` streams every document as terminated NDJSON. */
+    snapshot: boolean;
+}
+/** Options for {@link RemoteBackend.heads}. */
+export interface HeadsOptions {
+    /** A digest from an earlier `heads` or `snapshot` answer; the authority answers `304` when it still holds it. */
+    ifNoneMatch?: string;
+}
+/** A `200` from `GET /heads`: every document id and version, and the digest over them. */
+export interface HeadsResult {
+    digest: string;
+    heads: DocumentHead[];
+}
+/** The snapshot's first line: how many documents follow and the digest `heads` would return for this state. */
+export interface SnapshotHeader {
+    count: number;
+    digest: string;
+}
+/** One `doc` line of a snapshot. */
+export interface SnapshotDocument {
+    id: ConceptId;
+    version: Version;
+    frontmatter: Frontmatter;
+    body: string;
+}
+/**
+ * A snapshot as {@link RemoteBackend.snapshot} hands it over: the header, already parsed, and
+ * the documents as they stream. Iterating `docs` to completion is the completeness signal: the
+ * loop ends only after the `end` line arrived with the announced count and the digest recomputed
+ * over the received `{ id, version }` rows equals the header's, and it throws
+ * `SNAPSHOT_TRUNCATED` (the body ended or failed first) or `SNAPSHOT_DIGEST_MISMATCH` (the body
+ * was whole but describes a state the header did not announce) otherwise, so a consumer that
+ * writes batches as they arrive has one control path and never needs to inspect a terminator
+ * or a digest itself. A consumer records the header digest as matched only after the loop
+ * ended normally.
+ */
+export interface RemoteSnapshot {
+    header: SnapshotHeader;
+    docs: AsyncIterable<SnapshotDocument>;
 }
 /**
  * The client half of the wire-protocol v0 contract: implements {@link StorageBackend}
@@ -128,6 +170,28 @@ export declare class RemoteBackend implements StorageBackend {
      * sends any intent. Missing booleans read as `false`.
      */
     wireCapabilities(): Promise<WireCapabilities>;
+    /**
+     * `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.
+     */
+    heads(options?: HeadsOptions): Promise<HeadsResult | null>;
+    /**
+     * `GET /snapshot`: the whole bundle in one response. The header line is parsed before this
+     * resolves, so a non-2xx or a body without a header rejects here with the usual typed error;
+     * 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(): Promise<RemoteSnapshot>;
     /**
      * `GET /operations/{requestId}`: the authority's recorded outcome for an identified write, or
      * `null` when it holds nothing under that identity (never recorded, or recorded and expired;

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

@@ -1 +1 @@
-{"version":3,"file":"remote-backend.d.ts","sourceRoot":"","sources":["../src/remote-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEvE,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,aAAa,EAEb,UAAU,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AAWpB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhE,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,yGAAyG;IACzG,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,uGAAuG;IACvG,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM1D;AAED,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;CACrB;AAuHD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,oBAAoB;IAQzC,wEAAwE;IACxE,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,wFAAwF;IACxF,OAAO,CAAC,GAAG;YAIG,IAAI;IA0ClB,wEAAwE;YAC1D,OAAO;IAoBf,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAYxC,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCjD,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB1F;;;;;;OAMG;IACG,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAenD;;;;;OAKG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAY3D,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ7C;;;;;OAKG;YACW,QAAQ;IAwBhB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMjD;;;;;;;;;;OAUG;IACG,UAAU,CAAC,MAAM,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAa3D,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiB/C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAUrF,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAkBnB;;;;;;;;;OASG;IACG,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBpE,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAWtD,SAAS,CACb,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAmBnB,8FAA8F;IACxF,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAYvE,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ1C,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAiBrD"}
+{"version":3,"file":"remote-backend.d.ts","sourceRoot":"","sources":["../src/remote-backend.ts"],"names":[],"mappings":"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"}

package/dist/remote-backend.js

@@ -42,7 +42,8 @@
  */
 import { DEFAULT_BLOB_CONTENT_TYPE } from "./content-type.js";
 import { InvalidInputError } from "./errors.js";
-import { assertSafeBlobKey, assertSafeConceptId } from "./paths.js";
+import { headsDigest, isHeadsDigest } from "./heads-digest.js";
+import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, assertSafeReservedFilename, compareStorageKeys } from "./paths.js";
 import { isRequestIdentity } from "./uncertain-write.js";
 import { VersionConflict, stripETagWrapper } from "./version-transport.js";
 /**
@@ -57,8 +58,8 @@ export class RemoteError extends Error {
     code;
     /** The raw HTTP status that produced this error. */
     status;
-    constructor(message, code, status) {
-        super(message);
+    constructor(message, code, status, cause) {
+        super(message, cause === undefined ? undefined : { cause });
         this.name = "RemoteError";
         this.code = code;
         this.status = status;
@@ -122,6 +123,129 @@ 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
@@ -343,8 +467,80 @@ export class RemoteBackend {
             backlinks: flag("backlinks"),
             blobs: flag("blobs"),
             operations: flag("operations"),
+            heads: flag("heads"),
+            snapshot: flag("snapshot"),
         };
     }
+    /**
+     * `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.
+     */
+    async heads(options = {}) {
+        const headers = {};
+        if (options.ifNoneMatch !== undefined)
+            headers["If-None-Match"] = etagForm(options.ifNoneMatch);
+        const res = await this.send("/heads", { method: "GET", headers });
+        if (res.status === 304) {
+            // Only a conditional request can be answered `304`; to an unconditional one it is a
+            // malformed answer, not "nothing changed", since there is no digest it could be relative to.
+            if (options.ifNoneMatch === undefined)
+                throw malformed("wire heads answered 304 to a request that sent no If-None-Match");
+            return null;
+        }
+        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 };
+    }
+    /**
+     * `GET /snapshot`: the whole bundle in one response. The header line is parsed before this
+     * resolves, so a non-2xx or a body without a header rejects here with the usual typed error;
+     * 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.
+     */
+    async snapshot() {
+        const res = await this.send("/snapshot", { method: "GET" });
+        if (!res.ok)
+            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) };
+    }
     /**
      * `GET /operations/{requestId}`: the authority's recorded outcome for an identified write, or
      * `null` when it holds nothing under that identity (never recorded, or recorded and expired;
@@ -403,7 +599,7 @@ export class RemoteBackend {
         const params = new URLSearchParams();
         if (prefix)
             params.set("prefix", prefix);
-        return this.pageDocs(params, (row) => row.id, prefix ?? "");
+        return (await this.pageDocs(params, (row) => row.id, prefix ?? "")).sort(compareStorageKeys);
     }
     /**
      * The seam's OPTIONAL head-projection push-down, over the SAME `GET /docs` route
@@ -441,6 +637,8 @@ export class RemoteBackend {
             : { version: v.version, actor: v.actor, timestamp: v.timestamp, agent: v.agent });
     }
     async readReserved(dir, name) {
+        assertSafeReservedDir(dir);
+        assertSafeReservedFilename(name);
         const qs = dir ? `?dir=${encodeURIComponent(dir)}` : "";
         const res = await this.send(`/reserved/${name}${qs}`, { method: "GET" });
         if (res.status === 404)
@@ -452,6 +650,8 @@ export class RemoteBackend {
         return { content: payload.content, version };
     }
     async writeReserved(dir, name, content, options = {}) {
+        assertSafeReservedDir(dir);
+        assertSafeReservedFilename(name);
         assertValidExpectedVersion(options.expectedVersion);
         const headers = { "content-type": "application/json" };
         if (options.expectedVersion === null)
@@ -579,7 +779,7 @@ export class RemoteBackend {
                 break;
             cursor = payload.next_cursor;
         }
-        return keys;
+        return keys.sort(compareStorageKeys);
     }
 }
 //# sourceMappingURL=remote-backend.js.map