@parity/product-sdk-host 0.0.0-dev.312.0

package/src/container.ts

@@ -0,0 +1,339 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import type { JsonRpcProvider } from "polkadot-api";
+import type { HexString, TrUApiClient } from "@parity/truapi";
+
+import { formatHostError } from "./errors.js";
+import { createHostPapiProvider } from "./papi-provider.js";
+import { getClient, isCorrectEnvironment, subscribeWithInterrupt } from "./transport.js";
+import { fromHex, toHex, unwrapHostResult } from "./truapi.js";
+import type { HostLocalStorage, HostStatementStore } from "./types.js";
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * Synchronous container detection — fast heuristic check (iframe, webview
+ * marker, or injected host message port). Re-exported from the transport
+ * bootstrap, which owns the detection logic.
+ */
+export { isCorrectEnvironment as isInsideContainerSync } from "./transport.js";
+
+/**
+ * Thrown by {@link getHostProvider} when the host container is reachable but does
+ * not support the requested chain — e.g. the chain isn't enabled in this host
+ * build, or the descriptor's genesis hash has drifted from the host's after a
+ * network reset.
+ *
+ * Surfacing this as a thrown error (rather than handing back a provider that
+ * silently swallows every JSON-RPC request) is what lets callers of
+ * `createChainClient` detect the failure. Without it, the host's fallback no-op
+ * provider drops every request on the floor and queries await forever.
+ */
+export class ChainNotSupportedError extends Error {
+    /** Genesis hash of the chain the host refused, for programmatic detection. */
+    readonly genesisHash: string;
+
+    constructor(genesisHash: string) {
+        super(
+            `Chain ${genesisHash} is not supported by the current host. It may not be enabled in this host build, or its genesis hash may have drifted after a network reset.`,
+        );
+        this.name = "ChainNotSupportedError";
+        this.genesisHash = genesisHash;
+    }
+}
+
+/**
+ * Ask the host whether it can serve the given chain, via
+ * `system.featureSupported({ tag: "Chain", … })`. Gates {@link getHostProvider}
+ * the same way the upstream wrapper's provider gated itself internally before
+ * deciding whether to start a real provider or a no-op one.
+ *
+ * @throws If the host rejects the support check outright — a non-hanging,
+ *   catchable failure.
+ */
+async function isChainSupportedByHost(
+    client: TrUApiClient,
+    genesisHash: HexString,
+): Promise<boolean> {
+    return client.system.featureSupported({ tag: "Chain", value: { genesisHash } }).match(
+        (response) => response.supported,
+        (error) => {
+            throw new Error(
+                `Host rejected the chain-support check for ${genesisHash}: ${formatHostError(error)}`,
+            );
+        },
+    );
+}
+
+/**
+ * Detect if running inside a Host container (Polkadot Browser / Polkadot Desktop).
+ *
+ * The SDK is designed to run exclusively inside a host container. This function
+ * is primarily useful for early validation or informational purposes.
+ */
+export async function isInsideContainer(): Promise<boolean> {
+    return isCorrectEnvironment();
+}
+
+/**
+ * Adapt the TruAPI client's raw `localStorage` domain (hex-encoded
+ * `read`/`write`/`clear`) into the richer {@link HostLocalStorage} surface that
+ * the Storage package's `KvStore` and other consumers expect.
+ */
+function adaptLocalStorage(client: TrUApiClient): HostLocalStorage {
+    const ls = client.localStorage;
+
+    async function readBytes(key: string): Promise<Uint8Array | undefined> {
+        const response = await unwrapHostResult(ls.read({ key }), "host localStorage read failed");
+        return response.value !== undefined ? fromHex(response.value) : undefined;
+    }
+
+    async function writeBytes(key: string, value: Uint8Array): Promise<void> {
+        await unwrapHostResult(
+            ls.write({ key, value: toHex(value) }),
+            "host localStorage write failed",
+        );
+    }
+
+    async function readString(key: string): Promise<string> {
+        const bytes = await readBytes(key);
+        return bytes ? textDecoder.decode(bytes) : "";
+    }
+
+    async function writeString(key: string, value: string): Promise<void> {
+        return writeBytes(key, textEncoder.encode(value));
+    }
+
+    async function readJSON(key: string): Promise<unknown> {
+        const text = await readString(key);
+        return text ? JSON.parse(text) : null;
+    }
+
+    async function writeJSON(key: string, value: unknown): Promise<void> {
+        return writeString(key, JSON.stringify(value));
+    }
+
+    async function clear(key: string): Promise<void> {
+        await unwrapHostResult(ls.clear({ key }), "host localStorage clear failed");
+    }
+
+    return { readString, writeString, readJSON, writeJSON, readBytes, writeBytes, clear };
+}
+
+/**
+ * Get the Host API localStorage instance when running inside a container.
+ * Returns null outside a container or when the host transport is unavailable.
+ */
+export async function getHostLocalStorage(): Promise<HostLocalStorage | null> {
+    const client = await getClient();
+    return client ? adaptLocalStorage(client) : null;
+}
+
+/**
+ * Construct a host-backed `HostLocalStorage` instance. Retained for API
+ * compatibility; with the single cached TruAPI client this is equivalent to
+ * {@link getHostLocalStorage}.
+ *
+ * @returns A `HostLocalStorage` instance, or `null` if unavailable.
+ */
+export async function createHostLocalStorage(): Promise<HostLocalStorage | null> {
+    return getHostLocalStorage();
+}
+
+/**
+ * Get a PAPI-compatible JSON-RPC provider that routes through the host connection.
+ *
+ * When running inside a Polkadot container, this builds a `JsonRpcProvider` over
+ * `truApi.chain.*` (see {@link module:papi-provider}), enabling shared
+ * connections and efficient routing. Returns `null` when not running inside a
+ * container.
+ *
+ * @param genesisHash - Genesis hash of the target chain (`0x`-prefixed hex string).
+ * @returns A host-routed `JsonRpcProvider`, or `null` if unavailable.
+ * @throws {ChainNotSupportedError} When inside a container but the host can't serve
+ *   the chain — surfaced instead of returning a provider that would hang forever.
+ */
+export async function getHostProvider(genesisHash: HexString): Promise<JsonRpcProvider | null> {
+    const client = await getClient();
+    if (!client) return null;
+    return resolveHostProvider(client, genesisHash);
+}
+
+/**
+ * Decide whether to build a host provider for `genesisHash`, given a ready
+ * TruAPI client. Split out of {@link getHostProvider} so the decision logic can
+ * be unit-tested with a fake client.
+ *
+ * @returns the provider.
+ * @throws {ChainNotSupportedError} when the host can't serve the chain.
+ */
+async function resolveHostProvider(
+    client: TrUApiClient,
+    genesisHash: HexString,
+): Promise<JsonRpcProvider> {
+    // Confirm the host can actually serve this chain before handing PAPI a
+    // provider. When the host doesn't support the chain, a provider would silently
+    // swallow every JSON-RPC request and the caller hangs forever with no
+    // rejection. Surface a catchable error instead.
+    if (!(await isChainSupportedByHost(client, genesisHash))) {
+        throw new ChainNotSupportedError(genesisHash);
+    }
+
+    return createHostPapiProvider(client, genesisHash);
+}
+
+/** Build a {@link HostStatementStore} over a TruAPI client's `statementStore` domain. */
+function adaptStatementStore(client: TrUApiClient): HostStatementStore {
+    const ss = client.statementStore;
+    return {
+        subscribe(filter, callback) {
+            const request =
+                "matchAll" in filter
+                    ? ({ tag: "MatchAll", value: filter.matchAll } as const)
+                    : ({ tag: "MatchAny", value: filter.matchAny } as const);
+            // `RemoteStatementStoreSubscribeItem` is structurally a StatementsPage.
+            return subscribeWithInterrupt(ss.subscribe({ request }), callback);
+        },
+        async createProofAuthorized(statement) {
+            const response = await unwrapHostResult(
+                ss.createProofAuthorized(statement),
+                "createProofAuthorized failed",
+            );
+            return response.proof;
+        },
+        async submit(signedStatement) {
+            await unwrapHostResult(ss.submit(signedStatement), "statement submit failed");
+        },
+    };
+}
+
+/**
+ * Get the host statement store when running inside a container, backed by
+ * `truApi.statementStore.*`.
+ *
+ * Returns a store with `subscribe`, `createProofAuthorized`, and `submit` that
+ * communicate through the host's native binary protocol — bypassing JSON-RPC
+ * entirely. Returns `null` outside a host container.
+ *
+ * @returns The host statement store, or `null` if unavailable.
+ */
+export async function getStatementStore(): Promise<HostStatementStore | null> {
+    const client = await getClient();
+    return client ? adaptStatementStore(client) : null;
+}
+
+if (import.meta.vitest) {
+    const { test, expect, vi, afterEach } = import.meta.vitest;
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    // A self-contained fake TruAPI client exposing just the `system` and `chain`
+    // domains the provider gate touches, so the chain-support decision can be
+    // tested without a real host connection.
+    function makeFakeClient(opts: { supported?: boolean; featureErr?: string | null }) {
+        const { supported = true, featureErr = null } = opts;
+        return {
+            system: {
+                featureSupported: (_request: unknown) => ({
+                    match: (
+                        okFn: (ok: { supported: boolean }) => boolean,
+                        errFn: (err: { reason: string }) => boolean,
+                    ) => (featureErr ? errFn({ reason: featureErr }) : okFn({ supported })),
+                }),
+            },
+            // Read synchronously by createHostPapiProvider; never invoked here.
+            chain: {},
+        } as unknown as TrUApiClient;
+    }
+
+    test("isInsideContainer is false in a Node environment (no window)", async () => {
+        expect(await isInsideContainer()).toBe(false);
+    });
+
+    test("isInsideContainer detects an injected host port", async () => {
+        const win = {};
+        Object.defineProperty(win, "top", { get: () => win });
+        (win as Record<string, unknown>).__HOST_API_PORT__ = 12345;
+        vi.stubGlobal("window", win);
+        expect(await isInsideContainer()).toBe(true);
+    });
+
+    test("getHostLocalStorage returns null outside container", async () => {
+        expect(await getHostLocalStorage()).toBeNull();
+    });
+
+    test("createHostLocalStorage returns null outside container", async () => {
+        expect(await createHostLocalStorage()).toBeNull();
+    });
+
+    test("adaptLocalStorage round-trips strings, JSON, and bytes over the TruAPI client", async () => {
+        // Minimal in-memory fake of the TruAPI localStorage domain (hex values).
+        const store = new Map<string, `0x${string}`>();
+        const okAsync = <T>(value: T) => ({
+            match: async (onOk: (v: T) => unknown) => onOk(value),
+        });
+        const fakeClient = {
+            localStorage: {
+                read: ({ key }: { key: string }) => okAsync({ value: store.get(key) }),
+                write: ({ key, value }: { key: string; value: `0x${string}` }) => {
+                    store.set(key, value);
+                    return okAsync(undefined);
+                },
+                clear: ({ key }: { key: string }) => {
+                    store.delete(key);
+                    return okAsync(undefined);
+                },
+            },
+        } as unknown as TrUApiClient;
+
+        const ls = adaptLocalStorage(fakeClient);
+        expect(await ls.readString("missing")).toBe("");
+        expect(await ls.readJSON("missing")).toBeNull();
+        expect(await ls.readBytes("missing")).toBeUndefined();
+
+        await ls.writeString("s", "hello");
+        expect(await ls.readString("s")).toBe("hello");
+
+        await ls.writeJSON("j", { a: 1 });
+        expect(await ls.readJSON("j")).toEqual({ a: 1 });
+
+        await ls.writeBytes("b", new Uint8Array([1, 2, 3]));
+        expect(Array.from((await ls.readBytes("b")) ?? [])).toEqual([1, 2, 3]);
+
+        await ls.clear("s");
+        expect(await ls.readString("s")).toBe("");
+    });
+
+    // --- chain-support gating (resolveHostProvider over truApi.system/chain) ---
+
+    test("resolves to a provider when the host supports the chain", async () => {
+        const provider = await resolveHostProvider(makeFakeClient({ supported: true }), "0xabc");
+        // createHostPapiProvider returns a JsonRpcProvider (an onMessage -> connection fn).
+        expect(typeof provider).toBe("function");
+    });
+
+    test("throws ChainNotSupportedError when the host doesn't support the chain", async () => {
+        const err = await resolveHostProvider(makeFakeClient({ supported: false }), "0xfeed").catch(
+            (e) => e,
+        );
+        expect(err).toBeInstanceOf(ChainNotSupportedError);
+        expect((err as ChainNotSupportedError).genesisHash).toBe("0xfeed");
+    });
+
+    test("throws when the host rejects the support check", async () => {
+        await expect(
+            resolveHostProvider(makeFakeClient({ featureErr: "boom" }), "0xabc"),
+        ).rejects.toThrow(/boom/);
+    });
+
+    test("getHostProvider returns null outside a container", async () => {
+        expect(await getHostProvider("0xabc")).toBeNull();
+    });
+
+    test("getStatementStore returns null outside a container", async () => {
+        expect(await getStatementStore()).toBeNull();
+    });
+}

