@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/core/tests/client-disposed.test.ts

@@ -0,0 +1,403 @@
+/**
+ * Calls on a client after `dispose()`: every one, whatever its kind and
+ * whoever the client called as, rejects `cancelled` with code
+ * `client_disposed` and `mayHaveExecuted: false`, and sends nothing.
+ *
+ * A disposed client calls as the anonymous principal. A call path that asks
+ * who calls before it asks whether the client is still there refuses a write
+ * as `unauthenticated` (`anonymous_write`) instead, which tells the person to
+ * sign in when nothing about signing in is wrong: a CLI that disposes its
+ * client on Ctrl-C would report "nobody is signed in" for its last write.
+ *
+ * A call already sent when the client is disposed settles as the replica
+ * answers; one still waiting to be sent is cancelled like a new one.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { c, principal } from "@meantjs/schema"
+import type { Identity } from "@icp-sdk/core/agent"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import {
+  MutationObserver,
+  skipToken,
+  type QueryFunctionContext,
+} from "@tanstack/query-core"
+import type { Client } from "../src/client.js"
+import { isReactorError } from "../src/errors.js"
+import type { Canister } from "../src/index.js"
+import type { CanisterQueryOptions } from "../src/types.js"
+import { createTestAuth } from "../src/testing/test-auth.js"
+import {
+  ARCHIVE,
+  MANAGEMENT,
+  SHAPES,
+  canisterRequests,
+  clientAs,
+  clientWithAuth,
+  deferred,
+  replicaWith,
+  requestsFor,
+  serve,
+} from "./canister-helpers.js"
+import { withIdentity } from "./client-helpers.js"
+import * as archive from "./fixtures/archive.js"
+import * as management from "./fixtures/management.js"
+import * as shapes from "./fixtures/shapes.js"
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+const alice = Ed25519KeyIdentity.generate()
+
+/** The archive canister's interface, as the func types of `archive.did` describe it. */
+const archiveService = c.service({
+  read_range: archive.QueryArchiveFn,
+  notify: archive.NotifyFn,
+})
+type ArchiveActor = {
+  read_range: (arg: archive.GetBlocksArgs) => Promise<archive.BlockRange>
+  notify: (text: string) => Promise<bigint>
+}
+
+/**
+ * A replica running the shapes canister, the management canister and an
+ * archive. `bump` waits for `hold` when one is given, so a test can dispose
+ * the client while the replica holds the update.
+ */
+function replicaOf(hold?: { entered: () => void; until: Promise<void> }) {
+  return replicaWith({
+    [SHAPES]: serve<shapes.Actor>(shapes.actor, {
+      who: (_args, { caller }) => principal(caller),
+      one: ([n]) => n + 1n,
+      bump: async ([n]) => {
+        if (hold !== undefined) {
+          hold.entered()
+          await hold.until
+        }
+        return { tag: "ok", value: n + 1n }
+      },
+      fire: () => undefined,
+      address: ([seed], { caller }) => `${seed}:${caller}`,
+    }),
+    [MANAGEMENT]: serve<management.Actor>(management.actor, {
+      start_canister: () => undefined,
+      fetch_canister_logs: () => ({ canister_log_records: [] }),
+    }),
+    [ARCHIVE]: serve<ArchiveActor>(archiveService, {
+      read_range: () => ({ blocks: [] }),
+      notify: ([text]) => BigInt(text.length),
+    }),
+  })
+}
+
+type Replica = ReturnType<typeof replicaOf>
+
+/** What a call is made on: the client and the canisters it made before it was disposed. */
+interface Made {
+  readonly client: Client
+  readonly canister: Canister<shapes.Actor>
+  readonly ic: Canister<management.Actor>
+}
+
+const made = (client: Client): Made => ({
+  client,
+  canister: client.canister<shapes.Actor>(shapes.actor, { id: SHAPES }),
+  ic: client.canister<management.Actor>(management.actor, { id: MANAGEMENT }),
+})
+
+/** The two ways a client says who calls: a fixed identity, and an auth that is signed in. */
+const CLIENTS: readonly {
+  readonly built: string
+  readonly make: (replica: Replica) => Client
+}[] = [
+  {
+    built: "built with an identity",
+    make: (replica) => clientAs(replica, alice),
+  },
+  {
+    built: "signed in through its auth",
+    make: (replica) => clientWithAuth(replica, createTestAuth({ seed: 1 })),
+  },
+]
+
+/** Every kind of call an app makes, each with the method and canister its error names. */
+const CALLS: readonly {
+  readonly name: string
+  readonly method: string
+  readonly canisterId: string
+  readonly call: (made: Made) => Promise<unknown>
+}[] = [
+  {
+    name: "a direct query",
+    method: "who",
+    canisterId: SHAPES,
+    call: ({ canister }) => canister.who(),
+  },
+  {
+    name: "a direct update",
+    method: "bump",
+    canisterId: SHAPES,
+    call: ({ canister }) => canister.bump(1n),
+  },
+  {
+    name: "a direct oneway",
+    method: "fire",
+    canisterId: SHAPES,
+    call: ({ canister }) => canister.fire("x"),
+  },
+  {
+    name: "a read's query function",
+    method: "one",
+    canisterId: SHAPES,
+    call: ({ client, canister }) =>
+      client.queryClient.fetchQuery(client.queryOptions(canister, "one", 1n)),
+  },
+  {
+    name: "an idempotent update read's query function",
+    method: "address",
+    canisterId: SHAPES,
+    call: ({ client, canister }) =>
+      client.queryClient.fetchQuery(
+        client.queryOptions(canister, "address", "x", { update: "idempotent" })
+      ),
+  },
+  {
+    name: "a mutation's function",
+    method: "bump",
+    canisterId: SHAPES,
+    call: ({ client, canister }) =>
+      new MutationObserver(
+        client.queryClient,
+        client.mutationOptions(canister, "bump")
+      ).mutate(1n),
+  },
+  {
+    name: "a query func reference",
+    method: "read_range",
+    canisterId: ARCHIVE,
+    call: ({ client }) =>
+      client.func<ArchiveActor["read_range"]>(archive.QueryArchiveFn, {
+        principal: principal(ARCHIVE),
+        method: "read_range",
+      })({ start: 0n, length: 1n }),
+  },
+  {
+    name: "an update func reference",
+    method: "notify",
+    canisterId: ARCHIVE,
+    call: ({ client }) =>
+      client.func<ArchiveActor["notify"]>(archive.NotifyFn, {
+        principal: principal(ARCHIVE),
+        method: "notify",
+      })("hello"),
+  },
+  {
+    name: "a management canister update",
+    method: "start_canister",
+    canisterId: MANAGEMENT,
+    call: ({ ic }) => ic.start_canister({ canister_id: principal(SHAPES) }),
+  },
+  {
+    name: "a management canister query",
+    method: "fetch_canister_logs",
+    canisterId: MANAGEMENT,
+    call: ({ ic }) =>
+      ic.fetch_canister_logs({ canister_id: principal(SHAPES) }),
+  },
+]
+
+/** What every call on a disposed client rejects with. */
+const disposed = (method: string, canisterId: string) => ({
+  kind: "cancelled",
+  code: "client_disposed",
+  mayHaveExecuted: false,
+  method,
+  canisterId,
+})
+
+/** Runs a read's query function as TanStack Query would. */
+function runQueryFn<D, E>({ queryFn }: CanisterQueryOptions<D, E>): Promise<D> {
+  if (queryFn === skipToken) throw new Error("the read is not skipped")
+  return queryFn({
+    signal: new AbortController().signal,
+  } as QueryFunctionContext)
+}
+
+const rejection = (promise: Promise<unknown>): Promise<unknown> =>
+  promise.then(
+    (value) => {
+      throw new Error(`expected a rejection, got ${String(value)}`)
+    },
+    (error: unknown) => error
+  )
+
+describe.each(CLIENTS)("a client $built, after dispose()", ({ make }) => {
+  it.each(CALLS)(
+    "rejects $name cancelled (client_disposed), and sends nothing",
+    async ({ method, canisterId, call }) => {
+      const replica = replicaOf()
+      const live = made(make(replica))
+      // The same call goes out while the client is live, so "nothing sent"
+      // below is not a blind spot of the replica's log.
+      await call(live)
+      expect(requestsFor(replica, method)).toHaveLength(1)
+
+      live.client.dispose()
+
+      const error = await rejection(call(live))
+      expect(isReactorError(error)).toBe(true)
+      expect(error).toMatchObject(disposed(method, canisterId))
+      expect(requestsFor(replica, method)).toHaveLength(1)
+    }
+  )
+
+  it("cancels the query and mutation functions of options built before it was disposed", async () => {
+    const replica = replicaOf()
+    const { client, canister } = made(make(replica))
+    const read = client.queryOptions(canister, "one", 1n)
+    const updateRead = client.queryOptions(canister, "address", "x", {
+      update: "idempotent",
+    })
+    const write = client.mutationOptions(canister, "bump")
+
+    client.dispose()
+
+    await expect(rejection(runQueryFn(read))).resolves.toMatchObject(
+      disposed("one", SHAPES)
+    )
+    await expect(rejection(runQueryFn(updateRead))).resolves.toMatchObject(
+      disposed("address", SHAPES)
+    )
+    await expect(rejection(write.mutationFn(1n))).resolves.toMatchObject(
+      disposed("bump", SHAPES)
+    )
+    expect(canisterRequests(replica)).toEqual([])
+  })
+
+  it("runs a mutation's onMutate, and its onSettled invalidates nothing", async () => {
+    const replica = replicaOf()
+    const { client, canister } = made(make(replica))
+    client.dispose()
+    // A read of the canister written to, cached after the disposal emptied
+    // the cache: a write that may have run would mark it invalidated.
+    const key = client.queryKey(canister, "one", 1n)
+    client.queryClient.setQueryData(key, 2n)
+    const invalidate = vi.spyOn(client.queryClient, "invalidateQueries")
+    const mutation = new MutationObserver(
+      client.queryClient,
+      client.mutationOptions(canister, "bump")
+    )
+
+    await expect(rejection(mutation.mutate(1n))).resolves.toMatchObject(
+      disposed("bump", SHAPES)
+    )
+
+    expect(mutation.getCurrentResult()).toMatchObject({
+      status: "error",
+      error: disposed("bump", SHAPES),
+    })
+    expect(invalidate).not.toHaveBeenCalled()
+    expect(client.queryClient.getQueryState(key)?.isInvalidated).toBe(false)
+    expect(canisterRequests(replica)).toEqual([])
+  })
+})
+
+describe("a client nobody signed in to", () => {
+  it("refuses a write unauthenticated while it is live, and cancels it once it is disposed", async () => {
+    const replica = replicaOf()
+    const readOnly = made(clientAs(replica, "anonymous"))
+    const signedOut = made(
+      clientWithAuth(replica, createTestAuth({ seed: 1, signedIn: false }))
+    )
+
+    for (const { canister, client } of [readOnly, signedOut]) {
+      await expect(rejection(canister.bump(1n))).resolves.toMatchObject({
+        kind: "unauthenticated",
+        code: "anonymous_write",
+        mayHaveExecuted: false,
+      })
+      client.dispose()
+      await expect(rejection(canister.bump(1n))).resolves.toMatchObject(
+        disposed("bump", SHAPES)
+      )
+    }
+    expect(canisterRequests(replica)).toEqual([])
+  })
+})
+
+describe("a call in flight when the client is disposed", () => {
+  it("settles a write the replica already has as the replica answers, and its onSettled runs on the emptied cache", async () => {
+    const entered = deferred()
+    const release = deferred()
+    const replica = replicaOf({
+      entered: entered.resolve,
+      until: release.promise,
+    })
+    const { client, canister } = made(clientAs(replica, alice))
+    const invalidate = vi.spyOn(client.queryClient, "invalidateQueries")
+    const mutation = new MutationObserver(
+      client.queryClient,
+      client.mutationOptions(canister, "bump")
+    )
+
+    const write = mutation.mutate(1n)
+    await entered.promise
+    client.dispose()
+    release.resolve()
+
+    await expect(write).resolves.toBe(2n)
+    expect(mutation.getCurrentResult().status).toBe("success")
+    // The write ran, so its reads are invalidated: there are none left.
+    expect(invalidate).toHaveBeenCalledTimes(1)
+    expect(client.queryClient.getQueryCache().getAll()).toEqual([])
+    expect(requestsFor(replica, "bump")).toHaveLength(1)
+  })
+
+  it("cancels a write still waiting for its caller's identity, and sends nothing", async () => {
+    const asked = deferred()
+    const gate = deferred()
+    const auth = createTestAuth({ seed: 1 })
+    const slowAuth = withIdentity(auth, async () => {
+      const identity = await auth.getIdentity()
+      asked.resolve()
+      await gate.promise
+      return identity
+    })
+    const replica = replicaOf()
+    const { client, canister } = made(clientWithAuth(replica, slowAuth))
+
+    const write = rejection(canister.bump(1n))
+    await asked.promise
+    client.dispose()
+    gate.resolve()
+
+    await expect(write).resolves.toMatchObject(disposed("bump", SHAPES))
+    expect(canisterRequests(replica)).toEqual([])
+  })
+
+  it("cancels a write disposed of just after its agent was handed over, and sends nothing", async () => {
+    // The identity's promise settles; the client's own reaction to it hands
+    // the agent over, and the next reaction on the same promise disposes the
+    // client, before the call resumes and would send.
+    const asked = deferred()
+    const gate = deferred()
+    let identity: Promise<Identity> | undefined
+    const auth = createTestAuth({ seed: 1 })
+    const slowAuth = withIdentity(auth, () => {
+      identity = gate.promise.then(() => auth.getIdentity())
+      asked.resolve()
+      return identity
+    })
+    const replica = replicaOf()
+    const { client, canister } = made(clientWithAuth(replica, slowAuth))
+
+    const write = rejection(canister.bump(1n))
+    await asked.promise
+    void identity?.then(() => client.dispose())
+    gate.resolve()
+
+    await expect(write).resolves.toMatchObject(disposed("bump", SHAPES))
+    expect(canisterRequests(replica)).toEqual([])
+  })
+})

