@superbee/core 0.2.0-pre.4 → 0.2.0-pre.41

package/dist/hosted-transport/carrier.js

@@ -0,0 +1,260 @@
+import { isAgentLabelVia, isWriteRequestId, isWriteBinding } from "../write-identity.js";
+/** The header that carries {@link HostedRequestOptions.workspace}. */
+export const WORKSPACE_HEADER = "Superbee-Workspace";
+/** A namespaced tenant id (`tenant:holaxis`, `org:…`): the shape the host checks before admission. */
+const TENANT_ID = /^[a-z][a-z0-9-]{0,15}:[A-Za-z0-9._-]{1,128}$/;
+/** Whether `value` has the shape of a tenant id the workspace header may carry. */
+export function isWorkspaceTenantId(value) {
+    return typeof value === "string" && TENANT_ID.test(value);
+}
+/** The header that carries {@link HostedRequestOptions.acceptDeletes}. */
+export const ACCEPT_DELETES_HEADER = "X-Superbee-Accept-Deletes";
+/** The largest acknowledgment the host admits. */
+export const MAXIMUM_ACCEPTED_DELETIONS = 100000;
+/** Whether `value` is an acknowledgment count the host admits: an integer from 1 to 100,000. */
+export function isAcceptedDeletionCount(value) {
+    return Number.isSafeInteger(value) && value >= 1 && value <= MAXIMUM_ACCEPTED_DELETIONS;
+}
+/** The header that carries {@link HostedRequestOptions.recreate}. */
+export const RECREATE_HEADER = "X-Superbee-Recreate";
+/** The header that carries {@link HostedRequestOptions.via}. */
+export const VIA_HEADER = "X-Superbee-Via";
+/**
+ * Whether `value` is a `via` token the host admits: 1 to 32 characters of `[a-z0-9._-]`, never
+ * starting with `superbee` (Superbee's own names). The same rule as the host's `isAgentLabelVia`;
+ * the `/sync/v1` golden exchanges (`create-200-ok-via`, `write-400-invalid-via`) pin the header
+ * and the host's refusal. A token the host refused would make every write a terminal 400.
+ */
+export { isAgentLabelVia } from "../write-identity.js";
+/**
+ * The cause a carrier's `unavailable` carries when the answer was larger than the request's
+ * `maximum`: the host answered, and the same request gets the same answer, so a reader may report
+ * it as a deterministic refusal rather than an outage. The carrier's code stays `unavailable`.
+ */
+export class HostedAnswerTooLarge extends Error {
+    name = "HostedAnswerTooLarge";
+    maximum;
+    constructor(maximum) {
+        super(`the answer is larger than ${maximum} bytes`);
+        this.maximum = maximum;
+    }
+}
+/** True when `error` is a carrier failure because the answer exceeded its bound. */
+export function isAnswerTooLarge(error) {
+    return error instanceof HostedCarrierError && error.cause instanceof HostedAnswerTooLarge;
+}
+export class HostedCarrierError extends Error {
+    name = "HostedCarrierError";
+    code;
+    constructor(code, options) {
+        super(code, options);
+        this.code = code;
+    }
+}
+const ROUTE_HEADER = /^x-superbee-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ROUTE_HEADER_VALUE = /^[\x20-\x7e]{0,1024}$/;
+async function readBounded(response, maximum) {
+    if (!response.body)
+        return undefined;
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            size += part.value.byteLength;
+            if (size > maximum)
+                throw new HostedCarrierError("unavailable", { cause: new HostedAnswerTooLarge(maximum) });
+            chunks.push(part.value);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+    if (size === 0)
+        return undefined;
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes));
+    }
+    catch (cause) {
+        throw new HostedCarrierError("unavailable", { cause });
+    }
+}
+/** Restart `deadlineMs` at every chunk, so a slow but live stream is not cut and a stalled one is. */
+function idleBounded(body, deadlineMs, abort) {
+    let timer;
+    const arm = () => {
+        clearTimeout(timer);
+        timer = setTimeout(abort, deadlineMs);
+    };
+    arm();
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            arm();
+            controller.enqueue(chunk);
+        },
+        flush() {
+            clearTimeout(timer);
+        },
+        // A consumer that stops reading, or a body that fails, never reaches flush; a live timer
+        // would hold the process open for the rest of the deadline.
+        cancel() {
+            clearTimeout(timer);
+        },
+    }));
+}
+/** A request's headers: its own fields, then the credential and the content headers, which always win. */
+function requestHeaders(credentials, extra, type) {
+    const headers = new Headers(extra);
+    for (const [name, value] of Object.entries(credentials))
+        headers.set(name, value);
+    headers.set("Content-Type", type);
+    headers.set("Accept", "application/json");
+    return headers;
+}
+/**
+ * A carrier over `fetch` with caller-supplied credential headers: the shape the CLI's bearer
+ * carrier takes. Requests are `POST` with a JSON body (or, through `bytes`, a raw one), never follow
+ * redirects, and are refused before sending when the identity, binding or a route header is
+ * malformed.
+ */
+export function createFetchCarrier(options) {
+    const fetcher = options.fetch ?? fetch;
+    const deadlineMs = options.deadlineMs ?? 15_000;
+    const bindingHeader = options.bindingHeader ?? "X-Superbee-Checkout";
+    const base = new URL(options.baseUrl);
+    async function send(path, body, signal, extra, deadline) {
+        if (!path.startsWith("/"))
+            throw new TypeError(`hosted route '${path}' must be absolute`);
+        let credentials;
+        try {
+            credentials = await options.credentials(signal);
+        }
+        catch (cause) {
+            throw new HostedCarrierError("denied", { cause });
+        }
+        if (signal.aborted)
+            throw new HostedCarrierError("denied");
+        // A credential header `fetch` cannot carry is no credential: nothing is sent.
+        let headers;
+        try {
+            headers = requestHeaders(credentials, extra, body.type);
+        }
+        catch (cause) {
+            throw new HostedCarrierError("denied", { cause });
+        }
+        try {
+            return await fetcher(new URL(path, base), {
+                method: "POST",
+                redirect: "error",
+                headers,
+                body: body.content,
+                signal: AbortSignal.any([signal, deadline]),
+            });
+        }
+        catch (cause) {
+            throw new HostedCarrierError("unavailable", { cause });
+        }
+    }
+    const jsonBody = (input) => ({ type: "application/json", content: JSON.stringify(input) });
+    // Headers the carrier sets itself, which a route's own fields never name.
+    const owned = new Set(["x-superbee-write-request", bindingHeader.toLowerCase(), RECREATE_HEADER.toLowerCase(), VIA_HEADER.toLowerCase(), ACCEPT_DELETES_HEADER.toLowerCase(), WORKSPACE_HEADER.toLowerCase()]);
+    /**
+     * The headers the carrier owns for one request, each refused before sending when malformed. The
+     * one place a JSON and a raw request derive their identity, binding, `recreate`, `via` and
+     * deletion acknowledgment headers.
+     */
+    function carrierHeaders(request) {
+        if (request.writeRequest !== undefined && !isWriteRequestId(request.writeRequest))
+            throw new HostedCarrierError("denied");
+        if (request.binding !== undefined && !isWriteBinding(request.binding))
+            throw new HostedCarrierError("denied");
+        if (request.recreate !== undefined && !isWriteBinding(request.recreate))
+            throw new HostedCarrierError("denied");
+        if (request.via !== undefined && !isAgentLabelVia(request.via))
+            throw new HostedCarrierError("denied");
+        if (request.acceptDeletes !== undefined && !isAcceptedDeletionCount(request.acceptDeletes))
+            throw new HostedCarrierError("denied");
+        if (request.workspace !== undefined && !isWorkspaceTenantId(request.workspace))
+            throw new HostedCarrierError("denied");
+        const headers = {};
+        if (request.writeRequest !== undefined)
+            headers["X-Superbee-Write-Request"] = request.writeRequest;
+        if (request.binding !== undefined)
+            headers[bindingHeader] = request.binding;
+        if (request.recreate !== undefined)
+            headers[RECREATE_HEADER] = request.recreate;
+        if (request.via !== undefined)
+            headers[VIA_HEADER] = request.via;
+        if (request.acceptDeletes !== undefined)
+            headers[ACCEPT_DELETES_HEADER] = String(request.acceptDeletes);
+        if (request.workspace !== undefined)
+            headers[WORKSPACE_HEADER] = request.workspace;
+        return headers;
+    }
+    async function answer(path, body, signal, extra, maximum) {
+        // An answer is always read within a bound: an unset or nonsensical maximum refuses before sending.
+        if (!Number.isSafeInteger(maximum) || maximum <= 0)
+            throw new HostedCarrierError("denied");
+        const deadline = AbortSignal.timeout(deadlineMs);
+        const response = await send(path, body, signal, extra, deadline);
+        let read;
+        try {
+            read = await readBounded(response, maximum);
+        }
+        catch (error) {
+            // A refusal's envelope is best effort: its status already decides, and an unreadable
+            // body must never read as "not applied".
+            if (response.ok)
+                throw error instanceof HostedCarrierError ? error : new HostedCarrierError("unavailable", { cause: error });
+            read = undefined;
+        }
+        return { status: response.status, headers: response.headers, body: read };
+    }
+    return {
+        async json(path, input, signal, request) {
+            return answer(path, jsonBody(input), signal, carrierHeaders(request), request.maximum);
+        },
+        async bytes(path, body, signal, request) {
+            if (!(body instanceof Uint8Array))
+                throw new HostedCarrierError("denied");
+            // Named, not spread: a raw request carries no `recreate` or deletion acknowledgment.
+            const own = carrierHeaders({ writeRequest: request.writeRequest, binding: request.binding, via: request.via });
+            const extra = {};
+            for (const [name, value] of Object.entries(request.headers ?? {})) {
+                const lower = name.toLowerCase();
+                if (!ROUTE_HEADER.test(lower) || owned.has(lower) || lower in extra || typeof value !== "string" || !ROUTE_HEADER_VALUE.test(value))
+                    throw new HostedCarrierError("denied");
+                extra[lower] = value;
+            }
+            Object.assign(extra, own);
+            // The body is sent as given; `fetch` derives its exact Content-Length from the bytes.
+            return answer(path, { type: "application/octet-stream", content: body }, signal, extra, request.maximum);
+        },
+        async stream(path, input, signal) {
+            const idle = new AbortController();
+            const firstByte = setTimeout(() => idle.abort(), deadlineMs);
+            let response;
+            try {
+                response = await send(path, jsonBody(input), signal, {}, idle.signal);
+            }
+            finally {
+                clearTimeout(firstByte);
+            }
+            if (!response.ok || !response.body) {
+                const body = await readBounded(response, 64 * 1024).catch(() => undefined);
+                return { status: response.status, headers: response.headers, ok: false, body };
+            }
+            return { status: response.status, headers: response.headers, ok: true, body: idleBounded(response.body, deadlineMs, () => idle.abort()) };
+        },
+    };
+}
+//# sourceMappingURL=carrier.js.map