package/src/entropy.ts

@@ -0,0 +1,105 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Higher-level wrapper for the host's entropy derivation (RFC-0007).
+ *
+ * `truApi.entropy.derive` takes a hex `context` and returns a hex `entropy`
+ * payload wrapped in a neverthrow `ResultAsync`. `deriveEntropy` keeps the
+ * ergonomic `Uint8Array → Result<Uint8Array, HostError>` signature: it
+ * hex-encodes the context on the way in and decodes the entropy on the way out.
+ *
+ * @module
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { type HostError, HostUnavailableError } from "./errors.js";
+import { type Result, err } from "./result.js";
+import { fromHex, getTruApi, mapHostResult, toHex } from "./truapi.js";
+
+const log = createLogger("host:entropy");
+
+/**
+ * Derive deterministic entropy from a context key (RFC-0007).
+ *
+ * The host derives entropy from the user's wallet + the provided context
+ * key. Calling with the same key on the same wallet yields the same bytes;
+ * different keys (or different wallets) yield uncorrelated entropy.
+ *
+ * @param key - Context key bytes (typically a SCALE-encoded discriminator).
+ * @returns `ok` with the derived entropy bytes, or
+ *   `err(HostUnavailableError | HostCallFailedError)`.
+ *
+ * @example
+ * ```ts
+ * import { deriveEntropy } from "@parity/product-sdk-host";
+ *
+ * const r = await deriveEntropy(new TextEncoder().encode("my-app:seed-v1"));
+ * if (r.ok) { const seed = r.value; }
+ * ```
+ */
+export async function deriveEntropy(key: Uint8Array): Promise<Result<Uint8Array, HostError>> {
+    const truApi = await getTruApi();
+    if (!truApi) {
+        return err(new HostUnavailableError("deriveEntropy: TruAPI unavailable"));
+    }
+    log.debug("deriveEntropy", { keyLen: key.length });
+
+    return mapHostResult(
+        truApi.entropy.derive({ context: toHex(key) }),
+        (response) => fromHex(response.entropy),
+        "deriveEntropy failed",
+    );
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe, vi } = import.meta.vitest;
+
+    function okAsync<T>(value: T) {
+        return { match: async (onOk: (v: T) => unknown) => onOk(value) };
+    }
+
+    async function withMockedTruApi<T>(
+        client: unknown,
+        fn: (mod: typeof import("./entropy.js")) => Promise<T>,
+    ): Promise<T> {
+        vi.resetModules();
+        vi.doMock("./truapi.js", async (importOriginal) => {
+            const original = await importOriginal<typeof import("./truapi.js")>();
+            return { ...original, getTruApi: async () => client };
+        });
+        try {
+            const mod = await import("./entropy.js");
+            return await fn(mod);
+        } finally {
+            vi.doUnmock("./truapi.js");
+            vi.resetModules();
+        }
+    }
+
+    // Tests live inside `describe` so the re-import in `withMockedTruApi`
+    // (via `vi.resetModules`) doesn't re-register top-level `test()` calls.
+    describe("deriveEntropy", () => {
+        test("returns err(HostUnavailableError) when TruAPI is unavailable", async () => {
+            await withMockedTruApi(null, async (mod) => {
+                const result = await mod.deriveEntropy(new Uint8Array([1, 2, 3]));
+                expect(result.ok).toBe(false);
+                if (!result.ok) {
+                    expect(result.error.name).toBe("HostUnavailableError");
+                }
+            });
+        });
+
+        test("hex-encodes the context and decodes the entropy bytes", async () => {
+            const derive = vi.fn(() => okAsync({ entropy: "0xc0ffee" }));
+            await withMockedTruApi({ entropy: { derive } }, async (mod) => {
+                const result = await mod.deriveEntropy(new Uint8Array([0xab, 0xcd]));
+                expect(derive).toHaveBeenCalledWith({ context: "0xabcd" });
+                expect(result.ok).toBe(true);
+                if (result.ok) {
+                    expect(Array.from(result.value)).toEqual([0xc0, 0xff, 0xee]);
+                }
+            });
+        });
+    });
+}

