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

package/dist/hosted-transport/blob-reads.js

@@ -0,0 +1,179 @@
+/** Ordinary opaque-file reads over the supplied hosted carrier. Metadata is published only
+ * after a whole consistent listing; bytes only after their length, digest and exact MIME pin
+ * are verified. This adapter neither changes the document reader nor supplies credentials. */
+import { compareStorageKeys } from "../paths.js";
+import { captureBlobHead } from "../blob-contract.js";
+import { sha256HexOfBytes, sha256HexOfUtf8 } from "../sha256.js";
+import { isContentVersion } from "../version-transport.js";
+import { malformed, onRoute, RemoteError } from "../remote-error.js";
+import { HostedAnswerTooLarge, HostedCarrierError } from "./carrier.js";
+import { HostedReadAdapterError, readRefusal } from "./read-adapter.js";
+import { HEADS_PAGE_ATTEMPTS, isPageRestart, pageRestartDelay, pause } from "./paged-reads.js";
+export const HOSTED_BLOB_READ_BOUNDS = Object.freeze({
+    bytes: 16 * 1024 * 1024,
+    heads: 10000,
+    headsPerPage: 1000,
+    // Even maximally escaped legal keys and MIME values in a full page fit within this bound.
+    headsPageBytes: 4 * 1024 * 1024,
+    cursorChars: 1024,
+});
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const only = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+const whole = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+function head(value) {
+    try {
+        return captureBlobHead(value);
+    }
+    catch (error) {
+        throw malformed(error instanceof Error ? error.message : "malformed blob head");
+    }
+}
+function tooLarge(maximum) {
+    return new HostedCarrierError("unavailable", { cause: new HostedAnswerTooLarge(maximum) });
+}
+export function createHostedBlobReadAdapter(options) {
+    const { carrier, bundleId, signal, capabilities } = options;
+    const prefix = options.prefix ?? "/sync/v1";
+    const headsRoute = `${prefix}/blob-heads`, readRoute = `${prefix}/blob-read`;
+    const assertOpen = () => { if (signal.aborted)
+        throw new HostedCarrierError("unavailable"); };
+    /** Race even caller-supplied ports: abort must not depend on their cooperation. */
+    function active(work, discard) {
+        assertOpen();
+        return new Promise((resolve, reject) => {
+            const aborted = () => reject(new HostedCarrierError("unavailable"));
+            signal.addEventListener("abort", aborted, { once: true });
+            Promise.resolve().then(() => { assertOpen(); return work(); }).then(value => {
+                if (signal.aborted) {
+                    discard?.(value);
+                    aborted();
+                }
+                else
+                    resolve(value);
+            }, reject).finally(() => signal.removeEventListener("abort", aborted));
+        });
+    }
+    async function admitted() {
+        const caps = await active(capabilities);
+        assertOpen();
+        if (caps.blobReads !== "allowed" || !Number.isSafeInteger(caps.blobReadBytes) || !(caps.blobReadBytes > 0))
+            throw new HostedReadAdapterError("unsupported");
+        return Math.min(caps.blobReadBytes, HOSTED_BLOB_READ_BOUNDS.bytes);
+    }
+    function carrierFailure(error) {
+        if (error instanceof HostedCarrierError && error.code === "denied")
+            throw new RemoteError("no credential for the host", "AUTH_REQUIRED", 401, error);
+        throw error;
+    }
+    async function listing() {
+        const heads = [], cursors = new Set();
+        let cursor, revision, digest, total;
+        for (;;) {
+            const answer = await active(() => carrier.json(headsRoute, { bundleId, ...(cursor === undefined ? {} : { cursor }) }, signal, { maximum: HOSTED_BLOB_READ_BOUNDS.headsPageBytes })).catch(carrierFailure);
+            assertOpen();
+            if (answer.status !== 200)
+                throw readRefusal(answer);
+            const page = answer.body;
+            if (!record(page) || !only(page, ["schemaVersion", "bundleId", "revision", "digest", "total", "heads", "next"]) ||
+                page.schemaVersion !== 1 || page.bundleId !== bundleId || !whole(page.revision) || !isContentVersion(page.digest) ||
+                !whole(page.total) || page.total > HOSTED_BLOB_READ_BOUNDS.heads || !Array.isArray(page.heads) || page.heads.length > HOSTED_BLOB_READ_BOUNDS.headsPerPage ||
+                !(page.next === null || typeof page.next === "string" && page.next.length > 0 && page.next.length <= HOSTED_BLOB_READ_BOUNDS.cursorChars))
+                throw malformed("malformed blob heads page");
+            if (revision !== undefined && (revision !== page.revision || digest !== page.digest || total !== page.total))
+                throw malformed("mixed blob heads pages");
+            revision = page.revision;
+            digest = page.digest;
+            total = page.total;
+            for (const raw of page.heads) {
+                const entry = head(raw), previous = heads.at(-1);
+                if (previous && compareStorageKeys(previous.key, entry.key) >= 0)
+                    throw malformed("blob heads are not strictly ordered");
+                heads.push(entry);
+            }
+            if (heads.length > total || page.heads.length === 0 && (total !== 0 || cursor !== undefined || page.next !== null))
+                throw malformed("blob heads page made no progress");
+            if (page.next === null) {
+                if (heads.length !== total || digest !== `sha256:${sha256HexOfUtf8(JSON.stringify([revision, heads.map(entry => [entry.key, entry.version, entry.contentType])]))}`)
+                    throw malformed("blob heads count or digest mismatch");
+                return Object.freeze({ bundleId, revision, digest, heads: Object.freeze(heads) });
+            }
+            if (heads.length >= total || cursors.has(page.next))
+                throw malformed("blob heads cursor made no progress");
+            cursors.add(page.next);
+            cursor = page.next;
+        }
+    }
+    return {
+        async heads() {
+            await admitted();
+            return onRoute(headsRoute, async () => {
+                for (let attempt = 1;; attempt += 1) {
+                    try {
+                        return await listing();
+                    }
+                    catch (error) {
+                        if (attempt >= HEADS_PAGE_ATTEMPTS || !isPageRestart(error))
+                            throw error;
+                        await active(() => (options.sleep ?? pause)(pageRestartDelay(attempt), signal));
+                    }
+                }
+            });
+        },
+        async read(pin) {
+            // Copy before any await so caller mutation cannot change the request or its expectations.
+            const expected = head(pin);
+            const maximum = await admitted();
+            return onRoute(readRoute, async () => {
+                // An uncooperative port may answer after abort. It still must not leave an open body.
+                const answer = await active(() => carrier.stream(readRoute, { bundleId, ...expected }, signal), answer => {
+                    if (answer.ok)
+                        void answer.body.cancel().catch(() => { });
+                }).catch(carrierFailure);
+                if (!answer.ok)
+                    throw readRefusal(answer);
+                const reader = answer.body.getReader();
+                let complete = false;
+                const cancel = () => { void reader.cancel().catch(() => { }); };
+                signal.addEventListener("abort", cancel, { once: true });
+                try {
+                    assertOpen();
+                    const lengthText = answer.headers.get("content-length");
+                    if (answer.status !== 200 || answer.headers.get("content-type") !== "application/octet-stream" ||
+                        answer.headers.get("x-superbee-blob-version") !== expected.version || answer.headers.get("x-superbee-content-type") !== expected.contentType ||
+                        lengthText === null || !/^(0|[1-9][0-9]*)$/.test(lengthText) || !whole(Number(lengthText)))
+                        throw malformed("blob read headers do not match the pin");
+                    const length = Number(lengthText);
+                    if (length > maximum)
+                        throw tooLarge(maximum);
+                    const bytes = new Uint8Array(length);
+                    let offset = 0;
+                    for (;;) {
+                        const chunk = await active(() => reader.read());
+                        assertOpen();
+                        if (chunk.done)
+                            break;
+                        if (!(chunk.value instanceof Uint8Array))
+                            throw malformed("blob read yielded non-byte content");
+                        if (chunk.value.byteLength > maximum - offset)
+                            throw tooLarge(maximum);
+                        if (chunk.value.byteLength > length - offset)
+                            throw malformed("blob read exceeded its stated length");
+                        bytes.set(chunk.value, offset);
+                        offset += chunk.value.byteLength;
+                    }
+                    if (offset !== length || `sha256:${sha256HexOfBytes(bytes)}` !== expected.version)
+                        throw malformed("blob read length or digest mismatch");
+                    complete = true;
+                    return Object.freeze({ ...expected, bytes });
+                }
+                finally {
+                    signal.removeEventListener("abort", cancel);
+                    if (!complete)
+                        cancel();
+                    reader.releaseLock();
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=blob-reads.js.map

package/dist/hosted-transport/blob-reads.js.map

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

package/dist/hosted-transport/blob-write.d.ts

@@ -0,0 +1,34 @@
+import { type HostedCarrier } from "./carrier.js";
+import { type BlobWriteExpected, type BlobWriteResult, type BlobOutcomeAnswer, type UpdateAnswerRow } from "./answer-rows.js";
+import { type HostedCapabilities } from "./read-adapter.js";
+export interface HostedBlobWriteIdentity {
+    readonly requestId: string;
+    readonly binding: string;
+    readonly via?: string;
+    /** A person's confirmation of the deletion count; admission only, sent on delete, never lookup. */
+    readonly acceptDeletes?: number;
+}
+export interface BlobSendAnswer {
+    /** Null when the carrier failed or the call was aborted without usable answer evidence. */
+    readonly status: number | null;
+    readonly row: UpdateAnswerRow;
+    readonly result?: BlobWriteResult;
+    /** An exact request-id marker accompanying valid terminal evidence that its row admits.
+     * False does not override the row: successful/recorded rows retain their original meaning. */
+    readonly settled: boolean;
+}
+export interface HostedBlobWriteAdapterOptions {
+    readonly carrier: HostedCarrier;
+    /** Bare portable bundle id. A supplied scoped carrier owns workspace qualification. */
+    readonly bundleId: string;
+    readonly prefix?: string;
+    readonly signal: AbortSignal;
+    readonly capabilities: () => Promise<HostedCapabilities>;
+}
+export interface HostedBlobWriteAdapter {
+    send(intent: BlobWriteExpected, identity: HostedBlobWriteIdentity, bytes?: Uint8Array): Promise<BlobSendAnswer>;
+    /** Returns explicit absence, never null or resend permission. Failed evidence rejects. */
+    lookup(intent: BlobWriteExpected, identity: HostedBlobWriteIdentity): Promise<BlobOutcomeAnswer>;
+}
+export declare function createHostedBlobWriteAdapter(options: HostedBlobWriteAdapterOptions): HostedBlobWriteAdapter;
+//# sourceMappingURL=blob-write.d.ts.map

package/dist/hosted-transport/blob-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-write.d.ts","sourceRoot":"","sources":["../../src/hosted-transport/blob-write.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAC3F,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEpF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AACD,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;kGAC8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AACD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC1D;AACD,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,uBAAuB,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAChH,0FAA0F;IAC1F,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAClG;AAmBD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,6BAA6B,GAAG,sBAAsB,CAgE3G"}

package/dist/hosted-transport/blob-write.js

@@ -0,0 +1,115 @@
+/** One identified blob delivery or outcome lookup through the caller's carrier. This wire
+ * adapter preserves typed evidence; it never resends, reads a current head, or interprets an
+ * absent outcome as permission to deliver again. Client journaling and recovery live elsewhere. */
+import { captureBlobWriteExpected, encodeBlobKey } from "../blob-contract.js";
+import { isWriteRequestId } from "../write-identity.js";
+import { isHostedBundleId } from "../dependencies.js";
+import { isContentVersion } from "../version-transport.js";
+import { sha256HexOfBytes } from "../sha256.js";
+import { isAgentLabelVia, isAcceptedDeletionCount, HostedCarrierError, } from "./carrier.js";
+import { classifyBlobWriteAnswer, decodeBlobOutcomeAnswer, HostedOutcomeError, updateRow, } from "./answer-rows.js";
+import { HostedReadAdapterError } from "./read-adapter.js";
+const MAXIMUM_BLOB_BYTES = 16 * 1024 * 1024;
+const ANSWER_BYTES = 64 * 1024;
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const only = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+function snapshot(intent, identity) {
+    if (!record(intent) || !record(identity))
+        throw new TypeError("blob intent and identity must be objects");
+    const copied = { ...intent }, id = { ...identity };
+    const deletion = copied.operationId === "blobs.delete.v1";
+    captureBlobWriteExpected(copied);
+    if (!only(id, ["requestId", "binding", "via", "acceptDeletes"]) || typeof id.requestId !== "string" || !isWriteRequestId(id.requestId) || !isContentVersion(id.binding) ||
+        id.via !== undefined && !isAgentLabelVia(id.via) || id.acceptDeletes !== undefined && (!deletion || !isAcceptedDeletionCount(id.acceptDeletes)))
+        throw new TypeError("invalid blob write identity");
+    return { intent: Object.freeze(copied), identity: Object.freeze(id), keyHeader: encodeBlobKey(copied.key) };
+}
+function immutable(result) {
+    Object.freeze(result.ok ? result.data : result.error);
+    return Object.freeze(result);
+}
+export function createHostedBlobWriteAdapter(options) {
+    const { carrier, bundleId, signal, capabilities } = options;
+    const prefix = options.prefix ?? "/sync/v1";
+    if (typeof bundleId !== "string" || !isHostedBundleId(bundleId))
+        throw new TypeError("a bare hosted bundle id is required");
+    const assertOpen = () => { if (signal.aborted)
+        throw new HostedCarrierError("unavailable"); };
+    function active(work) {
+        assertOpen();
+        return new Promise((resolve, reject) => {
+            const abort = () => reject(new HostedCarrierError("unavailable"));
+            signal.addEventListener("abort", abort, { once: true });
+            Promise.resolve().then(() => { assertOpen(); return work(); }).then(value => {
+                if (signal.aborted)
+                    abort();
+                else
+                    resolve(value);
+            }, reject).finally(() => signal.removeEventListener("abort", abort));
+        });
+    }
+    async function admitted() {
+        const caps = await active(capabilities);
+        assertOpen();
+        if (caps.blobWrites !== "allowed" || !Number.isSafeInteger(caps.blobWriteBytes) || !(caps.blobWriteBytes > 0))
+            throw new HostedReadAdapterError("unsupported");
+        return Math.min(caps.blobWriteBytes, MAXIMUM_BLOB_BYTES);
+    }
+    const headers = (id, deletion = false) => ({ maximum: ANSWER_BYTES, writeRequest: id.requestId, binding: id.binding, ...(id.via === undefined ? {} : { via: id.via }), ...(deletion && id.acceptDeletes !== undefined ? { acceptDeletes: id.acceptDeletes } : {}) });
+    return {
+        async send(rawIntent, rawIdentity, rawBytes) {
+            const { intent, identity, keyHeader } = snapshot(rawIntent, rawIdentity);
+            const deletion = intent.operationId === "blobs.delete.v1";
+            if (deletion ? rawBytes !== undefined : !(rawBytes instanceof Uint8Array))
+                throw new TypeError("only blob create/replace carry bytes");
+            if (rawBytes && rawBytes.byteLength > MAXIMUM_BLOB_BYTES)
+                throw new TypeError("blob bytes exceed the write bound");
+            const bytes = rawBytes === undefined ? undefined : new Uint8Array(rawBytes);
+            if (bytes && (bytes.byteLength > MAXIMUM_BLOB_BYTES || intent.operationId === "blobs.delete.v1" || `sha256:${sha256HexOfBytes(bytes)}` !== intent.version))
+                throw new TypeError("blob bytes do not match the retained digest or bound");
+            const maximum = await admitted();
+            if (bytes && bytes.byteLength > maximum)
+                throw new TypeError("blob bytes exceed the advertised write bound");
+            if (!deletion && !carrier.bytes)
+                throw new HostedReadAdapterError("unsupported");
+            try {
+                const answer = await active(() => {
+                    if (intent.operationId === "blobs.delete.v1")
+                        return carrier.json(`${prefix}/blob-delete`, { bundleId, ...intent }, signal, headers(identity, true));
+                    return carrier.bytes(`${prefix}/${intent.operationId === "blobs.create.v1" ? "blob-create" : "blob-replace"}`, bytes, signal, {
+                        ...headers(identity), headers: {
+                            "X-Superbee-Bundle": bundleId, "X-Superbee-Blob-Key": keyHeader,
+                            "X-Superbee-Blob-Version": intent.version, "X-Superbee-Content-Type": intent.contentType,
+                            ...(intent.operationId === "blobs.create.v1" ? {} : { "X-Superbee-Expected-Version": intent.expectedVersion, "X-Superbee-Expected-Content-Type": intent.expectedContentType }),
+                        },
+                    });
+                });
+                const { row, result } = classifyBlobWriteAnswer(answer, intent);
+                const settled = answer.headers.get("X-Superbee-Write-Settled") === identity.requestId && result !== undefined &&
+                    (row.recorded === "yes" || row.recorded === "settled-only") && (result.ok || result.error.writeState === "not_applied");
+                return Object.freeze({ status: answer.status, row, ...(result === undefined ? {} : { result: immutable(result) }), settled });
+            }
+            catch {
+                return Object.freeze({ status: null, row: updateRow("carrier"), settled: false });
+            }
+        },
+        async lookup(rawIntent, rawIdentity) {
+            const { intent, identity } = snapshot(rawIntent, rawIdentity);
+            await admitted();
+            let answer;
+            try {
+                answer = await active(() => carrier.json(`${prefix}/outcome`, { bundleId, ...intent }, signal, headers(identity)));
+            }
+            catch {
+                throw new HostedOutcomeError("unavailable");
+            }
+            if (answer.status !== 200)
+                throw new HostedOutcomeError("refused", answer.status);
+            const decoded = decodeBlobOutcomeAnswer(answer.body, { ...intent, requestId: identity.requestId, binding: identity.binding });
+            if (decoded.status !== "absent")
+                immutable(decoded.result);
+            return Object.freeze(decoded);
+        },
+    };
+}
+//# sourceMappingURL=blob-write.js.map

package/dist/hosted-transport/blob-write.js.map

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

package/dist/hosted-transport/carrier.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The carrier seam: how a hosted request leaves and what comes back, with the credential kept on
+ * the carrier's side. The browser's carrier sends the session cookie and CSRF token; the CLI's
+ * sends a bearer token. Everything above the seam (the read adapter, the whole-document
+ * transport, the answer rows) is the same for both, so one answer grammar serves every client.
+ *
+ * A carrier reports two failures and never a third: `denied` says nothing left (the credential
+ * was already gone, so the request was never sent), and `unavailable` says the request may have
+ * left and its answer is unknown. It never reports "not applied" on its own.
+ */
+/** A hosted answer as the route sent it: the status, the headers, and the bounded JSON body (undefined when there is none). */
+export type HostedAnswer = {
+    status: number;
+    headers: Headers;
+    body: unknown;
+};
+/** A streamed answer: the body as a stream for a `2xx`, otherwise the bounded refusal envelope. */
+export type HostedStream = {
+    status: number;
+    headers: Headers;
+} & ({
+    ok: true;
+    body: ReadableStream<Uint8Array>;
+} | {
+    ok: false;
+    body: unknown;
+});
+export interface HostedRequestOptions {
+    /** Largest answer body admitted, in bytes; a larger or undecodable body is `unavailable`. */
+    maximum: number;
+    /** The request identity of an identified write or its outcome lookup. */
+    writeRequest?: string;
+    /**
+     * The binding the request is pinned to: the browser's editor recovery target, or the CLI
+     * checkout's digest. The carrier decides which header carries it.
+     */
+    binding?: string;
+    /**
+     * The tombstone a create acknowledges it re-creates (`X-Superbee-Recreate`), on a create and
+     * on that create's outcome lookup only. It is part of the request identity on the host, so a
+     * lookup must carry exactly what the write carried.
+     */
+    recreate?: string;
+    /**
+     * The agent the client runs under, such as `claude-code` (`X-Superbee-Via`): the unverified
+     * `;via=` part of the host's agent label for this write. Attribution only, never authority, and
+     * not part of the request identity. Only an identified write and its outcome lookup carry it,
+     * and only a token {@link isAgentLabelVia} admits is ever sent.
+     */
+    via?: string;
+    /**
+     * A person's typed acknowledgment of the host's mass-delete hold (`X-Superbee-Accept-Deletes`):
+     * the deletions they confirmed the bundle's 24-hour window may hold, from 1 to 100,000. Sent on
+     * a delete only, and never without that confirmation. Admission only, not part of the request
+     * identity.
+     */
+    acceptDeletes?: number;
+    /**
+     * The workspace (tenant id, such as `tenant:holaxis`) a workspace-scoped route acts in
+     * (`Superbee-Workspace`), for the attention routes, whose admission spans every workspace the
+     * person is in. Admission only. A value that is not a tenant id is refused before sending.
+     */
+    workspace?: string;
+}
+/** The header that carries {@link HostedRequestOptions.workspace}. */
+export declare const WORKSPACE_HEADER = "Superbee-Workspace";
+/** Whether `value` has the shape of a tenant id the workspace header may carry. */
+export declare function isWorkspaceTenantId(value: unknown): value is string;
+/** The header that carries {@link HostedRequestOptions.acceptDeletes}. */
+export declare const ACCEPT_DELETES_HEADER = "X-Superbee-Accept-Deletes";
+/** The largest acknowledgment the host admits. */
+export declare const MAXIMUM_ACCEPTED_DELETIONS = 100000;
+/** Whether `value` is an acknowledgment count the host admits: an integer from 1 to 100,000. */
+export declare function isAcceptedDeletionCount(value: unknown): value is number;
+/** The header that carries {@link HostedRequestOptions.recreate}. */
+export declare const RECREATE_HEADER = "X-Superbee-Recreate";
+/** The header that carries {@link HostedRequestOptions.via}. */
+export declare 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";
+/**
+ * A raw-bytes request ({@link HostedCarrier.bytes}), such as one blob of a staged bundle creation
+ * (`bundle-create-blob`): the body travels as `application/octet-stream` with its exact
+ * `Content-Length`, and the route's own fields travel as headers. The request identity, the
+ * binding and `via` are a JSON request's own ({@link HostedRequestOptions}): the same headers,
+ * refused before sending by the same rules, so an identified raw write is identified as a document
+ * write is.
+ */
+export interface HostedBytesRequestOptions extends Pick<HostedRequestOptions, "maximum" | "writeRequest" | "binding" | "via"> {
+    /**
+     * The route's own fields (`X-Superbee-Workspace`, say): `X-Superbee-` names only, and never a
+     * header the carrier owns (the request identity, the binding, `recreate`, `via`, the deletion
+     * acknowledgment) or a credential. Values are printable ASCII.
+     */
+    headers?: Readonly<Record<string, string>>;
+}
+export interface HostedCarrier {
+    json(path: string, input: unknown, signal: AbortSignal, options: HostedRequestOptions): Promise<HostedAnswer>;
+    stream(path: string, input: unknown, signal: AbortSignal): Promise<HostedStream>;
+    /**
+     * One `POST` whose body is `body` exactly, answered as {@link json} answers. Optional: a carrier
+     * without it (the browser's) cannot send raw bytes, and a caller that needs them says so.
+     */
+    bytes?(path: string, body: Uint8Array, signal: AbortSignal, options: HostedBytesRequestOptions): Promise<HostedAnswer>;
+}
+/**
+ * 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 declare class HostedAnswerTooLarge extends Error {
+    readonly name = "HostedAnswerTooLarge";
+    readonly maximum: number;
+    constructor(maximum: number);
+}
+/** True when `error` is a carrier failure because the answer exceeded its bound. */
+export declare function isAnswerTooLarge(error: unknown): boolean;
+export declare class HostedCarrierError extends Error {
+    readonly name = "HostedCarrierError";
+    readonly code: "denied" | "unavailable";
+    constructor(code: "denied" | "unavailable", options?: {
+        cause?: unknown;
+    });
+}
+export interface FetchCarrierOptions {
+    /** The host's origin, e.g. `https://superbee.example`; paths are resolved against it. */
+    baseUrl: string;
+    /**
+     * The credential headers for one request, such as `{ Authorization: "Bearer …" }`. A rejection
+     * means no credential is available: the request is not sent and the carrier reports `denied`.
+     */
+    credentials(signal: AbortSignal): Promise<Record<string, string>>;
+    /** The header that carries `binding`. Default `X-Superbee-Checkout`. */
+    bindingHeader?: string;
+    fetch?: typeof fetch;
+    /** Every request is answered within this many milliseconds; a stream restarts it at each chunk. Default 15 s. */
+    deadlineMs?: number;
+}
+/**
+ * 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 declare function createFetchCarrier(options: FetchCarrierOptions): HostedCarrier;
+//# sourceMappingURL=carrier.d.ts.map

package/dist/hosted-transport/carrier.d.ts.map

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