@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/evals/conditions/v4-proto/lib/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @ic-reactor/v4-proto — typed, mode-gated handles for Internet Computer
+ * canister methods that produce TanStack Query options.
+ *
+ *   const client = createClient({ network, identity } | { network, auth })
+ *   const ledger = client.canister(LedgerService, { id })
+ *   useQuery(ledger.icrc1_balance_of.queryOptions([account]))   // reads only
+ *   await ledger.icrc1_balance_of.certified([account])           // plain queries only
+ *   useMutation(ledger.icrc1_transfer.mutationOptions({ invalidates: [ledger.icrc1_balance_of] }))
+ *   await ledger.icrc1_transfer([arg])                           // direct call
+ */
+export { createClient } from "./client.js"
+export type { AuthSource, Client, ClientOptions, Network } from "./client.js"
+export { defineService } from "./service.js"
+export type { ActorShape, ModeMap, ServiceDef } from "./service.js"
+export { isPrincipalText, principal } from "./principal.js"
+export type { PrincipalText, Textify } from "./principal.js"
+export { isReactorError } from "./errors.js"
+export type {
+  ReactorError,
+  ReactorErrorKind,
+  ReactorFailure,
+} from "./errors.js"
+export type {
+  Canister,
+  CompositeQueryHandle,
+  HandleArgs,
+  HandleData,
+  HandleErr,
+  HandleMutationOptions,
+  HandleQueryOptions,
+  MutationConfig,
+  QueryHandle,
+  ReadHandle,
+  UpdateHandle,
+} from "./types.js"

package/evals/conditions/v4-proto/lib/src/principal.ts