package/src/errors.ts

@@ -0,0 +1,239 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Typed errors carried on the `err` channel of the host public API's
+ * {@link Result} returns.
+ *
+ * The hierarchy mirrors `@parity/product-sdk-signer`'s error classes
+ * (`HostUnavailableError` / `HostRejectedError`), so the two layers share one
+ * idiom: branch with `instanceof`, and every error is a real `Error` with a
+ * stack trace and `cause`. The structured truapi wire error
+ * ({@link HostErrorPayload}) rides along as {@link HostCallFailedError.payload}
+ * for callers that want fine-grained tag-level handling.
+ *
+ * This module also owns {@link HostErrorPayload} (the wire-error shape) and
+ * {@link formatHostError} (renders a payload to a message) — co-located with the
+ * error classes that consume them so the host error model lives in one place.
+ *
+ * @module
+ */
+import type { SdkError } from "@parity/product-sdk-errors";
+import type { scale } from "@parity/truapi";
+
+/**
+ * What a `Domain`-tagged call error carries. Widened from truapi's per-domain
+ * `Versioned*Error` types (all `{ tag: "V1", value: <domain error> }` today)
+ * so one payload type covers every call.
+ */
+type VersionedDomainError = { tag: string; value?: unknown };
+
+/**
+ * The error a host call puts on its `Err` channel — truapi's canonical
+ * {@link scale.CallErrorValue} envelope. `Denied` / `Unsupported` /
+ * `MalformedFrame` / `HostFailure` are transport-level failures; `Domain`
+ * wraps the actual per-domain error in a versioned envelope, which
+ * {@link formatHostError} digs through when rendering.
+ *
+ * This is the payload {@link HostCallFailedError} carries — not the error
+ * type consumers branch on.
+ */
+export type HostErrorPayload = scale.CallErrorValue<VersionedDomainError>;
+
+/** Narrow to a tagged-union member: `{ tag, value? }`. */
+function isTagged(value: unknown): value is { tag: string; value?: unknown } {
+    return (
+        value != null &&
+        typeof value === "object" &&
+        typeof (value as { tag?: unknown }).tag === "string"
+    );
+}
+
+/** Narrow to a reason-carrying payload — truapi's `GenericError` shape. */
+function hasReason(value: unknown): value is { reason: string } {
+    return (
+        value != null &&
+        typeof value === "object" &&
+        typeof (value as { reason?: unknown }).reason === "string"
+    );
+}
+
+/**
+ * Extract a human-readable message from a host-side error.
+ *
+ * Renders the {@link HostErrorPayload} shapes `@parity/truapi` surfaces. Accepts
+ * `unknown` because it is also the catch-all formatter for thrown adapter-method
+ * `Error` messages, so it falls back to `Error`/string/JSON rendering for
+ * anything that isn't a recognized host error payload.
+ *
+ * Used by {@link HostCallFailedError} to render its message, and by the throwing
+ * adapter-method helper `unwrapHostResult`.
+ */
+export function formatHostError(error: unknown): string {
+    if (error instanceof Error) return error.message;
+    if (typeof error === "string") return error;
+
+    if (isTagged(error)) {
+        // `Domain` carries the real error inside a versioned envelope — unwrap it.
+        if (error.tag === "Domain" && isTagged(error.value) && error.value.value !== undefined) {
+            return formatHostError(error.value.value);
+        }
+        // Tagged variant carrying a reason: { tag, value: { reason } }
+        if (hasReason(error.value)) {
+            return `${error.tag}: ${error.value.reason}`;
+        }
+        // Unit tagged variant, e.g. { tag: "Denied" } / { tag: "PermissionDenied" }
+        return error.tag;
+    }
+    // GenericError: { reason }
+    if (hasReason(error)) {
+        return error.reason;
+    }
+
+    if (error != null && typeof error === "object" && "message" in error) {
+        const message = (error as { message: unknown }).message;
+        if (typeof message === "string") return message;
+    }
+
+    try {
+        return JSON.stringify(error);
+    } catch {
+        return String(error);
+    }
+}
+
+/**
+ * Base class for all host errors. Use `instanceof HostError` (or {@link isHostError})
+ * to catch any host-related failure. Implements the cross-package
+ * {@link SdkError} marker so `isSdkError(e)` also recognizes it.
+ */
+export class HostError extends Error implements SdkError {
+    readonly isSdkError = true as const;
+    readonly source = "host";
+
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "HostError";
+    }
+}
+
+/**
+ * The host API is not available — the app is running outside a Polkadot host
+ * container (no injected TruAPI transport). The dominant case during local
+ * development. Branch with `instanceof HostUnavailableError` to surface an
+ * "open this app in a Polkadot host" message.
+ */
+export class HostUnavailableError extends HostError {
+    constructor(message = "Host API is not available") {
+        super(message);
+        this.name = "HostUnavailableError";
+    }
+}
+
+/**
+ * A host call reached the container but failed on the `Err` channel. Wraps the
+ * structured truapi {@link HostErrorPayload} as {@link payload} (also preserved
+ * as `cause`); the message is rendered via {@link formatHostError}.
+ */
+export class HostCallFailedError extends HostError {
+    readonly payload: HostErrorPayload;
+
+    constructor(label: string, payload: HostErrorPayload) {
+        super(`${label}: ${formatHostError(payload)}`, { cause: payload });
+        this.name = "HostCallFailedError";
+        this.payload = payload;
+    }
+}
+
+/** Check whether a value is any {@link HostError}. */
+export function isHostError(error: unknown): error is HostError {
+    return error instanceof HostError;
+}
+
+if (import.meta.vitest) {
+    const { test, expect, describe } = import.meta.vitest;
+
+    describe("host error classes", () => {
+        test("HostError is the base class", () => {
+            const e = new HostUnavailableError();
+            expect(e).toBeInstanceOf(HostError);
+            expect(e).toBeInstanceOf(Error);
+        });
+
+        test("HostUnavailableError default message", () => {
+            const e = new HostUnavailableError();
+            expect(e.name).toBe("HostUnavailableError");
+            expect(e.message).toBe("Host API is not available");
+        });
+
+        test("HostUnavailableError custom message", () => {
+            expect(new HostUnavailableError("nope").message).toBe("nope");
+        });
+
+        test("HostCallFailedError renders payload and preserves it", () => {
+            const payload: HostErrorPayload = {
+                tag: "Domain",
+                value: {
+                    tag: "V1",
+                    value: { tag: "PermissionDenied", value: { reason: "user said no" } },
+                },
+            };
+            const e = new HostCallFailedError("requestPermission failed", payload);
+            expect(e).toBeInstanceOf(HostError);
+            expect(e.payload).toBe(payload);
+            expect(e.cause).toBe(payload);
+            expect(e.message).toBe("requestPermission failed: PermissionDenied: user said no");
+        });
+
+        test("HostCallFailedError renders a Domain-wrapped GenericError payload", () => {
+            const e = new HostCallFailedError("submit failed", {
+                tag: "Domain",
+                value: { tag: "V1", value: { reason: "timeout" } },
+            });
+            expect(e.message).toBe("submit failed: timeout");
+        });
+
+        test("isHostError narrows host errors only", () => {
+            expect(isHostError(new HostUnavailableError())).toBe(true);
+            expect(isHostError(new HostCallFailedError("x", { tag: "Denied" }))).toBe(true);
+            expect(isHostError(new Error("plain"))).toBe(false);
+            expect(isHostError("string")).toBe(false);
+        });
+    });
+
+    describe("formatHostError", () => {
+        test("renders the TruAPI error payload shapes", () => {
+            // GenericError: { reason }
+            expect(formatHostError({ reason: "boom" })).toBe("boom");
+            // Tagged variant carrying a reason: { tag, value: { reason } }
+            expect(formatHostError({ tag: "Unknown", value: { reason: "boom" } })).toBe(
+                "Unknown: boom",
+            );
+            // Unit tagged variant: { tag }
+            expect(formatHostError({ tag: "Full" })).toBe("Full");
+        });
+
+        test("unwraps the CallError Domain envelope to the domain error", () => {
+            // { tag: "Domain", value: { tag: "V1", value: <domain error> } }
+            expect(
+                formatHostError({
+                    tag: "Domain",
+                    value: { tag: "V1", value: { tag: "PermissionDenied" } },
+                }),
+            ).toBe("PermissionDenied");
+            expect(
+                formatHostError({ tag: "Domain", value: { tag: "V1", value: { reason: "boom" } } }),
+            ).toBe("boom");
+            // Transport-level CallError variants render as-is.
+            expect(formatHostError({ tag: "Denied" })).toBe("Denied");
+            expect(formatHostError({ tag: "HostFailure", value: { reason: "crashed" } })).toBe(
+                "HostFailure: crashed",
+            );
+        });
+
+        test("falls back for non-host-error input", () => {
+            expect(formatHostError(new Error("plain"))).toBe("plain");
+            expect(formatHostError("string err")).toBe("string err");
+            expect(formatHostError({ message: "loose" })).toBe("loose");
+        });
+    });
+}