package/dist/hosted-transport/carrier.js.map

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

package/dist/hosted-transport/document-backend.d.ts

@@ -0,0 +1,74 @@
+import type { StorageBackend } from "../types.js";
+import { type OperationIntent, type Outcome } from "../uncertain-write.js";
+import { VersionConflict } from "../version-transport.js";
+import type { HostedCarrier } from "./carrier.js";
+import type { HostedReadAdapter } from "./read-adapter.js";
+import { type WholeDocumentRoutes } from "./whole-document-transport.js";
+/** Authority and interpretation pinned by the host before constructing this backend. */
+export interface HostedDocumentScope {
+    readonly tenant: string;
+    readonly bundleId: string;
+    readonly registration: string;
+    readonly binding: string;
+    readonly workspace: string | null;
+    readonly okfVersion: "0.1" | "0.2";
+    readonly mode: "write";
+    readonly bodyPolicy: "protected";
+    readonly tombstonePolicy: "refuse";
+}
+export interface HostedDocumentIntent {
+    readonly scope: Readonly<HostedDocumentScope>;
+    readonly intent: Readonly<OperationIntent>;
+    /** Advisory input only; the carrier and host determine persisted attribution. */
+    readonly advisoryActor: string | null;
+    /** Binds immutable scope, content, premise, identity and original creation instant. */
+    readonly digest: string;
+    readonly outcome?: Readonly<Outcome>;
+}
+/**
+ * Trusted persistence, outside the bundle. All methods are atomic and durable before resolving.
+ * prepareOrReadAndClaim inserts a new descriptor with in_flight/attempts=1 and returns fresh=true
+ * to exactly one caller. An existing row, even pending or in_flight, ALWAYS returns fresh=false.
+ * A failed/uncertain acknowledgement grants no freshness. Never overwrite a different descriptor
+ * under an identity. settle compares the immutable digest, preserves the descriptor, and must not
+ * overwrite a definitive outcome; contradictory settlement must refuse. A refused outcome with
+ * executed:"unknown" is unresolved attempt evidence, including in previously stored records.
+ * Retain descriptor and outcome through the consumer's acceptance acknowledgement.
+ */
+export interface HostedDocumentIntentPort {
+    prepareOrReadAndClaim(candidate: HostedDocumentIntent): Promise<{
+        record: HostedDocumentIntent;
+        fresh: boolean;
+    }>;
+    settle(record: HostedDocumentIntent, outcome: Outcome): Promise<void>;
+}
+export declare class HostedDocumentBackendError extends Error {
+    readonly name = "HostedDocumentBackendError";
+    readonly code: string;
+    readonly requestId?: string;
+    readonly record?: HostedDocumentIntent;
+    constructor(code: string, message: string, requestId?: string, record?: HostedDocumentIntent, options?: ErrorOptions);
+}
+/** CAS conflict retaining the original identity and tombstone receipt for its consumer. */
+export declare class HostedDocumentVersionConflict extends VersionConflict {
+    readonly requestId: string;
+    readonly record: HostedDocumentIntent;
+    constructor(record: HostedDocumentIntent);
+}
+export interface HostedDocumentBackendOptions {
+    readonly reader: HostedReadAdapter;
+    readonly carrier: HostedCarrier;
+    readonly scope: HostedDocumentScope;
+    readonly intents: HostedDocumentIntentPort;
+    readonly maximumDocuments: number;
+    readonly routes?: WholeDocumentRoutes;
+    readonly now?: () => number;
+}
+/**
+ * No auth authority or general wire routes are supplied here. An actor option is validated as
+ * advisory only; agent/bodyReplace
+ * options are refused: the host attributes normal writes and retains its body protection policy.
+ * Every reopened descriptor is lookup-only; absent or expired receipts never authorize a resend.
+ */
+export declare function createHostedDocumentBackend(options: HostedDocumentBackendOptions): StorageBackend;
+//# sourceMappingURL=document-backend.d.ts.map