@@ -0,0 +1,175 @@
+// Principals as branded text at the boundary.
+//
+// @candid-core/schema decodes a principal to a structural carrier
+// `{ toText(): string }` (its `PrincipalValue`), and encodes anything with a
+// `toText()`. Handles use the one representation an app can put in a query
+// key, compare with `===`, render and serialise: text. Every value crossing
+// the boundary is walked, schema-directed, to swap carriers for branded text
+// on the way out and branded text for carriers on the way in.
+import type { AnyFieldSchema, PrincipalValue } from "@candid-core/schema"
+import { resolveSchema } from "@candid-core/schema"
+import { principalBytesFromText } from "@candid-core/schema/codec"
+
+declare const principalBrand: unique symbol
+
+/** Principal text that has been checked to be canonical. */
+export type PrincipalText = string & { readonly [principalBrand]: true }
+
+/** Checks and brands principal text. Throws `TypeError` when it is not one. */
+export function principal(text: string): PrincipalText {
+  if (!isPrincipalText(text)) {
+    throw new TypeError(`not a principal: ${JSON.stringify(text)}`)
+  }
+  return text
+}
+
+/** Whether `text` is canonical principal text. Never throws. */
+export function isPrincipalText(text: unknown): text is PrincipalText {
+  if (typeof text !== "string") return false
+  try {
+    return principalBytesFromText(text) !== undefined
+  } catch {
+    return false
+  }
+}
+
+/** The generated type with every `PrincipalValue` replaced by `PrincipalText`. */
+export type Textify<T> = T extends PrincipalValue
+  ? PrincipalText
+  : T extends Uint8Array
+    ? T
+    : T extends bigint | number | string | boolean | null | undefined
+      ? T
+      : T extends readonly unknown[]
+        ? { -readonly [K in keyof T]: Textify<T[K]> }
+        : T extends object
+          ? { [K in keyof T]: Textify<T[K]> }
+          : T
+
+type Direction = "in" | "out"
+
+const principalFree = new WeakMap<object, boolean>()
+
+/**
+ * Whether a schema can hold a principal anywhere, so values of the many that
+ * cannot skip the walk. Cycles (via `rec`) count as principal-free until a
+ * principal is found.
+ */
+function mentionsPrincipal(
+  schema: AnyFieldSchema,
+  visiting = new Set<object>()
+): boolean {
+  const cached = principalFree.get(schema)
+  if (cached !== undefined) return !cached
+  if (visiting.has(schema)) return false
+  visiting.add(schema)
+  const node = resolveSchema(schema)
+  let found: boolean
+  switch (node.kind) {
+    case "primitive":
+      found = node.primitive === "principal"
+      break
+    case "opt":
+    case "vec":
+      found = mentionsPrincipal(node.inner, visiting)
+      break
+    case "record":
+      found = Object.values(node.fields).some((f) =>
+        mentionsPrincipal(f as AnyFieldSchema, visiting)
+      )
+      break
+    case "variant":
+      found = Object.values(node.arms).some((f) =>
+        mentionsPrincipal(f as AnyFieldSchema, visiting)
+      )
+      break
+    case "tuple":
+      found = (node.elements as readonly AnyFieldSchema[]).some((e) =>
+        mentionsPrincipal(e, visiting)
+      )
+      break
+    case "func":
+    case "service":
+      found = true
+      break
+    default:
+      found = false
+  }
+  visiting.delete(schema)
+  if (visiting.size === 0) principalFree.set(schema, !found)
+  return found
+}
+
+const carrier = (text: string): PrincipalValue => ({ toText: () => text })
+
+function convertPrincipal(value: unknown, direction: Direction): unknown {
+  if (direction === "out") {
+    return value !== null && typeof value === "object" && "toText" in value
+      ? (value as PrincipalValue).toText()
+      : value
+  }
+  // In: branded text (or any text) becomes a carrier; the codec checks it.
+  return typeof value === "string" ? carrier(value) : value
+}
+
+function walk(
+  schema: AnyFieldSchema,
+  value: unknown,
+  direction: Direction
+): unknown {
+  if (!mentionsPrincipal(schema)) return value
+  const node = resolveSchema(schema)
+  switch (node.kind) {
+    case "primitive":
+      return node.primitive === "principal"
+        ? convertPrincipal(value, direction)
+        : value
+    case "opt":
+      return value === null ? null : walk(node.inner, value, direction)
+    case "vec":
+      return Array.isArray(value)
+        ? value.map((v) => walk(node.inner, v, direction))
+        : value
+    case "tuple": {
+      const elements = node.elements as readonly AnyFieldSchema[]
+      return Array.isArray(value)
+        ? value.map((v, i) =>
+            elements[i] ? walk(elements[i], v, direction) : v
+          )
+        : value
+    }
+    case "record": {
+      if (value === null || typeof value !== "object") return value
+      const out: Record<string, unknown> = {}
+      for (const [key, v] of Object.entries(value)) {
+        const field = (node.fields as Record<string, AnyFieldSchema>)[key]
+        out[key] = field ? walk(field, v, direction) : v
+      }
+      return out
+    }
+    case "variant": {
+      if (value === null || typeof value !== "object" || !("tag" in value))
+        return value
+      const tagged = value as { tag: string; value?: unknown }
+      const arm = (node.arms as Record<string, AnyFieldSchema>)[tagged.tag]
+      if (!arm || !("value" in tagged)) return value
+      return { ...tagged, value: walk(arm, tagged.value, direction) }
+    }
+    case "func": {
+      if (value === null || typeof value !== "object") return value
+      const ref = value as { principal: unknown; method: unknown }
+      return { ...ref, principal: convertPrincipal(ref.principal, direction) }
+    }
+    case "service":
+      return convertPrincipal(value, direction)
+    default:
+      return value
+  }
+}
+
+/** App values (principals as text) → values the codec encodes. */
+export const toWire = (schema: AnyFieldSchema, value: unknown) =>
+  walk(schema, value, "in")
+/** Decoded values (principal carriers) → app values (principals as text). */
+export const fromWire = (schema: AnyFieldSchema, value: unknown) =>
+  walk(schema, value, "out")

package/evals/conditions/v4-proto/lib/src/service.ts

