@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/evals/conditions/v4/README.md

@@ -0,0 +1,106 @@
+# The `v4` condition
+
+ic-reactor 4 as published (issue #786): `@ic-reactor/core` and
+`@ic-reactor/react`, either packed from this repository (`node setup.mjs`,
+as the 4.0.0-beta.1 gate did) or downloaded from npm as published
+(`node setup.mjs --v4-from npm:4.0.0-beta.1`, as the GA gate does), with
+`@candid-core/schema` 0.3.0-beta.1 and the module `@candid-core/cli`
+0.2.0-beta.1 generates from `harness/icrc1.did`. Agents get the core
+tarball's `llms.txt` as their only documentation. It is the condition of the
+4.0.0-beta.1 gate (`PREREGISTRATION.md`, Addendum 3) and of the GA gate
+(Addendum 4), and runs only when named (`drive.mjs --condition v4`); the
+default matrix is the four conditions of the pilots.
+
+| File                             | What it is                                                                                                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `condition.json`                 | the `{{LIBRARY}}` line and the docs list                                                                                                                               |
+| `package.json`                   | what an agent may import. `workspace:*` marks a package setup installs from a tarball (packed here, or from npm); everything else is pinned as in the other conditions |
+| `starter/src/generated/icrc1.ts` | the CLI's output, unedited (setup.mjs regenerates it)                                                                                                                  |
+| `docs/llms.txt`                  | the core tarball's `llms.txt` (setup.mjs copies it): the published 4.0.0-beta.1 guide, 1,974 words, sha256 `a07b846a…4342`                                             |
+| `node_modules/` (not tracked)    | the scorer's install: a copy of `.ship/v4/node_modules`, with `@icp-sdk/core` linked to evals' own (step 6 below)                                                      |
+| `PORTING.md`                     | the work list for porting the v4-proto references and faulty solutions to this condition                                                                               |
+
+The starter module is generated with:
+
+```bash
+npx --yes @candid-core/cli@0.2.0-beta.1 gen evals/harness/icrc1.did -o <dir>
+```
+
+run in a scratch directory (so evals' own `@candid-core/cli` 0.1.0 is not
+picked up), keeping `<dir>/icrc1.ts` only; the CLI's `icrc1.envelope.json`
+(the contract the module came from) is not something an app imports.
+
+## How setup.mjs builds it
+
+1. Gets the two tarballs, from one of two sources (`--v4-from`):
+   - `tree` (the default): builds `@ic-reactor/core` and `@ic-reactor/react`
+     from this repository (`corepack pnpm --filter … build`, at the
+     repository root) and packs them with `corepack pnpm --filter … pack
+--pack-destination <tmp>`, which rewrites `workspace:` ranges as a
+     release does. The root workspace must be installed (`corepack pnpm
+install` at the repository root).
+   - `npm:<version>`: downloads the published tarballs with `npm pack
+<name>@<version>`, and refuses them unless each one's sha512 is the
+     `dist.integrity` that `V4_NPM_RELEASES` in `harness/ship.mjs` pins and
+     the registry still records (`npm view <name>@<version> dist.integrity`).
+     Only 4.0.0-beta.1 is pinned:
+
+     | Package                          | `dist.integrity`                                                                                  |
+     | -------------------------------- | ------------------------------------------------------------------------------------------------- |
+     | `@ic-reactor/core@4.0.0-beta.1`  | `sha512-qvxoX5SJa0ubJumLRctpYx9SqFynu3PXKO9E2fJpiDMKrb6y6rlxncR6XBALqjDdFi8UVYJxWXMhqG8Va/6alg==` |
+     | `@ic-reactor/react@4.0.0-beta.1` | `sha512-U0Bvz6qRmrnDCXCd27T28EJ3SNO5Z3eu2oENrHE5CMg6v36AzcjDWgwSzGTL+f8LDxGaFhvcuCGVAEYypNpCMg==` |
+
+     The repository's workspace is not built and need not be installed.
+
+   Every later step is the same for both sources.
+
+2. Installs the tarballs, from `.ship/v4/tarballs/`, with every pinned
+   dependency into `.ship/v4/node_modules` as a flat npm install: no
+   workspace links, no pnpm store paths.
+3. Refuses the tree, deleting it, when the core tarball's `llms.txt` holds a
+   hidden-test name or distinctive literal (`harness/check-docs.mjs`) or the
+   packages' code names a hidden test (`harness/ship.mjs`).
+4. Copies that `llms.txt` to `docs/llms.txt`, then cuts both packages to
+   `package.json` + `dist/`: their READMEs and sources would be
+   documentation beyond the one guide.
+5. Runs the checks every condition gets (no unmet dependency; no repository
+   path or hidden-test path anywhere in the shipped `node_modules`).
+6. Copies `.ship/v4/node_modules` to `conditions/v4/node_modules` for the
+   scorer. `conditions/v4` is not a member of evals' pnpm workspace: its
+   ic-reactor packages exist only as tarballs that setup makes. In that
+   copy `@icp-sdk/core` is a link to evals' own `node_modules/@icp-sdk/core`
+   (`V4_SHARED_WITH_WORLD` in `harness/ship.mjs`), after setup checks that
+   evals', the ship's and the pin's versions agree (6.1.0). The hidden
+   tests' world (`harness/world.ts`, `fake-auth.ts`, and `installFakeReplica`
+   from `@ic-reactor/core` 3.13.0) imports `@icp-sdk/core` from evals'
+   install; a plain copy would give the solution and the hidden tests a
+   second instance, and every class check across the two would fail in
+   scoring only. With the copy, fake-auth's signed-out `AnonymousIdentity`
+   was not an `instanceof AnonymousIdentity` for the solution; with the
+   link it is, as in the four other conditions (one pnpm store) and in an
+   agent's own run (one npm install).
+
+7. Writes `.ship/v4/source.json`: the source (`npm` and the version, or
+   `tree` and the commit), the installed versions, each tarball's integrity,
+   and the guide's word count and sha256. `drive.mjs` prints it in a dry run
+   and keeps it in `plan.json` (`v4Source`).
+
+`harness/ship.test.mjs` checks the result (the cut packages, no repository
+path, the single guide byte for byte as the core tarball holds it, the
+recorded source against the tarballs and npm's lockfile, the scorer's copy
+and its one `@icp-sdk/core`, the assembled starter), the refusals on seeded
+files and on local tarball fixtures (offline), and that the pins are what
+the registry records (skipped, with the reason, when it cannot be reached).
+
+## Status
+
+The references and faulty solutions are ported (`PORTING.md` records how):
+`tasks/<task>/solutions/v4/reference` and `reference-module-scope` for both
+tasks, the six faulty solutions ported from v4-proto
+(`tasks/*/faulty/v4-*`), each failing exactly the tests its v4-proto
+original fails, and one of v4's own,
+`node-tool/faulty/v4-anonymous-identity-sent`, for a trap the real library
+opens (an explicit `AnonymousIdentity` is sent). `node gate.mjs --require
+v4` (what Addenda 3 and 4 run) reports 56 of 56 with no cell skipped, on
+the tree packed for Addendum 3 and on the published 4.0.0-beta.1
+(`--v4-from npm:4.0.0-beta.1`, 2026-10-05).

