Maintainer decisions needed after the 2026-09-23 hardening round

[b3hr4d]

Today's hardening round stopped wherever a fix would change public behaviour. Each entry gives the question, the options, the issue's or PR's recommendation if any, and the user-visible impact; the linked issue or PR holds the evidence. Items most likely to affect correctness lead each package. Held PRs #578, #599 and #600 are green and mergeable.

Three entries share one underlying question: may a state-changing update call be re-sent automatically? #622 (query hooks' default retries), #600 (a global mutation retry reaching execute()) and the remaining #564 item (the hook's retry on an update's call()) all follow from that rule, so deciding it first settles all three.

core

#578 (held PR) Should createPollingStrategy time out requests after 5 minutes by default?

• Options: 5 minutes, like the SDK (as shipped; timeoutMs: Infinity opts out); no default. No recommendation. Merging fixes core: the README's polling example times out every call after 5 minutes of uptime, and a shared createPollingStrategy leaks state between calls #563 (calls failing after 5 minutes of uptime) either way.
• Impact: a call polling past 5 minutes rejects instead of hanging, though the canister may still run it.

#647 Should fetchQuery() and factory .fetch() keep rejecting with TanStack's CancelledError, which is not a documented reactor error, when a sign-in or sign-out interrupts them?

• Options: (1) refetch under the new identity; (2) rethrow as CallError; (3) document it. The audit recommends 1.
• Impact: route loaders get the new identity's data instead of an error boundary.

#642 Should a callConfig.agent query stop sharing a cache entry with the default agent's, which serves one principal's answer to another?

• Options: (1) an agent segment in overridden keys; (2) document a distinguishing queryKey; (3) throw or warn without one. The audit recommends 1.
• Impact: override queries reach the replica; other keys are unchanged.

#643 On Codespaces and Gitpod, should a ClientManager without host use the page origin, not mainnet, and stop auto-trusting ic_env cookies that strangers' workspaces can set?

• Options: (1) origin, cookie trusted only with allowEnvConfig: true; (2) origin, trust kept; (3) routing kept, trust dropped. The audit recommends 1.
• Impact: codespace dev apps reach their own replica; canister IDs from the cookie there need allowEnvConfig: true.

#646 Should reactorRetry stop retrying HTTP 4xx refusals, such as an expired delegation that takes 16 requests and about 20 s to fail?

• Options: (1) no 4xx retry except 408 and 429; (2) retry 4xx once; (3) document retryTimes: 0. The audit recommends 1.
• Impact: a lapsed session errors after the agent's own 4 requests; 5xx, 408 and 429 still retry.

#565 items 2–3 How should display values tell an enabled but empty opt vec from none (a form's [] is sent as none), and a _type variant arm from the discriminator (resolving it throws)?

• Options: item 2: forms emit [[]], or change core's []-is-none rule (fix(core): accept the canonical Candid optional forms in display args #273); the fix must also cover nested shapes such as opt vec vec T. Item 3: none listed. No recommendation.

#633 Should DisplayReactor keep vec record { text; T } as an object, which drops repeated keys (a second Set-Cookie) and reorders numeric-looking ones?

• Options: (1) keep it, document; (2) array of pairs, breaking icrc1_metadata and ICRC-3 shapes; (3) object only when lossless. The audit recommends 1 now, 2 at the next major.
• Impact: docs only until then.

#632 Should DisplayReactor accept NaN, ±Infinity and -0 on encode, so a float read from a canister can be sent back?

• Options: (1) accept them; (2) display them as strings, changing the type; (3) docs only. The audit recommends 1 plus docs.
• Impact: such values round-trip; JSON still turns them into null, now documented.

#593 Should fromZodSchema support async refinements, and should callMethod(), callMethodWithValidation() and validate() wrap a throwing validator alike?