@@ -0,0 +1,69 @@
+// A typed service descriptor over a module generated by candid-core.
+//
+// The generated module carries each method's signature in `type Actor` and
+// its mode (`query`, `composite_query`, `update`) in the service schema.
+// Handles need both in the type, so the descriptor names the actor type and
+// the method modes together:
+//
+//   export const LedgerService = defineService<Actor>()(actor, {
+//     icrc1_balance_of: "query",
+//     icrc1_transfer: "update",
+//     ...
+//   })
+//
+// and checks once, when it is built, that every declared mode is the
+// schema's mode and that the two method sets are equal.
+import type {
+  AnyFieldSchema,
+  MethodMode,
+  ServiceMethod,
+} from "@candid-core/schema"
+import { serviceMethods } from "@candid-core/schema"
+
+/** Any generated `Actor` type: method name → async function. */
+export type ActorShape = {
+  readonly [method: string]: (...args: never[]) => Promise<unknown>
+}
+
+/** One mode per method of `A`, and no other keys. */
+export type ModeMap<A> = { readonly [K in keyof A & string]: MethodMode }
+
+export interface ServiceDef<A extends ActorShape, M extends ModeMap<A>> {
+  readonly schema: AnyFieldSchema
+  readonly modes: M
+  readonly methods: ReadonlyMap<string, ServiceMethod>
+  /** Phantom: the generated actor interface. Never present at runtime. */
+  readonly actor?: A
+}
+
+/**
+ * `defineService<Actor>()(schema, modes)`. Curried so the actor interface is
+ * given explicitly while the mode literals are inferred.
+ */
+export function defineService<A extends ActorShape>() {
+  return <const M extends ModeMap<A>>(
+    schema: AnyFieldSchema,
+    modes: M & { readonly [K in Exclude<keyof M, keyof A>]: never }
+  ): ServiceDef<A, M> => {
+    const methods = serviceMethods(schema)
+    const declared = modes as Readonly<Record<string, MethodMode>>
+    for (const [name, method] of methods) {
+      if (!(name in declared)) {
+        throw new TypeError(
+          `defineService: method ${name} is missing from the mode map`
+        )
+      }
+      if (declared[name] !== method.mode) {
+        throw new TypeError(
+          `defineService: ${name} is declared ${declared[name]} but the schema says ${method.mode}`
+        )
+      }
+    }
+    for (const name of Object.keys(declared)) {
+      if (!methods.has(name)) {
+        throw new TypeError(`defineService: the schema has no method ${name}`)
+      }
+    }
+    return { schema, modes, methods }
+  }
+}

package/evals/conditions/v4-proto/lib/src/types.ts