package/evals/conditions/v4/condition.json

@@ -0,0 +1,5 @@
+{
+  "name": "v4",
+  "library": "Available library: IC Reactor 4 — `@ic-reactor/core`, a client that calls canisters and builds TanStack Query options, and `@ic-reactor/react` for React — over the module `candid-core-cli gen` generated from the ledger's `.did` in `src/generated/icrc1.ts` (`@candid-core/schema` 0.3.0-beta.1), with `@icp-sdk/core`, `@icp-sdk/auth` and TanStack Query (`@tanstack/react-query`, `@tanstack/query-core`). Its documentation is in `docs/`; read it before you start.",
+  "docs": ["docs/llms.txt"]
+}

package/evals/conditions/v4/docs/llms.txt

@@ -0,0 +1,323 @@
+# @ic-reactor/core
+
+> How to call Internet Computer canisters with a module `candid-core-cli gen`
+> generated from a `.did`, a client from `@ic-reactor/core`, and TanStack
+> Query. The client applies the rules a hand-written integration must get
+> right; this guide names the call for each.
+
+Applies to `@ic-reactor/core` 4.0.0-beta.1.
+
+## Imports
+
+```ts
+import { createClient, formatUnits, isReactorError, parseUnits } from "@ic-reactor/core"
+import { ReactorProvider, useAuth, useClient } from "@ic-reactor/react"
+import { isPrincipal, principal, type Principal } from "@candid-core/schema"
+import { skipToken, useMutation, useQuery } from "@tanstack/react-query"
+import { actor, type Actor } from "./generated/icrc1"
+```
+
+One import path per name: Candid values only from `@candid-core/schema`,
+`skipToken` and the hooks only from TanStack Query.
+
+The generated module (from `candid-core-cli gen` or `@ic-reactor/vite-plugin`;
+do not edit it) exports a type and schema per Candid type, the service schema
+`actor`, and `type Actor`.
+
+## Setup
+
+```ts
+// src/ledger.ts
+import { createClient } from "@ic-reactor/core"
+import { actor, type Actor } from "./generated/icrc1"
+
+export const client = createClient({ network: "ic", identity: "anonymous" })
+export const ledger = client.canister<Actor>(actor, { id: "ryjl3-tyaaa-aaaaa-aaaba-cai" })
+```
+
+`client.canister()` returns the same object each time: safe in render.
+
+`network` and the root key:
+
+- `"ic"`: mainnet (`https://icp-api.io`) and its built-in root key.
+- `"local"`: `http://127.0.0.1:4943`; its root key is fetched.
+- `{ host, rootKey }`: any other replica. A given `rootKey` is used, never
+  fetched; without one, it is fetched only from a local `host` (`localhost`,
+  `127.0.0.1`, `[::1]`). Never fetch one from any other host.
+- `"env"`: the page's network. Canisters can be named, `{ name: "backend" }`,
+  from the `ic_env` cookie, believed only on a local replica or with
+  `allowEnvConfig: true`. A server has no cookie: use `{ id }` there.
+
+Who calls (exactly one):
+
+- `identity`: a fixed `Identity` (scripts, servers, tests), or `"anonymous"`,
+  read-only: every update is refused before sending. A
+  `new AnonymousIdentity()` signs writes, so map one you are handed:
+  `identity: id && !id.getPrincipal().isAnonymous() ? id : "anonymous"`.
+- `auth: () => new AuthClient()` (`@icp-sdk/auth/client`): users sign in and
+  out. The factory runs once, in a browser only.
+
+Who is calling, and may they write:
+
+| Question               | Answer                                                                    |
+| ---------------------- | ------------------------------------------------------------------------- |
+| the caller's principal | `useAuth().principal`, `client.caller()` (`"2vxsx-fae"` unless signed in) |
+| may a write be sent    | `useAuth().status === "signed-in"`; the client refuses the rest itself    |
+| when did it change     | `useAuth()` re-renders; `client.subscribe(fn)`                            |
+
+The client keeps one agent per principal: a call goes out as the principal
+current when it was made, or not at all.
+
+One client per browser tab, or per request on a server. In React,
+`<ReactorProvider client={() => createClient(...)}>` builds it once per
+mounted tree and disposes it on unmount; a module-scope client passed as
+`client={() => client}` is borrowed, never disposed. Inside, `useClient()`
+returns it (as anonymous while hydrating) and `useAuth()` returns
+`{ status, principal, signIn, signOut }`, `"anonymous"` on a server and in a
+hydrating page's first render.
+
+Any other sign-in source becomes an `AuthLike`:
+
+```ts
+// src/auth-like.ts
+import type { AuthLike } from "@ic-reactor/core"
+import type { Identity } from "@icp-sdk/core/agent"
+
+export interface SignInSource {
+  getIdentity(): Identity // anonymous while signed out
+  isAuthenticated(): boolean
+  login(): Promise<void>
+  logout(): Promise<void>
+  subscribe(listener: () => void): () => void
+}
+
+export function toAuthLike(source: SignInSource): AuthLike {
+  const signedIn = () =>
+    source.isAuthenticated() && !source.getIdentity().getPrincipal().isAnonymous()
+  return {
+    getPrincipal: () => (signedIn() ? source.getIdentity().getPrincipal() : undefined),
+    getStatus: () => ({ state: signedIn() ? "signed-in" : "signed-out" }),
+    getIdentity: async () => source.getIdentity(),
+    subscribe: (listener) => source.subscribe(listener),
+    signIn: () => source.login(),
+    signOut: () => source.logout(),
+  }
+}
+```
+
+## Values
+
+Methods use the generated types:
+
+| Candid                                   | Value                                          |
+| ---------------------------------------- | ---------------------------------------------- |
+| `nat`, `int`, `nat64`, `int64`           | `bigint` (never `number`)                      |
+| `nat8`..`nat32`, `int8`..`int32`, floats | `number`                                       |
+| `text`, `bool`                           | `string`, `boolean`                            |
+| `principal`                              | `Principal`: branded principal text            |
+| `blob` / `vec nat8`                      | `Uint8Array`                                   |
+| `opt T`                                  | `T \| null` (the property is always present)   |
+| `opt opt T`, `opt null`                  | `{ some: T \| null } \| null`, `{ some: null } \| null` |
+| `vec T`                                  | `T[]`                                          |
+| `record { a : T }`                       | `{ a: T }`, every field present                |
+| `variant { A : T; B }`                   | `{ tag: "A"; value: T } \| { tag: "B" }`       |
+
+Make principals from user input with `principal(text)`, which throws a
+`TypeError` for invalid text: catch it and refuse the input. In render, test with `isPrincipal(text)` first.
+
+Direct calls take the parameters `type Actor` lists; the builders below take
+them as one value: nothing for none, the value for one, a tuple `[a, b]` for
+more.
+
+Token amounts are base units:
+
+```ts
+/// <reference lib="es2023.intl" />
+import { formatUnits, parseUnits } from "@ic-reactor/core"
+
+const units = parseUnits("1.5", 8) // 150000000n
+const text = formatUnits(units, 8, { minFractionDigits: 8 }) // "1.50000000"
+const local = new Intl.NumberFormat(undefined, { maximumFractionDigits: 8 }).format(
+  text as Intl.StringNumericLiteral // the cast needs lib ES2023
+)
+```
+
+`parseUnits` throws for text that is not a plain decimal (`"1e3"`, `"1,5"`),
+a negative, or excess fraction digits: refuse that input. A cap is the Candid
+type's: a `nat64` field refuses 2^64 at encoding (`invalid_args`); an ICRC-1
+`amount` is a `nat`, with none.
+
+### Results
+
+A method whose result is `variant { Ok : T; Err : E }` resolves with the `Ok`
+value; `Err` rejects as kind `"canister_err"`, with the `Err` value in `err`
+(typed on a query's or mutation's `error`).
+
+## Reads
+
+```tsx
+import type { Principal } from "@candid-core/schema"
+import { formatUnits } from "@ic-reactor/core"
+import { useClient } from "@ic-reactor/react"
+import { skipToken, useQuery } from "@tanstack/react-query"
+import { actor, type Actor } from "./generated/icrc1"
+
+export function Balance({ owner }: { owner: Principal | undefined }) {
+  const client = useClient()
+  const ledger = client.canister<Actor>(actor, { id: "ryjl3-tyaaa-aaaaa-aaaba-cai" })
+  const balance = useQuery(
+    client.queryOptions(ledger, "icrc1_balance_of", owner ? { owner, subaccount: null } : skipToken)
+  )
+  return <p>{balance.data === undefined ? "…" : formatUnits(balance.data, 8)}</p>
+}
+```
+
+`skipToken` stands in for arguments not known yet;
+arguments that do not encode make the read reject `invalid_args`.
+
+Keys are `["ic-reactor", network, caller, canisterId, method, args]`, so one
+principal's cached answer is never served to another: after a sign-in,
+sign-out or switch, the new caller's key is empty (`data` is `undefined`)
+until it loads, and a read made for the previous caller never lands in it.
+Keep it so: build the options in render, and add nothing that carries data
+across keys (`placeholderData: keepPreviousData`, cross-key `initialData`).
+`client.queryKey(ledger, method?, args?)` gives keys for the cache.
+
+Reads retry transient failures (never on a server). Spread to add options:
+`{ ...client.queryOptions(...), staleTime }`.
+
+`queryOptions` throws for an update method; one that answers the same however
+often it runs (ckBTC's `get_btc_address`) opts in with a fourth argument,
+`{ update: "idempotent" }`. The target `{ id, certified: true }` certifies
+`query` replies.
+
+## Writes
+
+```tsx
+import { useClient } from "@ic-reactor/react"
+import { useMutation } from "@tanstack/react-query"
+import { actor, type Actor, type TransferArg } from "./generated/icrc1"
+
+export function Send({ arg }: { arg: TransferArg }) {
+  const client = useClient()
+  const ledger = client.canister<Actor>(actor, { id: "ryjl3-tyaaa-aaaaa-aaaba-cai" })
+  const transfer = useMutation(client.mutationOptions(ledger, "icrc1_transfer"))
+  return <button disabled={transfer.isPending} onClick={() => transfer.mutate(arg)}>Send</button>
+}
+```
+
+- The mutation invalidates the canister's reads, for every caller, after a
+  success, a `canister_err` and a failure that may have executed. Nothing
+  else is needed after an unknown outcome.
+  A third argument, `{ invalidates: [canister, [canister, "method"]] }`,
+  names other reads; `[]`, none. To add an `onSettled`, call the client's
+  from yours.
+- Do not retry a write. `retry` is `false`; keep it. The client itself
+  re-sends an update, at most twice, only after a failure proving the canister
+  never got it (reject code 2, status 429); any other failure is final.
+- A write is sent as whoever is signed in when it runs. If nobody is, the
+  client refuses it (`unauthenticated`) before calling anything.
+- Call update methods only from `useMutation` or directly, never from
+  `useQuery`; call query methods from `useQuery` or directly.
+
+## Errors
+
+Every rejection is a `ReactorError`: test with `isReactorError(error)`, then
+read `kind` and `mayHaveExecuted`. A failed write either certainly had no
+effect, or may have executed:
+
+| What happened                                                                   | `kind`                            | May have executed |
+| ------------------------------------------------------------------------------- | --------------------------------- | ----------------- |
+| refused before sending: arguments that do not encode, a write while signed out  | `invalid_args`, `unauthenticated` | no                |
+| HTTP 4xx except 408 (429 included): the replica or a boundary node refused it    | `not_delivered`                   | no                |
+| reject code 1, 2 (transient) or 3: rejected before any canister code ran         | `rejected` (2: `not_delivered`)   | no                |
+| reject code 4 or 5: the canister rejected or trapped, maybe after changing state | `rejected`                        | yes (a write)     |
+| a sent write got no trustworthy answer: network drop, timeout, 5xx, 408          | `outcome_unknown`                 | yes               |
+| a reply that did not decode                                                      | `invalid_reply`                   | yes (a write)     |
+| the canister returned `Err`                                                      | `canister_err`                    | no                |
+| the caller changed, or the call was aborted                                      | `cancelled`                       | no (an aborted write: yes) |
+
+On the management canister (`aaaaa-aa`), codes 1 to 3 prove nothing: a write
+there may have executed. A query changes nothing, so a failed read never "may
+have executed".
+
+## Outside React
+
+```ts
+import { principal } from "@candid-core/schema"
+import { isReactorError, parseUnits } from "@ic-reactor/core"
+import { client, ledger } from "./ledger"
+
+const account = { owner: principal("aaaaa-aa"), subaccount: null }
+
+const cached = await client.queryClient.fetchQuery(client.queryOptions(ledger, "icrc1_balance_of", account))
+await client.queryClient.invalidateQueries({ queryKey: client.queryKey(ledger) })
+const fresh = await ledger.icrc1_balance_of(account)
+
+try {
+  const arg = { to: account, amount: parseUnits("1.5", 8), fee: null, memo: null, from_subaccount: null, created_at_time: null }
+  await ledger.icrc1_transfer(arg) // refused unless `client` was built with an Identity
+} catch (error) {
+  if (!isReactorError(error)) throw error
+  console.error(error.mayHaveExecuted ? "unknown outcome: re-read first" : error.kind)
+}
+```
+
+Direct calls never touch a cache. To test, `createTestClient()` from
+`@ic-reactor/core/testing` gives a real client over an in-memory replica with
+a sign-in you control.
+
+## Example
+
+```tsx
+import { principal } from "@candid-core/schema"
+import { createClient } from "@ic-reactor/core"
+import { ReactorProvider, useAuth, useClient } from "@ic-reactor/react"
+import { skipToken, useMutation, useQuery } from "@tanstack/react-query"
+import { toAuthLike, type SignInSource } from "./auth-like"
+import { actor, type Actor } from "./generated/backend"
+
+export function App({ auth }: { auth: SignInSource }) {
+  return (
+    <ReactorProvider client={() => createClient({ network: "ic", auth: () => toAuthLike(auth) })}>
+      <Profile />
+    </ReactorProvider>
+  )
+}
+
+function Profile() {
+  const client = useClient()
+  const { status, principal: caller, signIn } = useAuth()
+  const backend = client.canister<Actor>(actor, { id: "rrkah-fqaaa-aaaaa-aaaaq-cai" })
+  const me = principal(caller)
+  const signedIn = status === "signed-in"
+  const profile = useQuery(client.queryOptions(backend, "get_profile", signedIn ? me : skipToken))
+  const rename = useMutation(client.mutationOptions(backend, "set_name"))
+
+  if (!signedIn) return <button onClick={() => void signIn()}>Sign in</button>
+  if (profile.data === undefined) return <p>Loading…</p>
+  return (
+    <>
+      <p>{profile.data.name}</p>
+      <button disabled={rename.isPending} onClick={() => rename.mutate([me, "Ada"])}>Rename</button>
+      {rename.error && <p>{rename.error.mayHaveExecuted ? "Unknown outcome" : rename.error.message}</p>}
+    </>
+  )
+}
+```
+
+## Do not
+
+- Cast text to `Principal`: use `principal(text)`.
+- Convert `bigint` values to `number`: use `parseUnits` and `formatUnits`.
+- Add `retry` to a write (`{ ...client.mutationOptions(...), retry: 3 }`
+  compiles), or call a write from `useQuery`: TanStack Query may run a query's
+  function again whenever it refetches, and every run of an update executes
+  again.
+- Write a query key by hand (it leaves the caller out), or carry data across
+  keys (`keepPreviousData`, cross-key `initialData`).
+- Build agents yourself, a client per render, or one client for every user of
+  a server.
+- Send a write as the anonymous identity: pass `identity: "anonymous"`, never
+  an `AnonymousIdentity` you were handed.
+- Treat every failed write as "not executed": read `mayHaveExecuted`.

package/evals/conditions/v4/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "condition-v4",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@candid-core/schema": "0.3.0-beta.1",
+    "@ic-reactor/core": "workspace:*",
+    "@ic-reactor/react": "workspace:*",
+    "@icp-sdk/auth": "10.0.1",
+    "@icp-sdk/core": "6.1.0",
+    "@noble/curves": "2.4.0",
+    "@tanstack/query-core": "5.104.0",
+    "@tanstack/react-query": "5.104.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.1",
+    "typescript": "6.0.3",
+    "vitest": "5.0.2"
+  }
+}