package/dist/hosted-transport/document-backend.d.ts.map

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

package/dist/hosted-transport/document-backend.js

@@ -0,0 +1,160 @@
+/** A finite document StorageBackend over hosted's existing read and write grammars. */
+import { isOkfActor } from "../okf-actor.js";
+import { stringifyDoc } from "../frontmatter.js";
+import { assertSafeConceptId, isReservedFile, pathFromConceptId } from "../paths.js";
+import { sha256HexOfUtf8 } from "../sha256.js";
+import { performUncertainWrite } from "../uncertain-write.js";
+import { isContentVersion, VersionConflict } from "../version-transport.js";
+import { isWriteBinding, isWriteRequestId } from "../write-identity.js";
+import { createWholeDocumentTransport, wholeDocumentRequest } from "./whole-document-transport.js";
+export class HostedDocumentBackendError extends Error {
+    name = "HostedDocumentBackendError";
+    code;
+    requestId;
+    record;
+    constructor(code, message, requestId, record, options) {
+        super(message, options);
+        this.code = code;
+        this.requestId = requestId;
+        this.record = record;
+    }
+}
+/** CAS conflict retaining the original identity and tombstone receipt for its consumer. */
+export class HostedDocumentVersionConflict extends VersionConflict {
+    requestId;
+    record;
+    constructor(record) {
+        const outcome = record.outcome;
+        if (outcome?.kind !== "conflict")
+            throw new TypeError("A recorded conflict is required.");
+        super(record.intent.target, record.intent.base, outcome.actual);
+        this.requestId = record.intent.requestId;
+        this.record = record;
+    }
+}
+function immutable(record) {
+    const { intent: i, scope: s } = record;
+    return JSON.stringify([s.tenant, s.bundleId, s.registration, s.binding, s.workspace, s.okfVersion, s.mode, s.bodyPolicy, s.tombstonePolicy,
+        record.advisoryActor, i.requestId, i.kind, i.target, i.base, i.local, i.content, i.createdAt]);
+}
+function capture(record) {
+    return Object.freeze({ scope: Object.freeze({ ...record.scope }), intent: Object.freeze({ ...record.intent }), advisoryActor: record.advisoryActor, digest: record.digest,
+        ...(record.outcome === undefined ? {} : { outcome: Object.freeze({ ...record.outcome }) }) });
+}
+function sameInput(a, b) {
+    return a.scope.workspace === b.scope.workspace && a.intent.base === b.intent.base && a.advisoryActor === b.advisoryActor &&
+        immutable({ ...a, intent: { ...a.intent, createdAt: b.intent.createdAt } }) === immutable(b);
+}
+function refuse() { throw new HostedDocumentBackendError("unsupported", "This backend supports only finite document reads and conditional document writes."); }
+async function unsupported() { return refuse(); }
+/** The shared Outcome contract marks this as attempt evidence, never an identity verdict. */
+function identityOutcome(outcome) {
+    return outcome.kind === "refused" && outcome.executed === "unknown"
+        ? { kind: "unknown", refusal: { code: outcome.code, message: outcome.message } }
+        : outcome;
+}
+/**
+ * No auth authority or general wire routes are supplied here. An actor option is validated as
+ * advisory only; agent/bodyReplace
+ * options are refused: the host attributes normal writes and retains its body protection policy.
+ * Every reopened descriptor is lookup-only; absent or expired receipts never authorize a resend.
+ */
+export function createHostedDocumentBackend(options) {
+    const { reader, carrier, intents } = options;
+    const scope = Object.freeze({ ...options.scope });
+    if (![scope.tenant, scope.bundleId, scope.registration].every((v) => typeof v === "string" && v.length > 0) ||
+        !isWriteBinding(scope.binding) || !(scope.workspace === null || typeof scope.workspace === "string" && scope.workspace.length > 0) ||
+        !["0.1", "0.2"].includes(scope.okfVersion) || scope.mode !== "write" || scope.bodyPolicy !== "protected" || scope.tombstonePolicy !== "refuse")
+        throw new TypeError("Invalid hosted document scope.");
+    const maximumDocuments = options.maximumDocuments;
+    if (!Number.isSafeInteger(maximumDocuments) || maximumDocuments < 1)
+        throw new TypeError("maximumDocuments must be a positive integer.");
+    const now = options.now ?? Date.now;
+    const routes = options.routes === undefined ? undefined : Object.freeze({ ...options.routes });
+    return {
+        read: (id) => reader.read(id),
+        readMany: (ids) => reader.readMany(ids),
+        readReserved: (dir, name) => reader.readReserved(dir, name),
+        async exists(id) {
+            try {
+                await reader.read(id);
+                return true;
+            }
+            catch (error) {
+                if (error?.code === "ENOENT")
+                    return false;
+                throw error;
+            }
+        },
+        async list(prefix) {
+            const result = await reader.heads();
+            if (result === null)
+                throw new HostedDocumentBackendError("inventory_incomplete", "A complete document inventory is required.");
+            if (result.heads.length > maximumDocuments)
+                throw new HostedDocumentBackendError("inventory_bound", "Document inventory exceeds the configured bound.");
+            return result.heads.map((head) => head.id).filter((id) => prefix === undefined || id.startsWith(prefix));
+        },
+        async write(id, doc, writeOptions) {
+            assertSafeConceptId(id);
+            if (isReservedFile(pathFromConceptId(id)))
+                refuse();
+            if (!writeOptions || typeof writeOptions.requestId !== "string" || !isWriteRequestId(writeOptions.requestId) ||
+                !(writeOptions.expectedVersion === null || isContentVersion(writeOptions.expectedVersion)))
+                throw new HostedDocumentBackendError("invalid_input", "A UUIDv4 requestId and explicit create/replace CAS are required.");
+            if (writeOptions.actor !== undefined && !isOkfActor(writeOptions.actor))
+                throw new HostedDocumentBackendError("invalid_input", "actor must be an OKF actor; persisted attribution belongs to the host.");
+            if (Object.entries(writeOptions).some(([key, value]) => value !== undefined && !["requestId", "expectedVersion", "actor"].includes(key)))
+                refuse();
+            const requestId = writeOptions.requestId;
+            const content = stringifyDoc(doc.frontmatter, doc.body);
+            const intent = { requestId, kind: "document.write", target: id, base: writeOptions.expectedVersion,
+                local: `sha256:${sha256HexOfUtf8(content)}`, content, createdAt: new Date(now()).toISOString(), attempts: 1, state: "in_flight" };
+            // Preflight uses the same semantic owner as the actual transport, before persistence.
+            wholeDocumentRequest(scope.bundleId, intent, scope.okfVersion);
+            const initial = { scope, intent, advisoryActor: writeOptions.actor ?? null, digest: "" };
+            const candidate = capture({ ...initial, digest: sha256HexOfUtf8(immutable(initial)) });
+            let record;
+            let fresh;
+            try {
+                const prepared = await intents.prepareOrReadAndClaim(candidate);
+                record = capture(prepared.record);
+                fresh = prepared.fresh;
+            }
+            catch (cause) {
+                throw new HostedDocumentBackendError("outcome_unknown", "Intent claim acknowledgement is uncertain; retain the original identity.", requestId, undefined, { cause });
+            }
+            if (!sameInput(record, candidate) || record.digest !== sha256HexOfUtf8(immutable(record)) ||
+                record.intent.local !== `sha256:${sha256HexOfUtf8(record.intent.content)}` || record.intent.bodyReplace !== undefined || record.intent.recreates !== undefined ||
+                !Number.isFinite(Date.parse(record.intent.createdAt)) || typeof fresh !== "boolean" ||
+                !Number.isSafeInteger(record.intent.attempts) || record.intent.attempts < 0 ||
+                !["pending", "in_flight", "acknowledged", "conflict", "refused", "unknown"].includes(record.intent.state) ||
+                fresh && (record.digest !== candidate.digest || record.intent.attempts !== 1 || record.intent.state !== "in_flight" || record.outcome !== undefined))
+                throw new HostedDocumentBackendError("intent_conflict", "Stored identity does not match the immutable write and scope.", requestId);
+            const transport = createWholeDocumentTransport({ carrier, bundleId: scope.bundleId, binding: scope.binding, okfVersion: scope.okfVersion,
+                remote: reader, intentFor: async (key) => key === requestId ? { ...record.intent } : undefined, routes, signal: reader.signal, now });
+            const storedOutcome = record.outcome === undefined ? undefined : identityOutcome(record.outcome);
+            const result = storedOutcome && storedOutcome.kind !== "unknown" ? { outcome: storedOutcome } :
+                await performUncertainWrite({ submit: async (sending, opts) => identityOutcome(await transport.submit(sending, opts)), lookup: async (key) => {
+                        const answer = await transport.lookup(key);
+                        return answer === null || answer.kind === "pending" ? null : identityOutcome(answer);
+                    } }, { ...record.intent }, { settlement: "recorded-only", start: fresh ? "submit-claimed" : "lookup", signal: reader.signal });
+            const outcome = result.outcome;
+            try {
+                await intents.settle(record, outcome);
+            }
+            catch (cause) {
+                throw new HostedDocumentBackendError("outcome_unknown", "Outcome persistence is uncertain; retain the original identity.", requestId, capture({ ...record, outcome }), { cause });
+            }
+            switch (outcome.kind) {
+                case "committed": return outcome.version;
+                case "conflict": throw new HostedDocumentVersionConflict(capture({ ...record, outcome }));
+                case "refused": throw new HostedDocumentBackendError(outcome.code, outcome.message, requestId, capture({ ...record, outcome }));
+                case "unknown": throw new HostedDocumentBackendError("outcome_unknown", "The original write outcome remains unknown.", requestId, capture({ ...record, outcome }));
+            }
+        },
+        capabilities: () => ({ enforced_cas: true, history: false, blobs: false }),
+        versions: unsupported, writeReserved: unsupported, delete: unsupported, readBlob: unsupported, writeBlob: unsupported,
+        existsBlob: unsupported, listBlobs: unsupported, deleteBlob: unsupported,
+    };
+}
+//# sourceMappingURL=document-backend.js.map