@@ -0,0 +1,174 @@
+// The handle types: what a method's mode, arguments, data and error become.
+import type {
+  DataTag,
+  MutationFunctionContext,
+  QueryFunctionContext,
+  QueryKey,
+  SkipToken,
+} from "@tanstack/query-core"
+import type { ReactorError } from "./errors.js"
+import type { Textify } from "./principal.js"
+import type { ActorShape, ModeMap } from "./service.js"
+
+type ArgsOf<F> = F extends (...args: infer P) => Promise<unknown> ? P : never
+type ReplyOf<F> = F extends (...args: never[]) => Promise<infer R> ? R : never
+type ArmValue<V> = V extends { value: infer P } ? P : null
+
+type Split<R, OkTag extends string, ErrTag extends string> = [
+  Exclude<R, { tag: OkTag } | { tag: ErrTag }>,
+] extends [never]
+  ? [Extract<R, { tag: OkTag }>] extends [never]
+    ? undefined
+    : [Extract<R, { tag: ErrTag }>] extends [never]
+      ? undefined
+      : {
+          ok: ArmValue<Extract<R, { tag: OkTag }>>
+          err: ArmValue<Extract<R, { tag: ErrTag }>>
+        }
+  : undefined
+
+/**
+ * `{ ok, err }` when the reply is an exactly-two-arm `Ok`/`Err` (or `ok`/`err`)
+ * variant — the same rule `isResultSchema` applies at run time — else
+ * `undefined`.
+ */
+type ResultSplit<R> = [R] extends [never]
+  ? undefined
+  : Split<R, "Ok", "Err"> extends { ok: unknown }
+    ? Split<R, "Ok", "Err">
+    : Split<R, "ok", "err">
+
+/** The arguments a handle takes: the method's argument tuple, principals as text. */
+export type HandleArgs<F> = Textify<ArgsOf<F>>
+/** What a handle resolves with: the `Ok` payload for a result method, else the reply. */
+export type HandleData<F> =
+  ResultSplit<ReplyOf<F>> extends { ok: infer O }
+    ? Textify<O>
+    : Textify<ReplyOf<F>>
+/** The `Err` payload type of a result method; `never` for any other method. */
+export type HandleErr<F> =
+  ResultSplit<ReplyOf<F>> extends { err: infer E } ? Textify<E> : never
+
+declare const readBrand: unique symbol
+
+/** A handle whose cached data a write can invalidate: a query or composite query. */
+export interface ReadHandle {
+  readonly [readBrand]: true
+  readonly method: string
+  readonly canisterId: string
+  readonly network: string
+}
+
+/** Options for `useQuery`, `queryClient.fetchQuery` and friends. */
+export interface HandleQueryOptions<D, E> {
+  readonly queryKey: DataTag<QueryKey, D, ReactorError<E>>
+  readonly queryFn: ((context: QueryFunctionContext) => Promise<D>) | SkipToken
+  readonly retry: (failureCount: number, error: ReactorError<E>) => boolean
+}
+
+interface ReadHandleBase<
+  A extends readonly unknown[],
+  D,
+  E,
+> extends ReadHandle {
+  /** Call the method now, as the current caller. Resolves with the data or throws `ReactorError<E>`. */
+  (args: A): Promise<D>
+  /** Query options keyed by network, caller principal, canister, method and encoded args. */
+  queryOptions(args: A | SkipToken): HandleQueryOptions<D, E>
+  /** This method's key for `args`, or the prefix of every key of this method (current caller) without. */
+  queryKey(args?: A): QueryKey
+}
+
+export interface QueryHandle<
+  A extends readonly unknown[],
+  D,
+  E,
+> extends ReadHandleBase<A, D, E> {
+  readonly mode: "query"
+  /** Run the query as a replicated (update) call, so the reply is certified. Slower. */
+  certified(args: A): Promise<D>
+}
+
+export interface CompositeQueryHandle<
+  A extends readonly unknown[],
+  D,
+  E,
+> extends ReadHandleBase<A, D, E> {
+  readonly mode: "composite_query"
+}
+
+/** What a write's `mutationOptions` accepts. There is deliberately no `retry`. */
+export interface MutationConfig<A, D, E> {
+  /**
+   * Reads this write can change. They are invalidated after a success, and
+   * after a failure whose `mayHaveExecuted` is true (outcome unknown).
+   */
+  readonly invalidates?: readonly ReadHandle[]
+  readonly onSuccess?: (data: D, args: A) => unknown
+  readonly onError?: (error: ReactorError<E>, args: A) => unknown
+  readonly onSettled?: (
+    data: D | undefined,
+    error: ReactorError<E> | null,
+    args: A
+  ) => unknown
+}
+
+/** Options for `useMutation`. Retries only a `not_delivered` failure. */
+export interface HandleMutationOptions<A, D, E> {
+  readonly mutationKey: QueryKey
+  readonly mutationFn: (args: A) => Promise<D>
+  readonly retry: (failureCount: number, error: ReactorError<E>) => boolean
+  readonly onSuccess: (
+    data: D,
+    args: A,
+    onMutateResult: unknown,
+    context: MutationFunctionContext
+  ) => Promise<void>
+  readonly onError: (
+    error: ReactorError<E>,
+    args: A,
+    onMutateResult: unknown,
+    context: MutationFunctionContext
+  ) => Promise<void>
+  readonly onSettled: (
+    data: D | undefined,
+    error: ReactorError<E> | null,
+    args: A,
+    onMutateResult: unknown,
+    context: MutationFunctionContext
+  ) => Promise<void>
+}
+
+export interface UpdateHandle<A extends readonly unknown[], D, E> {
+  readonly mode: "update" | "oneway"
+  readonly method: string
+  readonly canisterId: string
+  /**
+   * Call the method now, as the current caller. Refused before sending
+   * (`unauthenticated`) when not signed in. Re-sent only after a
+   * `not_delivered` failure.
+   */
+  (args: A): Promise<D>
+  mutationOptions(
+    config?: MutationConfig<A, D, E>
+  ): HandleMutationOptions<A, D, E>
+}
+
+type HandleFor<Mode, F> = Mode extends "query"
+  ? QueryHandle<HandleArgs<F> & readonly unknown[], HandleData<F>, HandleErr<F>>
+  : Mode extends "composite_query"
+    ? CompositeQueryHandle<
+        HandleArgs<F> & readonly unknown[],
+        HandleData<F>,
+        HandleErr<F>
+      >
+    : UpdateHandle<
+        HandleArgs<F> & readonly unknown[],
+        HandleData<F>,
+        HandleErr<F>
+      >
+
+/** One handle per method, typed by the method's mode. */
+export type Canister<A extends ActorShape, M extends ModeMap<A>> = {
+  readonly [K in keyof M & keyof A & string]: HandleFor<M[K], A[K]>
+}

