@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.149

package/dist/transport/relay-close.js

@@ -0,0 +1,23 @@
+/** Bounded transport observations only: never admission, authority or raw close text. */
+const classes = {
+    1000: "normal", 1001: "going_away", 1002: "protocol_error", 1003: "unsupported_data",
+    1005: "no_status", 1006: "abnormal", 1007: "invalid_payload", 1008: "policy_violation",
+    1009: "message_too_big", 1010: "extension_required", 1011: "internal_error",
+    1012: "service_restart", 1013: "try_again_later", 1014: "bad_gateway", 1015: "tls_failure",
+    4000: "pipe_closed", 4401: "unauthenticated", 4403: "grant_inactive",
+    4404: "connector_offline", 4429: "connector_busy",
+};
+export function relayCloseDiagnostic(code) {
+    const closeCode = typeof code === "number" && Number.isInteger(code) && code >= 1000 && code <= 4999 ? code : null;
+    return Object.freeze({ closeCode, closeClass: closeCode === null ? "unknown" : classes[closeCode] ?? "other" });
+}
+/** Reconstruct only our bounded fields; arbitrary map values never reach snapshots. */
+export function relayCloseFromDetails(details) {
+    try {
+        if (details instanceof Map && details.has("relayCloseCode"))
+            return relayCloseDiagnostic(details.get("relayCloseCode"));
+    }
+    catch { /* Untrusted adapter details are not diagnostics. */ }
+    return undefined;
+}
+//# sourceMappingURL=relay-close.js.map

package/dist/transport/relay-close.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-close.js","sourceRoot":"","sources":["../../src/transport/relay-close.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,MAAM,OAAO,GAAG;IACd,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,kBAAkB;IACpF,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,kBAAkB;IACtF,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,gBAAgB;IAC3E,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa;IAC1F,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,gBAAgB;IACpE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,gBAAgB;CACzC,CAAC;AAOX,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,MAAM,SAAS,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACnH,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAiC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AAC1I,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,IAAI,CAAC;QACH,IAAI,OAAO,YAAY,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YAAE,OAAO,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC1H,CAAC;IAAC,MAAM,CAAC,CAAC,oDAAoD,CAAC,CAAC;IAChE,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/transport/relay-pipe.d.ts

@@ -0,0 +1,15 @@
+import { MdbaseError } from "../errors.js";
+import type { MessageCarrier, WebSocketFactory } from "./noise-session.js";
+export interface PipeAuth {
+    /** The app's Connect access token. */
+    accessToken: string;
+    /** The relay's (Connect's local) collection ID. */
+    collection: string;
+    grant: string;
+    /** Target device and its Noise key, as the routing endpoint returned them. */
+    device: string;
+    devicePublicKey: Uint8Array;
+}
+export declare function pipeCloseError(code?: number, reason?: string): MdbaseError;
+/** Open a relay pipe and return a carrier of whole Noise messages. */
+export declare function relayPipeCarrier(url: string, auth: PipeAuth, factory?: WebSocketFactory, signal?: AbortSignal): Promise<MessageCarrier>;

package/dist/transport/relay-pipe.js

