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

package/dist/memory-backend.js

@@ -12,8 +12,8 @@
  *   - per-write ACTOR attribution recorded on every revision;
  *   - a real batch {@link MemoryBackend.readMany}.
  *
- * It touches NO filesystem and NO markdown serialization for storage — documents are
- * held as parsed {@link OkfDocument} objects, keyed by concept id — so running the
+ * It touches NO filesystem — bodies and YAML metadata snapshots are held in memory,
+ * keyed by concept id — so running the
  * core operations over it exercises exactly the parts of the engine that must be
  * backend-neutral. Version tokens are still content-addressed via {@link contentVersion},
  * so an engine-written document carries the SAME token here as on disk.
@@ -25,12 +25,10 @@
  * the dual-backend / wire-protocol contract tests diverge.
  */
 import { resolveContentType } from "./content-type.js";
-import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, toPosix } from "./paths.js";
-import { blobVersion, contentVersion, defaultActor, VersionConflict, versionOfBytes } from "./versioning.js";
-/** Deep copy so stored state never aliases a caller's object (and vice-versa). */
-function snapshot(value) {
-    return structuredClone(value);
-}
+import { readBundleOkfVersion } from "./engine.js";
+import { MalformedDocumentError, parseFrontmatter, stringifyFrontmatter, stringifyWithSerializedFrontmatter } from "./frontmatter.js";
+import { assertSafeBlobKey, assertSafeConceptId, assertSafeReservedDir, assertSafeReservedFilename, compareStorageKeys } from "./paths.js";
+import { blobVersion, defaultActor, VersionConflict, versionOfBytes } from "./versioning.js";
 /** An ENOENT-shaped rejection so missing-document handling matches {@link FilesystemBackend}. */
 function notFound(id) {
     const err = new Error(`no concept document '${id}'`);
@@ -39,8 +37,7 @@ function notFound(id) {
 }
 /** Bundle-relative key for a reserved file (`""` = bundle root), mirroring the fs adapter's layout. */
 function reservedKey(dir, name) {
-    const d = toPosix(dir).replace(/^\.?\//, "").replace(/\/$/, "");
-    return d === "" ? name : `${d}/${name}`;
+    return dir === "" ? name : `${dir}/${name}`;
 }
 /**
  * A fully in-memory OKF store implementing the {@link StorageBackend} contract for
@@ -61,7 +58,18 @@ export class MemoryBackend {
         const head = this.chains.get(id)?.[0];
         if (!head)
             throw notFound(id);
-        return { doc: snapshot(head.doc), version: head.version };
+        let okfVersion;
+        try {
+            okfVersion = await readBundleOkfVersion(this);
+        }
+        catch (error) {
+            if (!(error instanceof MalformedDocumentError))
+                throw error;
+        }
+        return {
+            doc: { ...head.doc, frontmatter: parseFrontmatter(head.frontmatterSource, id, { okfVersion }) },
+            version: head.version,
+        };
     }
     async readMany(ids) {
         // Validate every id up front (same contract as FilesystemBackend.readMany), then a
@@ -82,7 +90,8 @@ export class MemoryBackend {
         // that route id on reads because document bytes do not serialize `doc.id`; mirror them here
         // instead of retaining a mismatched caller-supplied `doc.id` in the in-memory snapshot.
         const storedDoc = { ...doc, id };
-        const version = contentVersion(storedDoc);
+        const frontmatterSource = stringifyFrontmatter(storedDoc.frontmatter);
+        const version = versionOfBytes(stringifyWithSerializedFrontmatter(frontmatterSource, storedDoc.body));
         // Idempotent: re-writing byte-identical content is a no-op that does not grow the
         // chain (the content address is unchanged). A genuine content change appends a revision.
         if (current === version)
@@ -93,7 +102,8 @@ export class MemoryBackend {
             timestamp: new Date().toISOString(),
             // Unlike `actor`, an unattested agent is simply absent — no default is applied.
             agent: options.agent?.trim() || undefined,
-            doc: snapshot(storedDoc),
+            frontmatterSource,
+            doc: { id, body: storedDoc.body },
         };
         this.chains.set(id, chain ? [revision, ...chain] : [revision]);
         return version;
@@ -120,7 +130,7 @@ export class MemoryBackend {
     }
     async list(prefix) {
         const ids = [...this.chains.keys()].filter((id) => !prefix || id.startsWith(prefix));
-        ids.sort((a, b) => a.localeCompare(b));
+        ids.sort(compareStorageKeys);
         return ids;
     }
     async versions(id) {
@@ -133,6 +143,7 @@ export class MemoryBackend {
     }
     async readReserved(dir, name) {
         assertSafeReservedDir(dir);
+        assertSafeReservedFilename(name);
         const content = this.reserved.get(reservedKey(dir, name));
         if (content === undefined)
             return null;
@@ -141,6 +152,7 @@ export class MemoryBackend {
     }
     async writeReserved(dir, name, content, options = {}) {
         assertSafeReservedDir(dir);
+        assertSafeReservedFilename(name);
         const key = reservedKey(dir, name);
         const existing = this.reserved.get(key);
         const current = existing === undefined ? null : versionOfBytes(existing);
@@ -207,7 +219,7 @@ export class MemoryBackend {
     }
     async listBlobs(prefix) {
         const keys = [...this.blobs.keys()].filter((k) => !prefix || k.startsWith(prefix));
-        keys.sort((a, b) => a.localeCompare(b));
+        keys.sort(compareStorageKeys);
         return keys;
     }
 }

package/dist/memory-backend.js.map

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

package/dist/paths.d.ts

@@ -11,6 +11,10 @@
 import type { ConceptId } from "./types.js";
 /** The two OKF reserved filenames, valid at any directory level (§3.1). */
 export declare const RESERVED_FILENAMES: readonly ["index.md", "log.md"];
+/** Keep locale ordering, but never let distinct spellings depend on insertion order. */
+export declare function compareStorageKeys(a: string, b: string): number;
+/** Runtime callers must obey the same finite reserved-name type as TypeScript callers. */
+export declare function assertSafeReservedFilename(name: unknown): asserts name is typeof RESERVED_FILENAMES[number];
 /** Normalize any separators to forward slashes and collapse duplicate slashes. */
 export declare function toPosix(p: string): string;
 /**
@@ -71,8 +75,8 @@ export declare function assertSafeBlobKey(key: string): void;
  * Guard a reserved-file directory (the `dir` argument to `readReserved`/`writeReserved`,
  * where `""` denotes the bundle root) against path traversal / absolute escape before it
  * is joined onto the bundle root. Unlike {@link assertSafeConceptId}, an empty string IS
- * valid here (it means "the bundle root itself"). Throws on a non-string, an absolute
- * dir, or any `..` segment.
+ * valid here (it means "the bundle root itself"). Other spellings must be canonical;
+ * aliases are rejected rather than silently normalized.
  */
 export declare function assertSafeReservedDir(dir: string): void;
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,iCAAkC,CAAC;AAElE,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAO5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAwBvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA0BnD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAWvD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,iCAAkC,CAAC;AAElE,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS/D;AAYD,0FAA0F;AAC1F,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAI3G;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAO5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAWvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAgBnD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKvD"}

package/dist/paths.js

@@ -11,6 +11,34 @@
 import { InvalidInputError } from "./errors.js";
 /** The two OKF reserved filenames, valid at any directory level (§3.1). */
 export const RESERVED_FILENAMES = ["index.md", "log.md"];
+/** Keep locale ordering, but never let distinct spellings depend on insertion order. */
+export function compareStorageKeys(a, b) {
+    const primary = a.localeCompare(b);
+    if (primary !== 0 || a === b)
+        return primary;
+    const left = Array.from(a, (character) => character.codePointAt(0));
+    const right = Array.from(b, (character) => character.codePointAt(0));
+    for (let i = 0; i < Math.min(left.length, right.length); i++) {
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    }
+    return left.length - right.length;
+}
+/** Reject spellings that cannot remain the same key across storage and wire adapters. */
+function assertPortablePath(value, label) {
+    if (/[\u0000-\u001f\u007f]/u.test(value) || /^[a-z]:/i.test(value)) {
+        throw new InvalidInputError(`${label} must not contain controls or start with a drive prefix.`);
+    }
+    if (value.includes("\\") || value.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new InvalidInputError(`${label} must be canonical and bundle-relative.`);
+    }
+}
+/** Runtime callers must obey the same finite reserved-name type as TypeScript callers. */
+export function assertSafeReservedFilename(name) {
+    if (!RESERVED_FILENAMES.includes(name)) {
+        throw new InvalidInputError("Reserved filename must be index.md or log.md.");
+    }
+}
 /** Normalize any separators to forward slashes and collapse duplicate slashes. */
 export function toPosix(p) {
     return p.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
@@ -58,19 +86,8 @@ export function assertSafeConceptId(id) {
     if (typeof id !== "string" || id.trim() === "") {
         throw new InvalidInputError("Concept id must be a non-empty string.");
     }
-    if (id.startsWith("/")) {
-        throw new InvalidInputError(`Concept id must be bundle-relative, got absolute '${id}'.`);
-    }
-    if (id.includes("\\")) {
-        throw new InvalidInputError(`Concept id must use forward slashes: '${id}'.`);
-    }
+    assertPortablePath(id, "Concept id");
     const segments = id.split("/");
-    if (segments.some((seg) => seg === "..")) {
-        throw new InvalidInputError(`Concept id must not contain '..' segments: '${id}'.`);
-    }
-    if (segments.some((seg) => seg === "." || seg === "")) {
-        throw new InvalidInputError(`Concept id must be canonical (no '.', duplicate-slash, leading './', or trailing-slash segments): '${id}'.`);
-    }
     if (segments.slice(0, -1).some((seg) => seg.toLowerCase().endsWith(".md"))) {
         throw new InvalidInputError(`Concept id must not contain a non-final segment ending in '.md': '${id}' (it collides with a concept file at that path).`);
     }
@@ -105,21 +122,11 @@ export function assertSafeBlobKey(key) {
     if (typeof key !== "string" || key.trim() === "") {
         throw new InvalidInputError("Blob key must be a non-empty string.");
     }
-    const norm = toPosix(key);
-    if (norm.startsWith("/")) {
-        throw new InvalidInputError(`Blob key must be bundle-relative, got absolute '${key}'.`);
-    }
-    const segments = norm.split("/");
-    if (segments.some((seg) => seg === "..")) {
-        throw new InvalidInputError(`Blob key must not contain '..' segments: '${key}'.`);
-    }
+    assertPortablePath(key, "Blob key");
+    const segments = key.split("/");
     if (segments.some((seg) => seg.startsWith("."))) {
         throw new InvalidInputError(`Blob key must not contain dot-prefixed segments: '${key}'.`);
     }
-    const last = segments[segments.length - 1] ?? "";
-    if (last === "") {
-        throw new InvalidInputError(`Blob key must name a file, not end with '/': '${key}'.`);
-    }
     if (segments.some((seg) => seg.toLowerCase().endsWith(".md"))) {
         throw new InvalidInputError(`Blob key '${key}' has a path segment ending in '.md' (checked case-insensitively, at ` +
             `any depth), which collides with the concept-document namespace — write it as a doc ` +
@@ -130,19 +137,14 @@ export function assertSafeBlobKey(key) {
  * Guard a reserved-file directory (the `dir` argument to `readReserved`/`writeReserved`,
  * where `""` denotes the bundle root) against path traversal / absolute escape before it
  * is joined onto the bundle root. Unlike {@link assertSafeConceptId}, an empty string IS
- * valid here (it means "the bundle root itself"). Throws on a non-string, an absolute
- * dir, or any `..` segment.
+ * valid here (it means "the bundle root itself"). Other spellings must be canonical;
+ * aliases are rejected rather than silently normalized.
  */
 export function assertSafeReservedDir(dir) {
     if (typeof dir !== "string") {
         throw new InvalidInputError("Reserved-file directory must be a string.");
     }
-    const norm = toPosix(dir);
-    if (norm.startsWith("/")) {
-        throw new InvalidInputError(`Reserved-file directory must be bundle-relative, got absolute '${dir}'.`);
-    }
-    if (norm.split("/").some((seg) => seg === "..")) {
-        throw new InvalidInputError(`Reserved-file directory must not contain '..' segments: '${dir}'.`);
-    }
+    if (dir !== "")
+        assertPortablePath(dir, "Reserved-file directory");
 }
 //# sourceMappingURL=paths.js.map

package/dist/paths.js.map

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

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