package/dist/hosted-transport/document-backend.js.map

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

package/dist/hosted-transport/history-pages.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Paging back through one document's hosted history (`documents.history.v1`). The host serves a
+ * lineage newest first, a page at a time: the first page (no `before`) states the lineage's
+ * `total`, and each later page lists the versions older than the last one read. Older versions
+ * never change, so a write that only appends to the lineage while the pages are read leaves the
+ * listing a true picture of the lineage as the first page saw it.
+ *
+ * What does break a listing is a new lineage: the document deleted (and perhaps recreated, its
+ * `seq` restarting at 1) between two pages. A later page that answers `document_not_found` says
+ * so directly; otherwise, after a listing of more than one page, the first page's newest version
+ * is read again by its `seq`, and a listing whose newest version is gone or different starts
+ * again from the first page, after {@link pageRestartDelay}, at most {@link HEADS_PAGE_ATTEMPTS}
+ * times in all. Pages from two lineages are never assembled into one listing.
+ */
+import { type HostedHistoryAnswer, type HostedHistoryRequest, type HostedHistoryVersion, type HostedOperationRefusal } from "./read-adapter.js";
+/** Reads one page of a document's history (a client's bounded history read). */
+export type HistoryPageReader = (request: HostedHistoryRequest) => Promise<HostedHistoryAnswer>;
+export interface HistoryListingRequest {
+    readonly documentId: string;
+    /** The newest this many versions, or fewer when the lineage is shorter. */
+    readonly wanted: number;
+    /** Ask each page for its versions' stored bytes (a page's content shares the host's 1 MiB bound). */
+    readonly includeContent?: boolean;
+    /** Versions per request, 1..{@link HISTORY_PAGE_LIMIT} (default: the limit). */
+    readonly pageSize?: number;
+}
+export type HistoryListing = 
+/** Newest first; `total` is the lineage's length as the first page stated it. */
+{
+    readonly status: "listed";
+    readonly versions: readonly HostedHistoryVersion[];
+    readonly total: number;
+}
+/** The first page answered `document_not_found`: the host has no such document. */
+ | {
+    readonly status: "absent";
+}
+/** The host refused a page for another reason; the caller maps it. */
+ | {
+    readonly status: "refused";
+    readonly refusal: HostedOperationRefusal;
+}
+/** The lineage changed under every attempt. */
+ | {
+    readonly status: "moved";
+};
+export interface HistoryListingOptions {
+    readonly signal: AbortSignal;
+    /** Test seam: how the listing waits before starting again. */
+    readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    readonly attempts?: number;
+}
+/** The newest `wanted` versions of one lineage, paged back with `before`. */
+export declare function readHistoryListing(readPage: HistoryPageReader, request: HistoryListingRequest, options: HistoryListingOptions): Promise<HistoryListing>;
+//# sourceMappingURL=history-pages.d.ts.map

package/dist/hosted-transport/history-pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-pages.d.ts","sourceRoot":"","sources":["../../src/hosted-transport/history-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAsB,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEpK,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAEhG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qGAAqG;IACrG,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,cAAc;AACxB,iFAAiF;AAC/E;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAC3G,mFAAmF;GACjF;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE;AAC/B,sEAAsE;GACpE;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE;AAC1E,+CAA+C;GAC7C;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAsCD,6EAA6E;AAC7E,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ7J"}