@@ -0,0 +1,190 @@
+/**
+ * The relay's Noise pipe for thin clients (Connect `GET /v1/next/relay/client`,
+ * Connect #596):
+ *
+ * 1. Open the WebSocket. Browsers can't set headers, so the first **text** frame is
+ *    `{type: "pipe_auth", access_token, collection, grant, device, device_noise_pk}`.
+ * 2. Wait for `{type: "pipe_opened", pipe_id}` before sending any binary frame.
+ * 3. Binary frames then carry the §12.3 stream: `u32be(len) ‖ Noise message`, at most
+ *    65,539 bytes per frame. The relay forwards them opaquely. Authorization is the
+ *    replica's (Noise IK with the grant's `client_pk`); relay admission is a filter.
+ * 4. `{type: "pipe_close", pipe_id, reason}` or a close code ends the pipe.
+ *
+ * Close codes → the 15 codes: 4401 → `unauthenticated`; 4403 (`grant_inactive`) →
+ * `forbidden`; 4404 (`connector_offline`: no bound daemon) → `unavailable` /
+ * `no_device_online`; 4429 (`connector_busy`) → `rate_limited`; 4000 with
+ * `device_key_mismatch` → `unauthenticated` (the routed key isn't the device's; never
+ * retried blindly); other 4000 reasons → `unavailable` with that reason.
+ */
+import { LOCAL_APPLICATION_BUILD, localApplicationWebSocketUrl } from "../local-build.js";
+import { mdbaseError } from "../errors.js";
+import { relayCloseDiagnostic } from "./relay-close.js";
+import { toHex } from "../cbor.js";
+/** Max binary frame: u32be length + one Noise message. */
+const MAX_PIPE_FRAME = 4 + 65535;
+const CLOSE_REASONS = new Set("unauthenticated grant_inactive connector_offline connector_busy device_mismatch device_key_mismatch closed client_closed handshake_timeout idle lifetime frame_too_large invalid_frame not_served relay_closing authorization_unavailable grant_revoked".split(" "));
+export function pipeCloseError(code, reason) {
+    // Only fixed protocol reasons survive: arbitrary close text can contain secrets.
+    const r = typeof reason === "string" && CLOSE_REASONS.has(reason) ? reason : undefined;
+    const close = relayCloseDiagnostic(code);
+    const details = new Map([["relayCloseCode", close.closeCode], ["relayCloseClass", close.closeClass]]);
+    const error = (c, message, why, retryAfterMs) => mdbaseError(c, message, { reason: why, details, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) });
+    switch (close.closeCode) {
+        case 4401:
+            return error("unauthenticated", r ?? "relay: unauthenticated", "relay_unauthenticated");
+        case 4403:
+            return error("forbidden", r ?? "relay: grant inactive", r ?? "grant_inactive");
+        case 4404:
+            if (r)
+                details.set("relay", r);
+            return error("unavailable", "no device of this collection is online", "no_device_online");
+        case 4429:
+            return error("rate_limited", r ?? "relay: busy", r ?? "connector_busy", 5000);
+        case 4000:
+            if (r === "device_key_mismatch")
+                return error("unauthenticated", "relay: the routed key is not the device's", r);
+            return error("unavailable", `relay closed the pipe: ${r ?? "unknown"}`, r ?? "pipe_closed");
+        default:
+            return error("unavailable", `relay connection closed${close.closeCode === null ? "" : ` (${close.closeCode})`}`, "relay_closed");
+    }
+}
+function defaultWs(url) {
+    const Ws = globalThis.WebSocket;
+    if (!Ws)
+        throw mdbaseError("unavailable", "no WebSocket implementation; pass webSocket");
+    return new Ws(url);
+}
+/** Open a relay pipe and return a carrier of whole Noise messages. */
+export function relayPipeCarrier(url, auth, factory = defaultWs, signal) {
+    // The access token travels in the first frame: never over plaintext.
+    let scheme = "";
+    try {
+        scheme = new URL(url).protocol;
+    }
+    catch {
+        return Promise.reject(mdbaseError("invalid_request", `invalid relay URL ${url}`, "relay_url"));
+    }
+    if (scheme !== "wss:" && !(LOCAL_APPLICATION_BUILD && localApplicationWebSocketUrl(url))) {
+        return Promise.reject(mdbaseError("invalid_request", "relay pipes require wss:", "relay_insecure"));
+    }
+    if (!auth.grant) {
+        return Promise.reject(mdbaseError("invalid_request", "relay pipes require a grant", "grant_required"));
+    }
+    return new Promise((resolve, reject) => {
+        let ws;
+        try {
+            ws = factory(url);
+        }
+        catch (e) {
+            reject(mdbaseError("unavailable", `cannot open ${url}: ${String(e)}`));
+            return;
+        }
+        ws.binaryType = "arraybuffer";
+        let opened = false;
+        let settled = false;
+        let buf = new Uint8Array(0);
+        const carrier = {
+            onmessage: null,
+            onclose: null,
+            send(m) {
+                if (m.length > 65535)
+                    throw mdbaseError("too_large", "Noise message over 65535 bytes");
+                const f = new Uint8Array(4 + m.length);
+                new DataView(f.buffer).setUint32(0, m.length);
+                f.set(m, 4);
+                ws.send(f);
+            },
+            close() {
+                try {
+                    ws.close(1000);
+                }
+                catch {
+                    // closed
+                }
+            },
+        };
+        const fail = (e) => {
+            if (!settled) {
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                reject(e);
+            }
+            else
+                carrier.onclose?.(e);
+        };
+        const onAbort = () => {
+            ws.close();
+            fail(mdbaseError("cancelled", "connect aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        ws.onopen = () => {
+            // A text frame: the credential never goes in the URL.
+            ws.send(JSON.stringify({
+                type: "pipe_auth",
+                access_token: auth.accessToken,
+                collection: auth.collection,
+                grant: auth.grant,
+                device: auth.device,
+                device_noise_pk: toHex(auth.devicePublicKey),
+            }));
+        };
+        ws.onmessage = (ev) => {
+            const d = ev.data;
+            if (typeof d === "string") {
+                let msg;
+                try {
+                    msg = JSON.parse(d);
+                }
+                catch {
+                    return;
+                }
+                if (msg.type === "pipe_opened" && !opened) {
+                    opened = true;
+                    settled = true;
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve(carrier);
+                }
+                else if (msg.type === "pipe_close") {
+                    ws.close();
+                    fail(pipeCloseError(4000, msg.reason));
+                }
+                return;
+            }
+            if (!opened)
+                return; // binary before pipe_opened: not part of the protocol
+            const chunk = d instanceof ArrayBuffer
+                ? new Uint8Array(d)
+                : ArrayBuffer.isView(d)
+                    ? new Uint8Array(d.buffer, d.byteOffset, d.byteLength)
+                    : null;
+            if (!chunk)
+                return;
+            if (chunk.length > MAX_PIPE_FRAME) {
+                ws.close();
+                fail(mdbaseError("too_large", "relay frame over the limit"));
+                return;
+            }
+            // Tolerate a relay that re-chunks: parse u32be-prefixed messages from a stream.
+            const b = new Uint8Array(buf.length + chunk.length);
+            b.set(buf);
+            b.set(chunk, buf.length);
+            let off = 0;
+            while (b.length - off >= 4) {
+                const len = new DataView(b.buffer, b.byteOffset + off, 4).getUint32(0);
+                if (len > 65535) {
+                    ws.close();
+                    fail(mdbaseError("internal", "relay sent an oversized Noise message"));
+                    return;
+                }
+                if (b.length - off - 4 < len)
+                    break;
+                carrier.onmessage?.(b.slice(off + 4, off + 4 + len));
+                off += 4 + len;
+            }
+            buf = b.slice(off);
+        };
+        ws.onerror = () => { };
+        ws.onclose = (ev) => fail(pipeCloseError(ev.code, ev.reason));
+    });
+}
+//# sourceMappingURL=relay-pipe.js.map

package/dist/transport/relay-pipe.js.map

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

package/dist/transport/relay.d.ts

@@ -0,0 +1,36 @@
+import type { Uuid } from "../wire.js";
+import { KeyPair, StaticKey } from "./noise.js";
+import { WebSocketFactory } from "./noise-session.js";
+import type { Connector } from "./port.js";
+export interface RelayRoute {
+    /** WebSocket URL that reaches this target (relay session URL or the hosted replica). */
+    url: string;
+    /** The target replica's device ID. */
+    targetDevice: Uuid;
+    /** The target's enrolled Noise public key (32 bytes). */
+    noisePublicKey: Uint8Array;
+    /**
+     * Set for the relay's Noise pipe (`/v1/next/relay/client`): the relay's
+     * collection ID and the app's access token, sent in the first text frame. Absent for
+     * a direct WebSocket to the hosted replica (one Noise message per WS message).
+     */
+    pipe?: {
+        collection: string;
+        accessToken: string;
+    };
+}
+export interface RelayConnectorOptions {
+    collection: Uuid;
+    /** The grant this client holds (absent only for a hosting app). */
+    grant: Uuid | null;
+    /** The grant's client key (`client_pk`); in browsers a non-extractable WebCrypto key. */
+    staticKey: KeyPair | StaticKey;
+    /**
+     * Where to connect now. Return `null` when no target is reachable: for a private
+     * collection that means none of the user's devices is online.
+     */
+    resolveRoute: () => Promise<RelayRoute | null>;
+    webSocket?: WebSocketFactory;
+}
+/** A connector for web apps and other remote clients. */
+export declare function relayConnector(o: RelayConnectorOptions): Connector;

package/dist/transport/relay.js

@@ -0,0 +1,45 @@
+/**
+ * Remote thin clients: a Noise IK session through mdbase's relay, or straight to the
+ * hosted replica over a WebSocket (`replica-client-api.md` §12.3).
+ *
+ * The control plane's routing endpoint lists the targets for a collection: online
+ * device replicas (private collections) or the hosted replica (cloud copy), each with
+ * its device ID and Noise public key. How that endpoint is called, and the relay URL
+ * format, belong to the control workstream; this module takes a `resolveRoute`
+ * callback so they can change without touching the session code.
+ */
+import { uuidToBytes } from "../codec.js";
+import { mdbaseError } from "../errors.js";
+import { clientPrologue } from "./noise.js";
+import { noiseConnector, webSocketCarrier } from "./noise-session.js";
+import { relayPipeCarrier } from "./relay-pipe.js";
+/** A connector for web apps and other remote clients. */
+export function relayConnector(o) {
+    const collection = uuidToBytes(o.collection);
+    const grant = o.grant ? uuidToBytes(o.grant) : null;
+    return noiseConnector({
+        description: `relay:${o.collection}`,
+        staticKey: o.staticKey,
+        target: async () => {
+            const route = await o.resolveRoute();
+            if (!route) {
+                throw mdbaseError("unavailable", "no device of this collection is online", "no_device_online");
+            }
+            return {
+                prologue: clientPrologue(collection, grant, uuidToBytes(route.targetDevice)),
+                remoteStatic: route.noisePublicKey,
+                device: route.targetDevice,
+                openCarrier: (signal) => route.pipe
+                    ? relayPipeCarrier(route.url, {
+                        accessToken: route.pipe.accessToken,
+                        collection: route.pipe.collection,
+                        grant: o.grant ?? "",
+                        device: route.targetDevice,
+                        devicePublicKey: route.noisePublicKey,
+                    }, o.webSocket, signal)
+                    : webSocketCarrier(route.url, o.webSocket, signal),
+            };
+        },
+    });
+}
+//# sourceMappingURL=relay.js.map

package/dist/transport/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../src/transport/relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAoB,MAAM,oBAAoB,CAAC;AAExF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AA+BnD,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,CAAwB;IACrD,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,OAAO,cAAc,CAAC;QACpB,WAAW,EAAE,SAAS,CAAC,CAAC,UAAU,EAAE;QACpC,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,MAAM,EAAE,KAAK,IAAI,EAAE;YACjB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,YAAY,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,WAAW,CAAC,aAAa,EAAE,wCAAwC,EAAE,kBAAkB,CAAC,CAAC;YACjG,CAAC;YACD,OAAO;gBACL,QAAQ,EAAE,cAAc,CAAC,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;gBAC5E,YAAY,EAAE,KAAK,CAAC,cAAc;gBAClC,MAAM,EAAE,KAAK,CAAC,YAAY;gBAC1B,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CACtB,KAAK,CAAC,IAAI;oBACR,CAAC,CAAC,gBAAgB,CACd,KAAK,CAAC,GAAG,EACT;wBACE,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW;wBACnC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;wBACjC,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE;wBACpB,MAAM,EAAE,KAAK,CAAC,YAAY;wBAC1B,eAAe,EAAE,KAAK,CAAC,cAAc;qBACtC,EACD,CAAC,CAAC,SAAS,EACX,MAAM,CACP;oBACH,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC;aACvD,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/type-packs.d.ts

@@ -0,0 +1,124 @@
+/** Type packs: one reviewable plan, then one guarded all-or-nothing apply.
+ * The replica's Core plans; the SDK never diffs, merges or writes on its own. */
+import type { MdbaseClient, Write, WriteOptions } from "./client.js";
+/** A pack: its manifest and the exact bytes of every manifest source. */
+export interface TypePackProvision {
+    /** The parsed manifest (JSON data); Core validates it. */
+    manifest: object;
+    resources: readonly {
+        source: string;
+        document: string;
+    }[];
+    /** Accepted for compatibility; not used for planning. */
+    provides?: unknown;
+}
+/** The caller's decisions. Pass the same options to `plan` and `apply`. */
+export interface TypePackOptions {
+    /** Stable reverse-domain installer identity, e.g. `app.example.notes`. */
+    installedBy: string;
+    /** Reviewed adoptions: target → its exact current digest (see `plan.adoptable`). */
+    adopt?: Readonly<Record<string, string>>;
+    /** Canonical target → collection target. */
+    targetOverrides?: Readonly<Record<string, string>>;
+    /** Seed targets intentionally left out. */
+    preserveSeedTargets?: readonly string[];
+    /** Permit installing an older version than the installed one. */
+    allowDowngrade?: boolean;
+    signal?: AbortSignal;
+}
+export type TypePackAction = "create" | "update" | "delete" | "adopt" | "unchanged" | "preserve" | "conflict";
+export type TypePackResourceKind = "contract" | "type" | "schema";
+export type TypePackStatus = "install" | "upgrade" | "downgrade" | "reconfigure" | "current" | "conflict";
+/** One resource of the plan. `source` is empty for a retired resource with no lock entry. */
+export interface TypePackResource {
+    source: string;
+    target: string;
+    kind: TypePackResourceKind;
+    mode: "managed" | "seed";
+    action: TypePackAction;
+    digest?: string;
+    /** The live target's digest, when it exists. */
+    currentDigest?: string;
+    /** The digest the installed receipt records. */
+    installedDigest?: string;
+    /** The live digest an adoption took ownership of. */
+    adoptedFromDigest?: string;
+    /** Seed updates: the publisher baseline the update is based on. */
+    upgradeBaseline?: {
+        digest: string;
+        version?: number;
+    };
+    reason?: string;
+}
+export interface TypePackReceipt {
+    id: string;
+    version: string;
+    digest: string;
+    installedBy: string;
+    resources: {
+        source: string;
+        target: string;
+        kind: TypePackResourceKind;
+        mode: "managed" | "seed";
+        digest: string;
+        originDigest?: string;
+    }[];
+}
+/** Stable refusal codes; `message` is written to be shown as is. */
+export type TypePackRefusalCode = "forbidden" | "type_pack_conflict" | "type_pack_downgrade" | "invalid_type_pack" | "type_pack_contract_setups_unsupported";
+export interface TypePackConflict {
+    target: string;
+    kind: TypePackResourceKind;
+    reason?: string;
+    message: string;
+    /** Present when adopting the live target would resolve the conflict. */
+    adoptable?: {
+        digest: string;
+    };
+}
+/** One reviewable plan. Pass it to `typePacks.apply` unchanged. */
+export interface TypePackPlan {
+    readonly status: TypePackStatus;
+    readonly canApply: boolean;
+    /** Binds the pack, every relevant live target, the lock and the options. */
+    readonly digest: string;
+    /** Targets by action, for a diff. */
+    readonly summary: Readonly<Record<TypePackAction, readonly string[]>>;
+    readonly conflicts: readonly TypePackConflict[];
+    /** Conflicts adoption would resolve: pass as `adopt` and plan again. */
+    readonly adoptable: Readonly<Record<string, string>>;
+    readonly resources: readonly TypePackResource[];
+    readonly current?: TypePackReceipt;
+    readonly desired: TypePackReceipt;
+    readonly lock: {
+        target: string;
+        action: "create" | "update" | "unchanged";
+        digest: string;
+    };
+    readonly refusal?: {
+        code: TypePackRefusalCode;
+        message: string;
+    };
+}
+export interface TypePackApplyResult {
+    /** `applied`: the mutation is confirmed. `pending`: accepted locally and
+     * awaiting confirmation (`await write.confirmed`, which rejects with the
+     * original mutation's problem if it is later rejected). `preview`: a
+     * `dryRun`, nothing was installed. `already_current`: nothing to write. */
+    outcome: "applied" | "pending" | "preview" | "already_current";
+    receipt: TypePackReceipt;
+    /** The one mutation (or dry run), when anything was written. */
+    write?: Write;
+}
+/** Plan a type pack against the local collection. Writes nothing. */
+export declare function planTypePack(client: MdbaseClient, pack: TypePackProvision, options: TypePackOptions): Promise<TypePackPlan>;
+/**
+ * Apply a reviewed plan as one guarded mutation: every write, including the
+ * lock and each adopted target, is bound to the revision the plan reviewed,
+ * so the collection gets all of it or none. If anything changed since the
+ * plan, this refuses with `conflict`/`concurrent_modification`; plan again.
+ * An already-current pack writes nothing. A mutation the replica rejects or
+ * cannot settle throws its problem with the original `mutationId`; it is
+ * never reported as applied and never re-planned here.
+ */
+export declare function applyTypePack(client: MdbaseClient, plan: TypePackPlan, o?: WriteOptions): Promise<TypePackApplyResult>;

package/dist/type-packs.js

@@ -0,0 +1,188 @@
+import { bool, hash, list, struct, tstr, uint, value } from "./codec.js";
+import { isMdbaseError, MdbaseError, mdbaseError } from "./errors.js";
+import { toPlain, toValue } from "./values.js";
+const writeWire = struct("type-pack-write-v1", [
+    [0, "path", tstr], [1, "doc", tstr, "opt"], [2, "baseRevision", hash, "opt"], [3, "mustNotExist", bool],
+]);
+const planWire = struct("type-pack-plan-v1", [
+    [0, "version", uint], [1, "assessment", value], [2, "writes", list(writeWire), "opt"],
+]);
+const ACTIONS = ["create", "update", "delete", "adopt", "unchanged", "preserve", "conflict"];
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+const str = (v) => (typeof v === "string" ? v : undefined);
+function opt(key, v) {
+    return (v === undefined ? {} : { [key]: v });
+}
+function receipt(v) {
+    const r = obj(v);
+    return {
+        id: str(r.id), version: str(r.version), digest: str(r.digest), installedBy: str(r.installed_by),
+        resources: (Array.isArray(r.resources) ? r.resources : []).map((x) => {
+            const e = obj(x);
+            return {
+                source: str(e.source), target: str(e.target), kind: str(e.kind),
+                mode: str(e.mode), digest: str(e.digest), ...opt("originDigest", str(e.origin_digest)),
+            };
+        }),
+    };
+}
+function resource(v) {
+    const e = obj(v);
+    const b = e.upgrade_baseline === undefined ? undefined : obj(e.upgrade_baseline);
+    const version = b && (typeof b.version === "number" ? b.version : typeof b.version === "string" ? Number(b.version) : undefined);
+    return {
+        source: str(e.source) ?? "", target: str(e.target), kind: str(e.kind),
+        mode: str(e.mode), action: str(e.action),
+        ...opt("digest", str(e.digest)), ...opt("currentDigest", str(e.current_digest)),
+        ...opt("installedDigest", str(e.installed_digest)), ...opt("adoptedFromDigest", str(e.adopted_from_digest)),
+        ...opt("upgradeBaseline", b && { digest: str(b.digest), ...opt("version", version) }),
+        ...opt("reason", str(e.reason)),
+    };
+}
+function conflictMessage(r, adoptable) {
+    if (adoptable)
+        return `${r.target} already exists with different content. Review it, then adopt it to let this pack manage it.`;
+    return r.reason ? `${r.target} can't be changed: ${r.reason}.` : `${r.target} can't be changed by this pack.`;
+}
+/** The plan from the replica's assessment. */
+function toPlan(raw, pack, options) {
+    const a = obj(toPlain(raw));
+    const resources = (Array.isArray(a.resources) ? a.resources : []).map(resource);
+    const summary = Object.fromEntries(ACTIONS.map((k) => [k, resources.filter((r) => r.action === k).map((r) => r.target)]));
+    const adoptable = {};
+    const conflicts = resources.filter((r) => r.action === "conflict").map((r) => {
+        // An unmanaged live target the pack would own: adoption resolves it.
+        const canAdopt = r.mode === "managed" && r.currentDigest !== undefined && r.installedDigest === undefined;
+        if (canAdopt)
+            adoptable[r.target] = r.currentDigest;
+        return {
+            target: r.target, kind: r.kind, ...opt("reason", r.reason), message: conflictMessage(r, canAdopt),
+            ...opt("adoptable", canAdopt ? { digest: r.currentDigest } : undefined),
+        };
+    });
+    const status = str(a.status);
+    const issues = Array.isArray(a.issues) ? a.issues.map(obj) : [];
+    const desired = receipt(a.desired);
+    let refusal;
+    if (a.definitions_manage !== true) {
+        refusal = { code: "forbidden", message: "This app doesn't have permission to change the collection's types." };
+    }
+    else if (status === "downgrade") {
+        const installed = a.current === undefined ? "a newer version" : `version ${receipt(a.current).version}`;
+        refusal = { code: "type_pack_downgrade", message: `${desired.id} ${installed} is installed; ${desired.version} is older.` };
+    }
+    else if (conflicts.length) {
+        const n = conflicts.length;
+        refusal = {
+            code: "type_pack_conflict",
+            message: Object.keys(adoptable).length === n
+                ? `${n === 1 ? "A type already exists" : `${n} types already exist`} with different content. Review and adopt ${n === 1 ? "it" : "them"} to continue.`
+                : conflicts.map((c) => c.message).join(" "),
+        };
+    }
+    else if (issues.length || a.applicable !== true) {
+        refusal = { code: "invalid_type_pack", message: `This pack would leave the collection invalid: ${str(issues[0]?.message) ?? "the staged types do not validate"}.` };
+    }
+    const lock = obj(a.lock);
+    return Object.freeze({
+        status, canApply: a.applicable === true && refusal === undefined, digest: str(a.assessment_digest),
+        summary, conflicts, adoptable, resources, ...opt("current", a.current === undefined ? undefined : receipt(a.current)),
+        desired, lock: { target: str(lock.target), action: str(lock.action), digest: str(lock.digest) },
+        ...opt("refusal", refusal), pack, options,
+    });
+}
+function textMap(m) {
+    return m && Object.keys(m).length ? toValue(m) : undefined;
+}
+function contractSetupsRequested(input) {
+    if (input === undefined || input === null)
+        return false;
+    if (Array.isArray(input))
+        return input.length > 0;
+    return typeof input === "object" && Object.keys(input).length > 0;
+}
+async function call(client, pack, o, expected) {
+    if (contractSetupsRequested(o.contractSetups)) {
+        throw mdbaseError("invalid_request", "Contract setup during type pack install is not supported yet.", "type_pack_contract_setups_unsupported");
+    }
+    const provision = new Map([
+        ["manifest", toValue(pack.manifest)],
+        ["resources", pack.resources.map((r) => new Map([["source", r.source], ["document", r.document]]))],
+    ]);
+    if (pack.provides !== undefined)
+        provision.set("provides", toValue(pack.provides));
+    const p = new Map([[0, 1], [1, provision], [2, o.installedBy]]);
+    const adopt = textMap(o.adopt);
+    if (adopt !== undefined)
+        p.set(3, adopt);
+    if (o.preserveSeedTargets?.length)
+        p.set(4, [...o.preserveSeedTargets]);
+    const overrides = textMap(o.targetOverrides);
+    if (overrides !== undefined)
+        p.set(5, overrides);
+    if (o.allowDowngrade)
+        p.set(6, true);
+    if (expected !== undefined)
+        p.set(7, hash.enc(expected));
+    try {
+        const r = await client.call("plan_type_pack_v1", p, { codec: planWire, retry: true, ...(o.signal ? { signal: o.signal } : {}) });
+        if (r.version !== 1)
+            throw mdbaseError("upgrade_required", "unsupported type pack plan", "type_packs_unsupported");
+        return r;
+    }
+    catch (e) {
+        if (isMdbaseError(e, "invalid_request") && e.reason === "unknown_method") {
+            throw mdbaseError("upgrade_required", "This collection's replica can't install type packs yet.", "type_packs_unsupported");
+        }
+        throw e;
+    }
+}
+/** Plan a type pack against the local collection. Writes nothing. */
+export async function planTypePack(client, pack, options) {
+    return toPlan((await call(client, pack, options)).assessment, pack, options);
+}
+const REFUSAL_ERROR = {
+    forbidden: "forbidden",
+    type_pack_conflict: "conflict",
+    type_pack_downgrade: "conflict",
+    invalid_type_pack: "invalid_request",
+    type_pack_contract_setups_unsupported: "invalid_request",
+};
+/**
+ * Apply a reviewed plan as one guarded mutation: every write, including the
+ * lock and each adopted target, is bound to the revision the plan reviewed,
+ * so the collection gets all of it or none. If anything changed since the
+ * plan, this refuses with `conflict`/`concurrent_modification`; plan again.
+ * An already-current pack writes nothing. A mutation the replica rejects or
+ * cannot settle throws its problem with the original `mutationId`; it is
+ * never reported as applied and never re-planned here.
+ */
+export async function applyTypePack(client, plan, o = {}) {
+    if (plan.refusal)
+        throw mdbaseError(REFUSAL_ERROR[plan.refusal.code], plan.refusal.message, plan.refusal.code);
+    const options = o.signal ? { ...plan.options, signal: o.signal } : plan.options;
+    const r = await call(client, plan.pack, options, plan.digest);
+    const applied = toPlan(r.assessment, plan.pack, plan.options);
+    const writes = r.writes ?? [];
+    if (!writes.length)
+        return { outcome: "already_current", receipt: applied.desired };
+    const ops = writes.map((w) => w.doc === undefined
+        ? { kind: "resource_delete", path: w.path, ...opt("baseRevision", w.baseRevision) }
+        : { kind: "resource_put", path: w.path, doc: w.doc, ...opt("baseRevision", w.baseRevision), ...(w.mustNotExist ? { mustNotExist: true } : {}) });
+    const write = (await client.submit(ops, { ...o, allowPartial: false }))[0];
+    const receipt = write.receipt;
+    if (receipt.state === "rejected" || receipt.state === "unknown") {
+        throw new MdbaseError(receipt.problem ?? (receipt.state === "unknown"
+            ? { code: "outcome_unknown", recovery: "resolve_outcome", message: "The type pack install outcome is unknown." }
+            : { code: "internal", recovery: "contact_support", message: "The type pack install was rejected." }), { mutationId: receipt.mutation });
+    }
+    // A dry run that would apply is a preview; nothing was installed.
+    if (o.dryRun)
+        return { outcome: "preview", receipt: applied.desired, write };
+    if (receipt.status === "conflicted" || (receipt.conflicts?.length ?? 0) > 0) {
+        throw new MdbaseError({ code: "conflict", recovery: "resolve_conflict", reason: "type_pack_conflict",
+            message: "The type pack install has a conflict. Resolve it before continuing." }, { mutationId: receipt.mutation });
+    }
+    return { outcome: receipt.state === "confirmed" ? "applied" : "pending", receipt: applied.desired, write };
+}
+//# sourceMappingURL=type-packs.js.map