package/packages/core/tests/client-helpers.ts

@@ -0,0 +1,136 @@
+/**
+ * Fixtures for the client tests: a fake replica whose canister answers with
+ * the caller it was told about, a browser page, and auths that a test can
+ * slow down or renew behind the client's back.
+ */
+import { QueryResponseStatus, type Identity } from "@icp-sdk/core/agent"
+import { IDL } from "@icp-sdk/core/candid"
+import {
+  DelegationChain,
+  DelegationIdentity,
+  Ed25519KeyIdentity,
+} from "@icp-sdk/core/identity"
+import { Principal } from "@icp-sdk/core/principal"
+import { vi } from "vitest"
+import type { AuthLike, Client } from "../src/client.js"
+import { internalsOf } from "../src/client.js"
+import {
+  createFakeReplica,
+  type FakeCanister,
+  type FakeReplica,
+} from "../src/testing/fake-replica.js"
+
+/** The anonymous principal, as text. */
+export const ANONYMOUS = "2vxsx-fae"
+
+/** The canister every test calls. */
+export const CANISTER = "rdmx6-jaaaa-aaaaa-aaadq-cai"
+
+/** What a test names in the context of a call it asks an agent for. */
+export const CALL = { method: "whoami", canisterId: CANISTER } as const
+
+const answerWithCaller = (
+  _method: string,
+  _arg: Uint8Array,
+  { caller }: { caller: Principal }
+): Uint8Array => new Uint8Array(IDL.encode([IDL.Principal], [caller]))
+
+/** A canister that answers every query and update with the caller it sees. */
+export const whoami: FakeCanister = {
+  query: answerWithCaller,
+  update: answerWithCaller,
+}
+
+/** A fake replica running {@link whoami} at {@link CANISTER}. */
+export const replicaWithWhoami = (host?: string): FakeReplica =>
+  createFakeReplica({
+    ...(host && { host }),
+    canisters: { [CANISTER]: whoami },
+  })
+
+/** The network of `replica`, with its root key given so none is fetched. */
+export const networkOf = (replica: FakeReplica) => ({
+  host: replica.host,
+  rootKey: replica.rootKey,
+})
+
+/**
+ * Makes the code run in a browser page on an ordinary web host, which is not
+ * local, so the `ic_env` cookie is never trusted. Undo with
+ * `vi.unstubAllGlobals()`.
+ */
+export const onPage = (origin = "https://app.example.com"): void => {
+  vi.stubGlobal("window", {
+    location: { origin, protocol: new URL(origin).protocol },
+  })
+}
+
+/**
+ * Asks `client` for the agent of `principal`, as a read's query function
+ * would with the principal captured in its key, and sends a query through
+ * it. Resolves with the caller the canister saw.
+ */
+export async function readAs(
+  client: Client,
+  principal: string
+): Promise<string> {
+  const agent = await internalsOf(client).agentFor(principal, CALL)
+  const response = await agent.query(CANISTER, {
+    methodName: "whoami",
+    arg: new Uint8Array(IDL.encode([], [])),
+  })
+  if (response.status !== QueryResponseStatus.Replied) {
+    throw new Error(`the query was rejected with code ${response.reject_code}`)
+  }
+  return (
+    IDL.decode([IDL.Principal], response.reply.arg)[0] as unknown as Principal
+  ).toText()
+}
+
+/** The callers of the canister requests (`query` and `call`) the replica saw. */
+export const callersSeen = (replica: FakeReplica): string[] =>
+  replica.requests.flatMap((request) =>
+    (request.endpoint === "query" || request.endpoint === "call") &&
+    request.caller !== undefined
+      ? [request.caller]
+      : []
+  )
+
+/** A promise and the function that resolves it. */
+export function deferred<T = void>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+/** A delegation from `root` to a fresh session key, as a sign-in hands out. */
+export async function delegate(
+  root: Ed25519KeyIdentity
+): Promise<DelegationIdentity> {
+  const sessionKey = Ed25519KeyIdentity.generate()
+  const chain = await DelegationChain.create(
+    root,
+    sessionKey.getPublicKey(),
+    new Date(Date.now() + 60 * 60_000)
+  )
+  return DelegationIdentity.fromDelegation(sessionKey, chain)
+}
+
+/**
+ * `auth`, with its `getIdentity()` replaced by `identity`: a test decides
+ * which identity object it hands out, and when.
+ */
+export const withIdentity = (
+  auth: AuthLike,
+  identity: () => Promise<Identity>
+): AuthLike => ({
+  getPrincipal: () => auth.getPrincipal(),
+  getStatus: () => auth.getStatus(),
+  getIdentity: identity,
+  subscribe: (listener) => auth.subscribe(listener),
+  signIn: (options) => auth.signIn(options),
+  signOut: (options) => auth.signOut(options),
+  dispose: () => auth.dispose?.(),
+})