• Options: opt-in { async: true } or document sync-only; wrap as CallError with cause or document. The audit recommends the opt-in and the wrapping.
• Impact: async schemas work in validate() and callMethodWithValidation(); code matching a validator's raw error must read cause.

#595 (closed; docs fixed in #596) Should Reactor.fetchQuery stay cache-first, returning invalidated data, or become stale-aware?

• Options: keep it; accept revalidateIfStale (needs a peer-floor bump from @tanstack/query-core 5.0.0, or an untyped pass-through); adopt TanStack's fetchQuery semantics. No recommendation.

react

#621 Should useAuth() report isAuthenticating: true until the first session restore settles, so the guides' ProtectedRoute stops bouncing signed-in users to /login?

• Options: (1) yes, server snapshot too; (2) a new readiness flag; (3) docs only; (4) restore in the constructor. The audit recommends 1; its prerequisite landed in fix(react): restore the session once per AuthenticationManager, not per useAuth() (#619) #624.
• Impact: no redirect on reload; signed-out visitors and SSR HTML briefly see the loading state, and a hung restore holds it.

#622 Should query hooks and factories stop retrying update methods by default, since every re-run executes the update again?

• Options: (1) docs only; (2) no retry for updates unless retry is set, or SysTransient only; (3) a dev warning; (4) reuse the request id. The audit recommends 1 and 2 (SysTransient only).
• Impact: a lost response becomes an error, not a second execution; focus refetches remain; explicit retry wins.

#600 (held PR, #564 item 1) Should createMutation(...).execute() run through the MutationCache, like useMutation()?

• Options: (1) the PR; (2) without the factory's onMutate/onSettled; (3) evicting settled mutations; (4) keep it outside. The PR recommends 1.
• Impact: global callbacks (maybe a second error toast), useIsMutating, mutation defaults (a global retry now re-sends these calls; see design: an update method used through the query hooks runs again on every focus, reconnect, remount and retry, each time as a new call #622) and the factory's onMutate apply; offline calls pause; in Node, settled mutations pile up unless gcTime is set.

#599 (held PR, #564 item 3) Should useActorMethod await its invalidateQueries refetches before onSuccess and call() resolve, like the other mutation paths?

• Options: take the PR; keep the order, document it. The audit (react: mutation and query hooks diverge from TanStack in six ways (execute bypasses the MutationCache, no mutationKey, and more) #564) recommends awaiting.
• Impact: onSuccess and await call() see fresh data but land later; isPending lasts until the slowest active refetch.

#564 (remaining item) Should useActorMethod's call() for an update method apply the hook's retry, retryDelay, networkMode and meta, which it silently ignores today?

• Options (the issue lists none): all four, so retry re-sends state-changing calls; all but retry; document the gap. No recommendation; decide with design: an update method used through the query hooks runs again on every focus, reconnect, remount and retry, each time as a new call #622.

#679 Should @ic-reactor/react add a react-server export condition so server components can import core classes from it?

• Options: (A) docs only, done in docs(react): fix the server-component SSR example and the v10 idle example (#675) #681; (B) a react-server entry re-exporting core; (C) "use client" hooks, advised against. The audit recommends A now, B if App Router matters.
• Impact of B: server imports of Reactor build, hook imports fail with a clear error, and the exports map changes.

candid

#611 Should MetadataReactor emit Candid-typed defaultArgs for func-record callbacks, and should forms accept an empty text?

• Options: Candid-typed defaults or converting on that path; accepting "" or documenting "Required". The audit recommends Candid-typed defaults and accepting "".
• Impact: callMethod({ args: defaultArgs }) stops throwing, with bigint defaults; empty-text methods become callable.

#606 (closed; fixed in #618) Should a url field's inputProps.type stay "url" now that its schema accepts paths like /metrics?

• Options: keep it (a test pins it), so a browser <form> still rejects paths; change it. No recommendation.

#644 How should candid reactors stop each leaving a permanent ClientManager subscription?

• Options: (1) compute didjsCanisterId on read; (2) add dispose(); (3) one shared adapter per manager. The audit recommends 1.
• Impact: dynamic reactors stop piling up callbacks that run on every identity change; nothing to adopt.

parser

#631 Should fields and variant tags named like _0_ print under their hash, so they encode by their name's hash, not as id 0?

• Options: (1) print them hashed in didToJs and didToTs; (2) reject them; (3) leave it to upstream. The audit recommends 1, plus filing 3 upstream.
• Impact: these interfaces work, but their keys change (_0_ becomes _4735054_); a hand-written .did that spells a Motoko numeric field _0_ breaks.

vite-plugin / codegen

#664 Should the vite plugin re-detect icp state after vite dev starts, so a later deploy needs no restart?

• Options: (A) re-detect on page loads, cached; (B) only until every canister resolves; (C) stay static, fix the warning. The audit recommends B, with /api following detection.
• Impact: deploying after starting the dev server works on the next reload; a fresh-network redeploy still needs a restart.

#565 item 1 Should the plugin reject two entries sharing name and outDir, as the CLI does?

• Options: fail with the CLI's message; leave it. The audit recommends failing, calling it a small, safe change.
• Impact: that config fails the build instead of producing nondeterministic output with exit 0.

docs / process

#666 item 4 Which icp-cli version should the examples target, now that vite-plugin-demo uses a sync step icp-cli 1.5 removed (current users can't deploy it) while CI pins 1.2.0?

• Options: stay on 1.2.0 and say so; move examples and CI to 1.5. No recommendation.

#634 Should the @icp-sdk/core quirks (U1–U9) and candid_parser/bindgen issues be reported upstream?

• Options: report them with the sweep's repro script; keep tracking here. Also open: moving fix(candid): close the remaining Object.prototype-name gaps (#659) #672's __proto__ workaround into core's reply decoding. No recommendation; design(parser): a Candid field or variant tag named like _0_ is sent as field id 0, not by its name's hash #631 recommends filing its part.

Checklist

• fix(core): give each polled request its own counter, clock and timeout (#563) #578 — polling timeout default: 5 minutes or none
• design(core): a fetchQuery() in flight during a sign-in or sign-out rejects with TanStack's CancelledError, which is neither a CallError nor a CanisterError #647 — fetchQuery across a sign-in/out (audit: 1)
• design(core): a query sent through callConfig.agent shares its cache entry with the same query sent through the ClientManager's agent #642 — agent segment in query keys (audit: 1)
• design(core): in Codespaces and Gitpod a ClientManager talks to mainnet unless given a host, and with one it trusts an ic_env cookie that other users' workspaces can write #643 — Codespaces/Gitpod routing and cookie trust (audit: 1)
• design(core): reactorRetry retries HTTP 4xx refusals such as an expired delegation, so a query fails only after 16 requests and about 20 seconds #646 — stop retrying HTTP 4xx (audit: 1)
• design: vite-plugin allows entries sharing name+outDir, an enabled empty opt vec is sent as none, and a variant arm named _type collides #565 items 2–3 — empty opt vec; _type arm
• design(core): a vec record { text; T } result loses repeated keys and the order of numeric-looking keys, e.g. an HTTP response's second Set-Cookie header #633 — object keys: docs now, pairs later (audit)
• design(core): a NaN or infinite float from a canister cannot be sent back through DisplayReactor, and JSON turns it into null (an optional one into none) #632 — non-finite floats on encode (audit: 1)
• design: validation — async zod refinements in fromZodSchema, and validator errors wrapped differently per entry point #593 — async zod; validator error wrapping (audit)
• docs(core): fetchQuery is cache-first (returns invalidated data, ignores staleTime), but the docs say it follows standard React Query caching #595 — fetchQuery staleness
• design: useAuth() reports "signed out, not authenticating" before the session restore starts, so the documented ProtectedRoute sends signed-in users to /login on every page load #621 — isAuthenticating before the first restore (audit: 1)
• design: an update method used through the query hooks runs again on every focus, reconnect, remount and retry, each time as a new call #622 — update methods in query hooks (audit: 1+2)
• fix(react): run createMutation's execute() in the MutationCache (#564 item 1, design) #600 — execute() via the MutationCache (PR: 1)
• fix(react): await useActorMethod's invalidation before onSuccess (#564 item 3, design) #599 — await invalidation before onSuccess
• react: mutation and query hooks diverge from TanStack in six ways (execute bypasses the MutationCache, no mutationKey, and more) #564 — hook options on an update's call()
• design(react): nothing can be imported from @ic-reactor/react in a React Server Component, not even the core classes it re-exports #679 — react-server export condition
• design(candid): MetadataReactor func-record defaultArgs are display-typed, and form visitors reject empty text #611 — func-record defaults; empty text (audit)
• candid: a field labelled url only accepts absolute URLs, so http_request forms reject every request path #606 — url field's inputProps.type
• design(candid): every CandidReactor built without a shared adapter subscribes to its ClientManager for good, and no reactor can be disposed #644 — adapter subscription leak (audit: 1)
• design(parser): a Candid field or variant tag named like _0_ is sent as field id 0, not by its name's hash #631 — _N_ field names (audit: 1)
• design(vite-plugin): the ic_env cookie and /api proxy are fixed when vite dev starts, so a canister deployed afterwards never gets its id until the server restarts #664 — dev-server re-detection (audit: B)
• design: vite-plugin allows entries sharing name+outDir, an enabled empty opt vec is sent as none, and a variant arm named _type collides #565 item 1 — shared name + outDir
• codegen/cli: regeneration rewrites unchanged files, --bindgen-only help names a file never produced, cli.mdx name/key claim, vite-plugin-demo uses a removed icp-cli step #666 item 4 — icp-cli version for examples
• upstream: @icp-sdk/core Candid encoding/decoding quirks found by the encoding sweep (tracking) #634 — upstream reports

[b3hr4d]

Added after this digest was written:

#690 (core) An API-shaped canister error (code / message: opt text / details, e.g. Orbit's station) gets two different messages depending on the reactor class. Through a raw Reactor it's the whole payload printed as JSON; through a DisplayReactor it's the text. Separately, isApiError() narrows to an ApiError whose message: string and details: Map don't match decoded values.

• Options: for message, (A) read a raw opt text's element or (B) document it. For the guard, (C) type message/details as unknown, (D) check the asserted types (returns false for decoded errors) or (E) document it.

• The audit recommends A and C.

• Impact: raw-Reactor users of such canisters get the text message. No runtime change from C.

• design(core): an API-shaped canister error through a raw Reactor gets its whole payload as message, and isApiError() still claims a Map #690 — API-shaped error message and isApiError types (audit: A + C)

[b3hr4d]

Also added after this digest was written:

#700 (core) An untyped DisplayReactor or CandidDisplayReactor types validator args and results as unknown, while an untyped Reactor gives any.

• Options: keep unknown and document it, or make it any for consistency.

• The sweep recommends keeping unknown and documenting it. Some candid docs snippets carry casts that only this typing needs (docs(candid): fix candid page snippets and JSDoc that fail tsc (#697) #705).

• design(core): an untyped DisplayReactor or CandidDisplayReactor types validator args and results as unknown, while an untyped Reactor gives any #700 — untyped display reactor: unknown vs any

[b3hr4d]

Also added: #713 (core) On a local host, initialize() replaces a root key supplied through agentOptions.rootKey, or read from the ic_env cookie, with the one the host serves. It does this even with shouldFetchRootKey: false. This is deliberate (since core 1.10.1, kept by #637/#651, relied on by #643) but was undocumented. The docs PR describes the current behaviour.

• Recommendation (from the issue): honour an explicit agentOptions.rootKey in initialize(). Cookie keys would still be replaced.

• design(core): on a local host, initialize() replaces a supplied root key with the one the host serves, even with shouldFetchRootKey: false #713 — explicit rootKey on local initialize()

[b3hr4d]

Also added: #719 (core). updateAgent sweeps the canister cache even when the new identity has the same principal, for example a renewed delegation or an attributes request. It measured one extra refetch of a mounted query, a removed inactive entry, and an in-flight fetchQuery rejected with CancelledError. Skipping the sweep is safe for plain delegations. It isn't safe in general: AttributesIdentity keeps the principal but adds sender_info that the canister sees.

• Recommendation (from the issue): skip the sweep when the principal is unchanged, but still refetch failed queries. The narrower "same identity object re-installed" option is safe on its own.

• design(core): updateAgent sweeps the canister cache when the principal did not change (session renewal, attribute requests) #719 — cache sweep on a same-principal updateAgent

[b3hr4d]

Also added: #729 (react) When IC Reactor rebuilds the auth client for per-call options, the old client is never released. On v8, the app's onIdle then fired 3 times in one idle period; on v10, dispose() was called 0 times.

• Recommendation (from the issue): dispose replaced clients on v10, and give every v8 client one onIdle wrapper that runs once per idle event.

• design(react): a client IC Reactor rebuilds for per-call options is never released, so v8's onIdle fires once per client and v10 clients are never disposed #729 — releasing rebuilt auth clients

[b3hr4d]

Also added: #737 (parser) A Candid type named _SERVICE, or named like a TypeScript type keyword, breaks didToTs output, and only renaming the user's type can fix it. That makes it a public-name change.

• Options are in the issue. The related import clashes (Principal, ActorMethod, IDL, Array, typed arrays) are fixed without renaming in the PR for parser: a Candid type named Principal, ActorMethod, IDL, Array or a typed array breaks the generated bindings #735.

• design(parser): a Candid type named _SERVICE, or like a TypeScript type keyword, breaks didToTs output, and only renaming it can fix that #737 — types named _SERVICE or like a TS keyword

[b3hr4d]

Also added from the performance audit:

#745 (react) A discarded AuthenticationManager never disposes its v10 client. 50 provider remounts left 50 live clients and 653 page listeners. #729 covers only a client replaced when options change.

• Options are in the issue, e.g. a dispose() on the manager, or disposing when the last subscriber leaves.

#746 (react, core) defineReactor always bundles DisplayReactor and all of zod, even with display: false: 42.0 kB gzipped, of which zod is 23.5 kB, against 12.5 kB for createActorHooks + Reactor + the auth hooks.

• zod/mini would cost 5.0 kB, but it changes the public DisplayCodec type. A lazy or split entry is the other option.

• design(react): a discarded AuthenticationManager leaves its AuthClient running, so each remount of a provider that builds one leaks a live v10 client #745 — disposing a dropped AuthenticationManager's client

• design(react, core): defineReactor always bundles DisplayReactor and all of zod (about 23.5 kB gzipped), even with display: false #746 — defineReactor bundle size / zod

[b3hr4d]

Also added: #754 (react, high) With @icp-sdk/auth v10, a tab keeps signing as the account the user signed out of in another tab. Its next check then signs every tab out of the account signed in since. Reproduced on main with real clients.

• Recommendation (from the issue): subscribe the AuthenticationManager to the v10 client's change notifications, so every tab follows a sign-out or sign-in made in another tab. Report the upstream part too: a replaced v10 session identity can still drop the newer session record.

• This is the design half of a fix. The narrower bug (react: with @icp-sdk/auth v10, a session check in one tab ends the sign-in the user just made in another tab #753, one tab's session check ending another tab's fresh sign-in) is fixed in its PR without it.

• design(react): with @icp-sdk/auth v10, a tab keeps signing as the account the user signed out of in another tab, then signs every tab out of the account signed in since #754 — v10 cross-tab session following