package/evals/conditions/v4/starter/src/generated/icrc1.ts

@@ -0,0 +1,78 @@
+// Generated by candid-core-ts from a candid-core Contract. Do not edit.
+import * as $ from "@candid-core/schema";
+
+type $Account = { owner: $.Principal; subaccount: $Subaccount | null };
+const $Account: $.Schema<$Account> = $.c.rec(() => $.c.record({ owner: $.c.principal, subaccount: $.c.opt($Subaccount) }));
+export { $Account as Account };
+
+type $BlockIndex = bigint;
+const $BlockIndex: $.Schema<$BlockIndex> = $.c.rec(() => $.c.nat);
+export { $BlockIndex as BlockIndex };
+
+/** Number of nanoseconds between two [Timestamp]s. */
+type $Duration = bigint;
+/** Number of nanoseconds between two [Timestamp]s. */
+const $Duration: $.Schema<$Duration> = $.c.rec(() => $.c.nat64);
+export { $Duration as Duration };
+
+/** The initialization parameters of the Ledger */
+type $InitArgs = { token_symbol: string; transfer_fee: bigint; metadata: Array<[string, $Value]>; minting_account: $Account; initial_balances: Array<[$Account, bigint]>; archive_options: { num_blocks_to_archive: bigint; trigger_threshold: bigint; max_message_size_bytes: bigint | null; cycles_for_archive_creation: bigint | null; node_max_memory_size_bytes: bigint | null; controller_id: $.Principal }; token_name: string };
+/** The initialization parameters of the Ledger */
+const $InitArgs: $.Schema<$InitArgs> = $.c.rec(() => $.c.record({ token_symbol: $.c.text, transfer_fee: $.c.nat64, metadata: $.c.vec($.c.tuple([$.c.text, $Value])), minting_account: $Account, initial_balances: $.c.vec($.c.tuple([$Account, $.c.nat64])), archive_options: $.c.record({ num_blocks_to_archive: $.c.nat64, trigger_threshold: $.c.nat64, max_message_size_bytes: $.c.opt($.c.nat64), cycles_for_archive_creation: $.c.opt($.c.nat64), node_max_memory_size_bytes: $.c.opt($.c.nat64), controller_id: $.c.principal }), token_name: $.c.text }));
+export { $InitArgs as InitArgs };
+
+type $LedgerArg = { tag: "Upgrade"; value: $UpgradeArgs | null } | { tag: "Init"; value: $InitArgs };
+const $LedgerArg: $.Schema<$LedgerArg> = $.c.rec(() => $.c.variant({ Upgrade: $.c.opt($UpgradeArgs), Init: $InitArgs }));
+export { $LedgerArg as LedgerArg };
+
+type $Subaccount = Uint8Array;
+const $Subaccount: $.Schema<$Subaccount> = $.c.rec(() => $.c.blob());
+export { $Subaccount as Subaccount };
+
+/** Number of nanoseconds since the UNIX epoch in UTC timezone. */
+type $Timestamp = bigint;
+/** Number of nanoseconds since the UNIX epoch in UTC timezone. */
+const $Timestamp: $.Schema<$Timestamp> = $.c.rec(() => $.c.nat64);
+export { $Timestamp as Timestamp };
+
+type $Tokens = bigint;
+const $Tokens: $.Schema<$Tokens> = $.c.rec(() => $.c.nat);
+export { $Tokens as Tokens };
+
+type $TransferArg = { to: $Account; fee: bigint | null; memo: $Subaccount | null; from_subaccount: $Subaccount | null; created_at_time: bigint | null; amount: bigint };
+const $TransferArg: $.Schema<$TransferArg> = $.c.rec(() => $.c.record({ to: $Account, fee: $.c.opt($.c.nat), memo: $.c.opt($Subaccount), from_subaccount: $.c.opt($Subaccount), created_at_time: $.c.opt($.c.nat64), amount: $.c.nat }));
+export { $TransferArg as TransferArg };
+
+type $TransferError = { tag: "GenericError"; value: { message: string; error_code: bigint } } | { tag: "TemporarilyUnavailable" } | { tag: "BadBurn"; value: { min_burn_amount: bigint } } | { tag: "Duplicate"; value: { duplicate_of: bigint } } | { tag: "BadFee"; value: { expected_fee: bigint } } | { tag: "CreatedInFuture"; value: { ledger_time: bigint } } | { tag: "TooOld" } | { tag: "InsufficientFunds"; value: { balance: bigint } };
+const $TransferError: $.Schema<$TransferError> = $.c.rec(() => $.c.variant({ GenericError: $.c.record({ message: $.c.text, error_code: $.c.nat }), TemporarilyUnavailable: $.c.null, BadBurn: $.c.record({ min_burn_amount: $.c.nat }), Duplicate: $.c.record({ duplicate_of: $.c.nat }), BadFee: $.c.record({ expected_fee: $.c.nat }), CreatedInFuture: $.c.record({ ledger_time: $.c.nat64 }), TooOld: $.c.null, InsufficientFunds: $.c.record({ balance: $.c.nat }) }));
+export { $TransferError as TransferError };
+
+type $TransferResult = { tag: "Ok"; value: bigint } | { tag: "Err"; value: $TransferError };
+const $TransferResult: $.Schema<$TransferResult> = $.c.rec(() => $.c.variant({ Ok: $.c.nat, Err: $TransferError }));
+export { $TransferResult as TransferResult };
+
+type $UpgradeArgs = { token_symbol: string | null; transfer_fee: bigint | null; metadata: Array<[string, $Value]> | null; token_name: string | null };
+const $UpgradeArgs: $.Schema<$UpgradeArgs> = $.c.rec(() => $.c.record({ token_symbol: $.c.opt($.c.text), transfer_fee: $.c.opt($.c.nat64), metadata: $.c.opt($.c.vec($.c.tuple([$.c.text, $Value]))), token_name: $.c.opt($.c.text) }));
+export { $UpgradeArgs as UpgradeArgs };
+
+/** The value returned from the [icrc1_metadata] endpoint. */
+type $Value = { tag: "Int"; value: bigint } | { tag: "Nat"; value: bigint } | { tag: "Blob"; value: $Subaccount } | { tag: "Text"; value: string };
+/** The value returned from the [icrc1_metadata] endpoint. */
+const $Value: $.Schema<$Value> = $.c.rec(() => $.c.variant({ Int: $.c.int, Nat: $.c.nat, Blob: $Subaccount, Text: $.c.text }));
+export { $Value as Value };
+
+const $actor: $.Schema<$.Principal> = $.c.rec(() => $.c.service({ icrc1_balance_of: $.c.func([$Account], [$.c.nat], "query"), icrc1_decimals: $.c.func([], [$.c.nat8], "query"), icrc1_fee: $.c.func([], [$.c.nat], "query"), icrc1_supported_standards: $.c.func([], [$.c.vec($.c.record({ url: $.c.text, name: $.c.text }))], "query"), icrc1_metadata: $.c.func([], [$.c.vec($.c.tuple([$.c.text, $Value]))], "query"), icrc1_symbol: $.c.func([], [$.c.text], "query"), icrc1_minting_account: $.c.func([], [$.c.opt($Account)], "query"), icrc1_name: $.c.func([], [$.c.text], "query"), icrc1_total_supply: $.c.func([], [$.c.nat], "query"), icrc1_transfer: $.c.func([$TransferArg], [$TransferResult], "update") }));
+type $Actor = {
+  icrc1_balance_of: (arg0: $Account) => Promise<bigint>;
+  icrc1_decimals: () => Promise<number>;
+  icrc1_fee: () => Promise<bigint>;
+  icrc1_supported_standards: () => Promise<Array<{ url: string; name: string }>>;
+  icrc1_metadata: () => Promise<Array<[string, $Value]>>;
+  icrc1_symbol: () => Promise<string>;
+  icrc1_minting_account: () => Promise<$Account | null>;
+  icrc1_name: () => Promise<string>;
+  icrc1_total_supply: () => Promise<bigint>;
+  icrc1_transfer: (arg0: $TransferArg) => Promise<$TransferResult>;
+};
+export { $actor as actor, type $Actor as Actor };
+// Note: the actor is a service class; init args are install-time metadata not exposed here (issue #104).

package/evals/conditions/v4-proto/condition.json

@@ -0,0 +1,6 @@
+{
+  "name": "v4-proto",
+  "localVersion": "0.1.0",
+  "library": "Available library: `@ic-reactor/v4-proto` \u2014 typed per-method handles that produce TanStack Query options \u2014 over the module generated from the ledger's `.did` in `src/generated/` (use `LedgerService` from `src/generated/icrc1.service.ts`), with `@icp-sdk/core`, `@icp-sdk/auth` and TanStack Query (`@tanstack/react-query`, `@tanstack/query-core`). Its documentation is in `docs/`; read it before you start.",
+  "docs": ["docs/llms.txt"]
+}