package/packages/core/tests/client-hydration.test.ts

@@ -0,0 +1,166 @@
+/**
+ * A client's cache survives a server-to-browser hand-off: `dehydrate()` on
+ * one client, `JSON.stringify`, `JSON.parse`, `hydrate()` into another, and
+ * every Candid value comes back exactly, `bigint` and `Uint8Array` included.
+ */
+import { describe, expect, it } from "vitest"
+import { dehydrate, hydrate } from "@tanstack/query-core"
+import { createClient } from "../src/client.js"
+import { deserializeData, serializeData } from "../src/hydration.js"
+
+/** What a canister reply can decode to, as `@meantjs/schema` shapes it. */
+const CANDID_VALUES = {
+  "nat above 2^64": 340282366920938463463374607431768211457n,
+  "negative int": -18446744073709551617n,
+  "zero nat": 0n,
+  blob: new Uint8Array([0, 1, 127, 128, 254, 255]),
+  "empty blob": new Uint8Array(),
+  "principal text": "rdmx6-jaaaa-aaaaa-aaadq-cai",
+  "absent opt": null,
+  "boxed opt holding null": { some: null },
+  "nested boxed opts": { some: { some: 1n } },
+  variant: {
+    tag: "Ok",
+    value: { amount: 5n, memo: new Uint8Array([9]), to: "2vxsx-fae" },
+  },
+  "nested variant": {
+    tag: "Err",
+    value: { tag: "InsufficientFunds", value: { balance: 3n } },
+  },
+  "vec of nat": [1n, 2n, 18446744073709551615n],
+  floats: [1.5, -2.25, NaN, Infinity, -Infinity, -0, 0],
+  "record shaped like a tag": { $ic: "bigint", v: "1" },
+  "record shaped like an escaped record": { $ic: "object", v: { a: 1 } },
+  "record with a tag-shaped field": { $ic: { $ic: "undefined" }, ok: true },
+  text: 'quotes " and \\ and 
 and emoji \u{1f600}',
+  "bool and empty": [true, false, [], {}],
+} as const
+
+/** Moves `value` through a server client's cache to a browser client's, as JSON. */
+function handOff(value: unknown): unknown {
+  const server = createClient({ network: "ic", identity: "anonymous" })
+  const browser = createClient({ network: "ic", identity: "anonymous" })
+  server.queryClient.setQueryData(["value"], value)
+
+  const json = JSON.stringify(dehydrate(server.queryClient))
+  hydrate(browser.queryClient, JSON.parse(json))
+
+  return browser.queryClient.getQueryData(["value"])
+}
+
+describe("a client's dehydrated cache", () => {
+  it.each(Object.entries(CANDID_VALUES))(
+    "round-trips %s through JSON into another client",
+    (_name, value) => {
+      expect(handOff(value)).toStrictEqual(value)
+    }
+  )
+
+  it("round-trips every value of one reply together", () => {
+    expect(handOff(CANDID_VALUES)).toStrictEqual(CANDID_VALUES)
+  })
+
+  it("brings integers back as bigint, blobs as Uint8Array and -0 as -0", () => {
+    const back = handOff({
+      big: 2n ** 70n,
+      bytes: new Uint8Array([1, 2]),
+      zero: -0,
+    }) as { big: unknown; bytes: unknown; zero: number }
+
+    expect(typeof back.big).toBe("bigint")
+    expect(back.big).toBe(2n ** 70n)
+    expect(back.bytes).toBeInstanceOf(Uint8Array)
+    expect((back.bytes as Uint8Array).constructor).toBe(Uint8Array)
+    expect(Object.is(back.zero, -0)).toBe(true)
+  })
+
+  it("writes JSON with no bigint left in it", () => {
+    const server = createClient({ network: "ic", identity: "anonymous" })
+    server.queryClient.setQueryData(["balance"], 10n ** 30n)
+
+    expect(() => JSON.stringify(dehydrate(server.queryClient))).not.toThrow()
+  })
+})
+
+describe("the serializer", () => {
+  const roundTrip = (value: unknown): unknown =>
+    deserializeData(JSON.parse(JSON.stringify(serializeData(value))))
+
+  it("keeps undefined where JSON would drop it or write null", () => {
+    const back = roundTrip({ present: undefined, list: [1, undefined, 2] }) as {
+      present?: undefined
+      list: unknown[]
+    }
+
+    expect("present" in back).toBe(true)
+    expect(back.list).toStrictEqual([1, undefined, 2])
+  })
+
+  it("keeps a __proto__ field as a field, without touching the prototype", () => {
+    // A Candid record may name a field "__proto__"; JSON.parse makes it an
+    // own key, and so must the way back.
+    const value = {}
+    Object.defineProperty(value, "__proto__", {
+      value: { polluted: 1n },
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    })
+    const back = roundTrip(value) as Record<string, unknown>
+
+    expect(Object.getPrototypeOf(back)).toBe(Object.prototype)
+    expect(Object.keys(back)).toEqual(["__proto__"])
+    expect(Object.getOwnPropertyDescriptor(back, "__proto__")?.value).toEqual({
+      polluted: 1n,
+    })
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined()
+  })
+
+  it("encodes a blob larger than one chunk", () => {
+    const blob = new Uint8Array(100_000).map((_, i) => (i * 7) % 256)
+
+    expect(roundTrip(blob)).toStrictEqual(blob)
+  })
+
+  it("brings a Node Buffer back as a plain Uint8Array", () => {
+    const back = roundTrip(Buffer.from([1, 2, 3]))
+
+    expect(back).toStrictEqual(new Uint8Array([1, 2, 3]))
+  })
+
+  it("treats what is not a Candid value as JSON does", () => {
+    const date = new Date("2026-10-02T00:00:00.000Z")
+    const back = roundTrip({
+      date,
+      skipped: () => 1,
+      list: [() => 1, Symbol("s")],
+    })
+
+    expect(back).toStrictEqual({
+      date: "2026-10-02T00:00:00.000Z",
+      list: [null, null],
+    })
+  })
+
+  it("refuses a cyclic structure, as JSON.stringify does", () => {
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+
+    expect(() => serializeData(cyclic)).toThrow(/cyclic/)
+    // A value seen twice, but not inside itself, is no cycle.
+    const shared = { n: 1n }
+    expect(roundTrip([shared, shared])).toStrictEqual([shared, shared])
+  })
+
+  it("refuses a tag it does not know instead of guessing", () => {
+    expect(() => deserializeData({ $ic: "date", v: "x" })).toThrow(
+      /unknown tag "date"/
+    )
+    expect(() => deserializeData({ $ic: "bigint", v: 1 })).toThrow(
+      /malformed bigint tag/
+    )
+    expect(() => deserializeData({ $ic: "number", v: "toString" })).toThrow(
+      /malformed number tag/
+    )
+  })
+})