package/evals/conditions/v4-proto/lib/test/runtime.test.ts

@@ -0,0 +1,170 @@
+// @vitest-environment node
+//
+// Runtime checks of the prototype itself against the harness's fake replica.
+// Not a hidden test: it tests the library, not a solution.
+//
+//   cd evals/conditions/v4-proto && node node_modules/vitest/vitest.mjs run --config lib/test/vitest.config.mjs
+import { afterEach, beforeEach, expect, it } from "vitest"
+import { AnonymousIdentity } from "@icp-sdk/core/agent"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import { QueryClient } from "@tanstack/query-core"
+import { actor, type Actor } from "../../starter/src/generated/icrc1"
+import { LedgerService } from "../../starter/src/generated/icrc1.service"
+import {
+  createClient,
+  defineService,
+  isReactorError,
+  principal,
+} from "../src/index"
+import { createWorld, type World } from "#harness/world"
+import { MINTER } from "#harness/fake-ledger"
+
+let world: World
+let alice: Ed25519KeyIdentity
+beforeEach(() => {
+  world = createWorld()
+  alice = Ed25519KeyIdentity.generate()
+  world.own(alice.getPrincipal().toText())
+  world.ledger.setBalance(alice.getPrincipal().toText(), 5_000_000_000n)
+})
+afterEach(() => world.restore())
+
+const ledgerAs = (identity?: Ed25519KeyIdentity | AnonymousIdentity) =>
+  createClient({
+    network: { host: world.host, rootKey: world.rootKey, name: "test" },
+    identity,
+  }).canister(LedgerService, { id: world.ledgerId })
+
+const transferArg = (to: string, amount: bigint) => ({
+  to: { owner: principal(to), subaccount: null },
+  amount,
+  fee: null,
+  memo: null,
+  from_subaccount: null,
+  created_at_time: null,
+})
+
+it("defineService refuses a mode map that disagrees with the schema", () => {
+  expect(() =>
+    defineService<Actor>()(actor, {
+      icrc1_balance_of: "update",
+      icrc1_decimals: "query",
+      icrc1_fee: "query",
+      icrc1_metadata: "query",
+      icrc1_minting_account: "query",
+      icrc1_name: "query",
+      icrc1_supported_standards: "query",
+      icrc1_symbol: "query",
+      icrc1_total_supply: "query",
+      icrc1_transfer: "update",
+    })
+  ).toThrow(/icrc1_balance_of is declared update but the schema says query/)
+})
+
+it("keys carry network, caller, canister, method and the encoded args", () => {
+  const ledger = ledgerAs(alice)
+  const owner = principal(alice.getPrincipal().toText())
+  const key = ledger.icrc1_balance_of.queryKey([{ owner, subaccount: null }])
+  expect(key.slice(0, 6)).toEqual([
+    "ic-reactor",
+    "test",
+    alice.getPrincipal().toText(),
+    world.ledgerId,
+    "icrc1_balance_of",
+    "query",
+  ])
+  expect(key[6]).toMatch(/^4449444c/) // hex of "DIDL"
+  expect(
+    ledgerAs().icrc1_balance_of.queryKey([{ owner, subaccount: null }])[2]
+  ).toBe("2vxsx-fae")
+})
+
+it("decodes principals in replies to text", async () => {
+  const minting = await ledgerAs().icrc1_minting_account([])
+  expect(minting).toEqual({ owner: MINTER, subaccount: null })
+  expect(typeof minting?.owner).toBe("string")
+})
+
+it("reads through queryOptions and certified()", async () => {
+  const ledger = ledgerAs(alice)
+  const owner = principal(alice.getPrincipal().toText())
+  const qc = new QueryClient()
+  await expect(
+    qc.fetchQuery(
+      ledger.icrc1_balance_of.queryOptions([{ owner, subaccount: null }])
+    )
+  ).resolves.toBe(5_000_000_000n)
+  await expect(
+    ledger.icrc1_balance_of.certified([{ owner, subaccount: null }])
+  ).resolves.toBe(5_000_000_000n)
+  expect(world.calls("icrc1_balance_of")).toHaveLength(1) // certified() is a replicated call
+})
+
+it("refuses a write from an anonymous caller before sending", async () => {
+  const error = await ledgerAs(new AnonymousIdentity())
+    .icrc1_transfer([transferArg(alice.getPrincipal().toText(), 1n)])
+    .catch((e: unknown) => e)
+  expect(isReactorError(error) && error.kind).toBe("unauthenticated")
+  expect(world.calls()).toHaveLength(0)
+})
+
+it("refuses invalid principal text as invalid_args before sending", async () => {
+  const bad = {
+    owner: "not-a-principal" as ReturnType<typeof principal>,
+    subaccount: null,
+  }
+  const error = await ledgerAs(alice)
+    .icrc1_balance_of([bad])
+    .catch((e: unknown) => e)
+  expect(isReactorError(error) && error.kind).toBe("invalid_args")
+  expect(world.queries()).toHaveLength(0)
+})
+
+it("unwraps Err as a typed canister_err", async () => {
+  world.ledger.setBalance(alice.getPrincipal().toText(), 5n)
+  const error = await ledgerAs(alice)
+    .icrc1_transfer([transferArg(MINTER, 1_000n)])
+    .catch((e: unknown) => e)
+  if (!isReactorError(error)) throw error
+  expect(error.kind).toBe("canister_err")
+  expect(error.mayHaveExecuted).toBe(false)
+  expect(error.err).toEqual({
+    tag: "InsufficientFunds",
+    value: { balance: 5n },
+  })
+})
+
+it("classifies rejects by who produced them, and a lost reply as outcome_unknown", async () => {
+  // Code 3: rejected by the system, no ledger code ran.
+  world.ledger.rejectTransfersWith = 3
+  const missing = await ledgerAs(alice)
+    .icrc1_transfer([transferArg(MINTER, 1n)])
+    .catch((e: unknown) => e)
+  expect(
+    isReactorError(missing) && [
+      missing.kind,
+      missing.mayHaveExecuted,
+      missing.rejectCode,
+    ]
+  ).toEqual(["rejected", false, 3])
+  world.ledger.rejectTransfersWith = null
+  // Code 5: the ledger's own code trapped; it may have committed before.
+  world.ledger.rejectTransfersWith = 5
+  const trap = await ledgerAs(alice)
+    .icrc1_transfer([transferArg(MINTER, 1n)])
+    .catch((e: unknown) => e)
+  expect(
+    isReactorError(trap) && [trap.kind, trap.mayHaveExecuted, trap.rejectCode]
+  ).toEqual(["rejected", true, 5])
+  world.ledger.rejectTransfersWith = null
+  world.loseReplyOf("icrc1_transfer", 3)
+  const lost = await ledgerAs(alice)
+    .icrc1_transfer([transferArg(MINTER, 1n)])
+    .catch((e: unknown) => e)
+  expect(isReactorError(lost) && [lost.kind, lost.mayHaveExecuted]).toEqual([
+    "outcome_unknown",
+    true,
+  ])
+  expect(world.distinctCalls("icrc1_transfer")).toHaveLength(3)
+  expect(world.ledger.transfers).toHaveLength(1)
+}, 30_000)

package/evals/conditions/v4-proto/lib/test/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "..",
+    "types": [],
+    "noUnusedLocals": false
+  },
+  "include": ["types.test-d.ts", "../src"]
+}