@capxul/sdk-react 4.2.0 → 4.20.0-beta.1

package/README.md

@@ -28,10 +28,12 @@ export function Providers({ children }: { children: React.ReactNode }) {
   session. Account and Organization readiness transitions refresh active
   authenticated queries.
 - `CapxulAuthenticationController` and `CapxulOnboardingController` select
-  app-owned slots and render no SDK-owned DOM. Supplying the onboarding
-  controller's `recoveryOptions` factory lets a fresh actor resume account
-  prerequisites before the stored Organization replay; a failed prerequisite
-  returns the same manual replay instead of looping.
+  app-owned slots and render no SDK-owned DOM. The onboarding controller keeps
+  no Organization submission: after a reload the Core SDK reads the pending
+  Organization from the backend and attaches it, so the app re-submits nothing.
+  A claimed identity with no Organization and no app-held form step reports
+  `organizationProgress` with `{ at: "loading", orgId: null }` until that
+  attach lands.
 - Rich-data hooks such as `useCapxulProfile`, `useCapxulOrgs`, members, roles,
   treasury, and money hooks remain TanStack Query projections. Personal
   holdings and activity reads start only after the Account is claimed.

package/dist/{controllers-BPEhjKX9.mjs → controllers-DXmEHrnw.mjs}

@@ -37,6 +37,24 @@ function useCapxulClientOrNull() {
 }
 //#endregion
 //#region src/internal/reactivity-keys.ts
+/**
+* The account a read is answered FOR, as a key segment (#2007 R19).
+*
+* A read whose answer depends on who is asking belongs to the (scope, account)
+* pair, not to the scope. Replacing one claimed account with another is not a
+* state-label change. Keying is what
+* makes the new person miss rather than read the previous person's answer.
+* `undefined` while no account is claimed — no such read may run then anyway.
+*/
+function actingAccount(identity) {
+	return identity !== null && identity.phase === "authenticated" && identity.account.at === "claimed" ? identity.account.address : void 0;
+}
+/** Keep invalidation prefixes shared, but never share a personal result across accounts.
+* Session reads also run before an Account is claimed (for example `orgs()`).
+*/
+function accountKey(key, identity) {
+	return [...key, actingAccount(identity) ?? (identity?.phase === "authenticated" ? identity.session.authUserId : null)];
+}
 const capxulKeys = {
 	root: ["capxul"],
 	profile: ["capxul", "profile"],
@@ -80,11 +98,12 @@ const capxulKeys = {
 		orgId ?? "pending",
 		"permissions"
 	],
-	orgMe: (orgId) => [
+	orgMe: (orgId, account) => [
 		"capxul",
 		"org",
 		orgId ?? "pending",
-		"me"
+		"me",
+		account ?? "pending"
 	],
 	orgLifecycle: (orgId) => [
 		"capxul",
@@ -151,10 +170,35 @@ const capxulKeys = {
 	]
 };
 //#endregion
-//#region src/identity.tsx
-const MISSING_IDENTITY_PROVIDER = Symbol("MISSING_IDENTITY_PROVIDER");
-const IdentityContext = createContext(MISSING_IDENTITY_PROVIDER);
-function controls(options) {
+//#region src/internal/invocation-controls.ts
+/**
+* Keep only the five public option fields, and only when they hold the right
+* kind of value. A named action verb takes its attempt as an optional FIRST
+* argument, so a screen that wires one straight to a DOM handler
+* (`onClick={row.hide}`) hands us a React SyntheticEvent. That is not an
+* attempt: it must reach neither the SDK call nor the callback echo.
+*/
+function toInvocationOptions(options) {
+	if (typeof options !== "object" || options === null) return void 0;
+	const attempt = {};
+	if (typeof options.correlationId === "string") attempt.correlationId = options.correlationId;
+	if (typeof options.journeyId === "string") attempt.journeyId = options.journeyId;
+	if (typeof options.timeoutMs === "number") attempt.timeoutMs = options.timeoutMs;
+	if (typeof options.deadlineMs === "number") attempt.deadlineMs = options.deadlineMs;
+	if (options.signal instanceof AbortSignal) attempt.signal = options.signal;
+	return Object.keys(attempt).length === 0 ? void 0 : attempt;
+}
+/**
+* Map the public camel-case invocation options onto the Core SDK's control
+* spelling. ONE definition, because the identity facade and every headless
+* engine must hand the SDK the same shape: a caller that captured one user
+* attempt before it started gets that attempt's `correlation_id`/`journey_id`
+* on whichever operation it starts (#1960 R02).
+*
+* It creates no identifiers. An absent option stays absent, so an automatic
+* read keeps its own invocation context instead of borrowing an attempt's.
+*/
+function toInvocationControls(options) {
 	if (options === void 0) return void 0;
 	return {
 		...options.signal === void 0 ? {} : { signal: options.signal },
@@ -164,12 +208,16 @@ function controls(options) {
 		...options.journeyId === void 0 ? {} : { journey_id: options.journeyId }
 	};
 }
+//#endregion
+//#region src/identity.tsx
+const MISSING_IDENTITY_PROVIDER = Symbol("MISSING_IDENTITY_PROVIDER");
+const IdentityContext = createContext(MISSING_IDENTITY_PROVIDER);
 const failure = (result) => result.ok ? null : {
 	ok: false,
 	reason: result.refused
 };
 async function guarded(runtime, verb, options, run) {
-	const invocation = controls(options);
+	const invocation = toInvocationControls(options);
 	try {
 		return await (runtime.runFacade?.(verb, invocation, run) ?? run(invocation));
 	} catch {
@@ -215,18 +263,102 @@ function normalizeOrganization(organization) {
 		return null;
 	}
 }
+/** The Organization id when its lane is already running or finished, else null. */
+const runningOrganization = (state) => {
+	if (state.phase !== "authenticated" || state.account.at !== "claimed") return null;
+	const org = state.account.org;
+	return org !== null && (org.at === "loading" || org.at === "settingUp" || org.at === "ready") ? org.orgId : null;
+};
+/** A superseded session read waits at most this long for the winning read. */
+const SESSION_SETTLE_LIMIT_MS = 3e4;
+const accountInFlight = (state) => state.phase === "authenticated" && (state.account.at === "deriving" || state.account.at === "claiming");
 function createAuth(client, clearAuthenticatedQueries) {
 	const runtime = client._internal.identity;
+	const settledSession = (invocation) => new Promise((resolve) => {
+		let done = false;
+		let stop = null;
+		let timer = null;
+		const onAbort = () => finish({
+			ok: false,
+			reason: "CANCELLED"
+		});
+		const finish = (result) => {
+			if (done) return;
+			done = true;
+			stop?.();
+			if (timer !== null) clearTimeout(timer);
+			invocation?.signal?.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+		if (invocation?.signal?.aborted) {
+			onAbort();
+			return;
+		}
+		invocation?.signal?.addEventListener("abort", onAbort, { once: true });
+		const unsubscribe = runtime.subscribeTransitions((record) => {
+			if (record.slot !== "identity:session") return;
+			if (record.outcome === "applied" && record.event === "SessionRead") finish({ ok: true });
+			else if (record.outcome === "failed" || record.outcome === "cancelled") finish({
+				ok: false,
+				reason: record.error_code
+			});
+		});
+		if (done) {
+			unsubscribe();
+			return;
+		}
+		stop = unsubscribe;
+		timer = setTimeout(() => finish({
+			ok: false,
+			reason: "UNKNOWN"
+		}), SESSION_SETTLE_LIMIT_MS);
+	});
 	const read = async (invocation) => {
 		const result = await runtime.send({ _tag: "ReadSession" }, invocation);
-		return failure(result) ?? { ok: true };
+		const refused = failure(result);
+		if (refused === null) return { ok: true };
+		return refused.reason === "SUPERSEDED" ? settledSession(invocation) : refused;
 	};
 	const ensureAccount = async (invocation) => {
 		const result = await runtime.send({ _tag: "EnsureAccount" }, invocation);
 		return failure(result) ?? { ok: true };
 	};
+	const settledAccount = (invocation) => new Promise((resolve) => {
+		let done = false;
+		let stop = null;
+		const onAbort = () => finish({
+			ok: false,
+			reason: "CANCELLED"
+		});
+		const finish = (result) => {
+			if (done) return;
+			done = true;
+			stop?.();
+			invocation?.signal?.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+		if (invocation?.signal?.aborted) {
+			onAbort();
+			return;
+		}
+		invocation?.signal?.addEventListener("abort", onAbort, { once: true });
+		const unsubscribe = runtime.subscribe((state) => {
+			if (!accountInFlight(state)) finish({ ok: true });
+		});
+		if (done) {
+			unsubscribe();
+			return;
+		}
+		stop = unsubscribe;
+		if (!accountInFlight(runtime.snapshot())) finish({ ok: true });
+	});
 	const reachClaimed = async (invocation) => {
 		let state = runtime.snapshot();
+		if (accountInFlight(state)) {
+			const settled = await settledAccount(invocation);
+			if (!settled.ok) return settled;
+			state = runtime.snapshot();
+		}
 		if (state.phase !== "authenticated" || state.account.at === "unknown") {
 			const result = await runtime.send({ _tag: "EnsureAccount" }, invocation);
 			const refused = failure(result);
@@ -238,6 +370,16 @@ function createAuth(client, clearAuthenticatedQueries) {
 			reason: "WRONG_STATE"
 		};
 		if (state.account.at === "claimed") return { ok: true };
+		if (accountInFlight(state)) {
+			const settled = await settledAccount(invocation);
+			if (!settled.ok) return settled;
+			state = runtime.snapshot();
+			if (state.phase !== "authenticated") return {
+				ok: false,
+				reason: "WRONG_STATE"
+			};
+			if (state.account.at === "claimed") return { ok: true };
+		}
 		const event = state.account.at === "failed" ? { _tag: "RetryAccount" } : state.account.at === "counterfactual" ? { _tag: "ClaimAccount" } : { _tag: "EnsureAccount" };
 		const result = await runtime.send(event, invocation);
 		const refused = failure(result);
@@ -258,13 +400,13 @@ function createAuth(client, clearAuthenticatedQueries) {
 			ok: false,
 			reason: "INVALID_INPUT"
 		};
+		const refreshed = await read(invocation);
+		if (!refreshed.ok) return refreshed;
 		const current = runtime.snapshot();
 		if (current.phase !== "authenticated" || !current.profileComplete) {
 			const completed = await runtime.completeProfile(submission.profileDetails, invocation);
 			if (!completed.ok) return completed;
 		}
-		const refreshed = await read(invocation);
-		if (!refreshed.ok) return refreshed;
 		const claimed = await reachClaimed(invocation);
 		return claimed.ok ? {
 			ok: true,
@@ -341,12 +483,13 @@ function createAuth(client, clearAuthenticatedQueries) {
 		}),
 		createOrganization: (submission, options) => guarded(runtime, "createOrganization", options, async (invocation) => {
 			const current = runtime.snapshot();
+			const running = runningOrganization(current);
+			if (running !== null) return {
+				ok: true,
+				orgId: running
+			};
 			if (current.phase === "authenticated" && current.account.at === "claimed") {
 				const org = current.account.org;
-				if (org !== null && (org.at === "loading" || org.at === "settingUp" || org.at === "ready")) return {
-					ok: true,
-					orgId: org.orgId
-				};
 				if (org?.at === "failed" && org.orgId !== null) {
 					if (!org.retryable) return {
 						ok: false,
@@ -361,6 +504,11 @@ function createAuth(client, clearAuthenticatedQueries) {
 			}
 			const prepared = await prepareOrganization(submission, invocation);
 			if (!prepared.ok) return prepared;
+			const opened = runningOrganization(runtime.snapshot());
+			if (opened !== null) return {
+				ok: true,
+				orgId: opened
+			};
 			const created = await runtime.send({
 				_tag: "CreateOrganization",
 				draft: prepared.organization
@@ -426,9 +574,16 @@ function CapxulIdentityProvider({ client, children }) {
 	}, [client, runtime]);
 	useEffect(() => {
 		if (runtime === null) return;
+		let previousAccount = actingAccount(runtime.snapshot());
 		return runtime.subscribeTransitions((record) => {
 			const state = runtime.snapshot();
-			if (record.outcome === "applied" && record.from !== record.to && (record.to === "authenticated:claimed" || record.to === "authenticated:claimed:ready")) queryClient.invalidateQueries({ queryKey: capxulKeys.root });
+			const account = actingAccount(state);
+			const accountChanged = previousAccount !== void 0 && account !== void 0 && account !== previousAccount;
+			previousAccount = account;
+			if (record.outcome === "applied" && (record.from !== record.to || accountChanged) && (record.to === "authenticated:claimed" || record.to === "authenticated:claimed:ready")) queryClient.invalidateQueries({
+				queryKey: capxulKeys.root,
+				...accountChanged ? { refetchType: "none" } : {}
+			});
 			for (const listener of listeners.current) try {
 				listener(record, state);
 			} catch {
@@ -442,7 +597,7 @@ function CapxulIdentityProvider({ client, children }) {
 	}, []);
 	const value = useMemo(() => {
 		if (client === null || runtime === null) return null;
-		const send = (event, options) => runtime.send(event, controls(options));
+		const send = (event, options) => runtime.send(event, toInvocationControls(options));
 		const clearAuthenticatedQueries = async () => {
 			await queryClient.cancelQueries({ queryKey: capxulKeys.root });
 			await queryClient.resetQueries({ queryKey: capxulKeys.root });
@@ -821,4 +976,4 @@ function organizationForm(props, state, auth, submitted) {
 	});
 }
 //#endregion
-export { useCapxulAuth as a, useCapxulIdentityOrNull as c, capxulKeys as d, useCapxulClientOrNull as f, entered as i, useCapxulSend as l, CapxulOnboardingController as n, useCapxulDestination as o, useCapxul as p, CapxulProvider as r, useCapxulIdentity as s, CapxulAuthenticationController as t, useCapxulTransitions as u };
+export { useCapxul as _, useCapxulAuth as a, useCapxulIdentityOrNull as c, toInvocationControls as d, toInvocationOptions as f, useCapxulClientOrNull as g, capxulKeys as h, entered as i, useCapxulSend as l, actingAccount as m, CapxulOnboardingController as n, useCapxulDestination as o, accountKey as p, CapxulProvider as r, useCapxulIdentity as s, CapxulAuthenticationController as t, useCapxulTransitions as u };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { A as entered, C as CreateOrganizationFailure, D as OrganizationDetails, E as InvocationOptions, F as useCapxulTransitions, M as useCapxulDestination, N as useCapxulIdentity, O as ProfileDetails, P as useCapxulSend, S as CapxulSend, T as Destination, _ as ReadyDestination, a as AuthenticationSlots, b as Slot, c as ControllerAction, d as OnboardingControllerProps, f as OrgFailure, g as ProfileSlotProps, h as PendingAuthState, i as AuthenticatedState, j as useCapxulAuth, k as SendResult, l as FaultedState, m as OtpPendingState, n as AccountProgress, o as CapxulAuthenticationController, p as OrgProgress, r as ActionResult, s as CapxulOnboardingController, t as AccountFailure, u as NavigationAction, v as RetryAction, w as CreateOrganizationSubmission, x as CapxulAuth, y as SignedOutState } from "./controllers-BWmKRFy6.mjs";
 import { ReactNode, RefCallback } from "react";
 import { QueryClient, UseMutationResult, UseQueryResult } from "@tanstack/react-query";
-import { Account, AccountRequirement, ActivityAnnotation, ActivityAnnotationInput, ActivityDetail, ActivityKind, ActivityListParams, ActivityPage, ActivityPhase, ActivityRange, ActivityReference, ActorReference, AddressBookEntry, BudgetId, CapxulClient, CapxulError, CapxulResult, CapxulSigner, CreateOrgInput, CurrentHoldings, HostObservability, IdentityDestination, InviteMemberInput, MemberView, Money, MoneyParseErrorReason, OrgId, OrgView, OrganizationPaymentBatchInput, OrganizationPaymentInput, PartyId, Payment, PaymentDirection, PaymentDocumentRef, PaymentDocumentRender, PaymentStatus, PaymentTiming, PaymentType, PaymentsPayInput, PayrollGroupId, PayrollGroupInput, PayrollRunId, PayrollRunStatus, Permission, PermissionMethods, PermissionReadResult, Profile, RoleView, SubmittedPermissionExecution, isClaimed, isRestoring } from "@capxul/sdk";
+import { Account, AccountRequirement, ActivityAnnotation, ActivityAnnotationInput, ActivityDetail, ActivityKind, ActivityListParams, ActivityPage, ActivityPhase, ActivityRange, ActivityReference, ActorReference, AddressBookEntry, BudgetId, CapxulClient, CapxulError, CapxulResult, CapxulSigner, CreateOrgInput, CurrentHoldings, HostObservability, IdentityDestination, IdentityState, InviteMemberInput, MemberView, Money, MoneyParseErrorReason, OrgId, OrgView, OrganizationPaymentBatchInput, OrganizationPaymentInput, PartyId, Payment, PaymentDirection, PaymentDocumentRef, PaymentDocumentRender, PaymentStatus, PaymentTiming, PaymentType, PaymentsPayInput, PayrollGroupId, PayrollGroupInput, PayrollRunId, PayrollRunStatus, Permission, PermissionMethods, PermissionReadResult, Profile, RoleView, SubmittedPermissionExecution, isClaimed, isRestoring } from "@capxul/sdk";
 //#region src/provider.d.ts
 type CapxulProviderSharedProps = {
   /** Bring your own QueryClient; otherwise the provider creates one. */
@@ -200,12 +200,21 @@ type UseCapxulCreateOrgReturn = UseMutationResult<OrgView, CapxulError, CreateOr
 declare function useCapxulCreateOrg(): UseCapxulCreateOrgReturn;
 //#endregion
 //#region src/hooks/use-capxul-invite-member.d.ts
+/**
+ * R06 (#1964): `options` is the browser attempt the caller captured before the
+ * person pressed Send. It reaches the SDK operation unchanged, so the durable
+ * `org_invite_sent` and the later `org_invite_progressed` carry that attempt's
+ * correlation. Absent, the invitation keeps its own invocation context.
+ */
+type UseCapxulInviteMemberInput = InviteMemberInput & {
+  readonly options?: InvocationOptions;
+};
 /**
  * Invite a member to an Organization by email. The hook uses the closed-over `orgId`.
  * It binds directly to
  * `capxul.org(orgId).invite(input)`. On success, invalidates the member list.
  */
-type UseCapxulInviteMemberReturn = UseMutationResult<MemberView, CapxulError, InviteMemberInput>;
+type UseCapxulInviteMemberReturn = UseMutationResult<MemberView, CapxulError, UseCapxulInviteMemberInput>;
 declare function useCapxulInviteMember(orgId: OrgId | undefined): UseCapxulInviteMemberReturn;
 //#endregion
 //#region src/headless/journey/journey-state.d.ts
@@ -383,9 +392,9 @@ interface Contact {
 interface ContactRow extends Contact {
   /** Ours: one initials rule, not one copy per screen. */
   readonly initials: string;
-  readonly rename: (name: string) => void;
-  readonly hide: () => void;
-  readonly unhide: () => void;
+  readonly rename: (name: string, options?: InvocationOptions) => void;
+  readonly hide: (options?: InvocationOptions) => void;
+  readonly unhide: (options?: InvocationOptions) => void;
 }
 /** ADR-0023 R1: refusal CODES, never sentences — the app owns the words. */
 type ContactsRefusal = "loading" | "org-unavailable" | "unavailable";
@@ -421,7 +430,13 @@ interface ContactsListOptions {
 interface ContactsAddSlice {
   readonly value: string;
   readonly change: (text: string) => void;
-  readonly submit: () => void;
+  /**
+   * #1960 R02: hand it the options the screen captured BEFORE the click. The
+   * same snapshot reaches the SDK add call and comes back on `onAdded`/
+   * `onFailed`, so the UI observation and the operation share one identity even
+   * when the reply lands after an account switch. Omitted stays omitted.
+   */
+  readonly submit: (options?: InvocationOptions) => void;
   readonly isSubmitting: boolean;
   readonly blocked: boolean;
   readonly blockedReason: ContactsAddBlockedReason | null;
@@ -431,9 +446,14 @@ interface ContactsAddSlice {
 //#region src/headless/contacts/contacts.d.ts
 interface CapxulContactsProps {
   readonly actor: ContactsActor;
-  readonly onAdded: (contact: Contact) => void;
+  /**
+   * `options` is exactly what the caller handed `.Add.submit` or a row verb, so
+   * the screen's own observation of the finished action can reuse the attempt
+   * identity the SDK operation ran under (#1960 R02).
+   */
+  readonly onAdded: (contact: Contact, options?: InvocationOptions) => void;
   /** ADR-0023 R1: the app maps `error.code` to its own copy; no SDK sentence. */
-  readonly onFailed: (error: CapxulError) => void;
+  readonly onFailed: (error: CapxulError, options?: InvocationOptions) => void;
   readonly children: ReactNode;
 }
 declare function Root$6({ actor, onAdded, onFailed, children }: CapxulContactsProps): import("react/jsx-runtime").JSX.Element;
@@ -505,6 +525,7 @@ type SummaryWindow = "all" | "last30days" | ActivityRange;
  * in its own words.
  */
 interface ActivitySummarySlice {
+  readonly readWarning?: ActivityPage["readWarning"];
   readonly currency: string | null;
   readonly moneyIn: string | null;
   readonly moneyOut: string | null;
@@ -541,11 +562,17 @@ interface ActivitySearchSlice {
   readonly change: (text: string) => void;
 }
 interface ActivityRowsSlice {
+  readonly readWarning?: ActivityPage["readWarning"];
   /** Already filtered and already searched. */
   readonly rows: readonly ActivityRow[];
   readonly isLoading: boolean;
   readonly error: CapxulError | null;
-  readonly retry: () => void;
+  /**
+   * #1960 R02: pass the options captured before the retry was selected and the
+   * re-read runs under the same attempt identity as the UI observation. Omit
+   * them and the read keeps its own invocation context.
+   */
+  readonly retry: (options?: InvocationOptions) => void;
   /** Server read time of the newest page, so the app can say which read is older. */
   readonly observedAt: number | null;
 }
@@ -583,13 +610,15 @@ interface ActivityDetailSlice {
   readonly error: CapxulError | null;
 }
 interface CsvExport {
+  readonly readWarning?: ActivityPage["readWarning"];
   readonly text: string;
   readonly rowCount: number;
   /** The 5,000-row ceiling was reached and rows were left unread. */
   readonly truncated: boolean;
 }
 interface ActivityExportSlice {
-  readonly toCsv: () => Promise<CsvExport>;
+  /** Same contract as `retry`: the export's pages run under the caller's attempt. */
+  readonly toCsv: (options?: InvocationOptions) => Promise<CsvExport>;
   readonly isExporting: boolean;
 }
 //#endregion
@@ -816,8 +845,19 @@ type DashboardScope = {
   readonly orgId?: string;
 };
 type DashboardAccessPhase = "checking" | "error" | "redirect" | "granted";
+/**
+ * Which of the three probes produced the error the screen is showing. The
+ * error code alone cannot say: a provider failure reads the same whether the
+ * session read, the membership list or the lifecycle read raised it, and a
+ * consumer that reports a displayed gate error has to keep those apart
+ * (#1963 R05-2). It names the SOURCE only; `retry` still re-runs every failed
+ * probe, exactly as before.
+ */
+type DashboardAccessProbe = "session" | "membership" | "lifecycle";
 interface DashboardAccessErrorSlice {
   readonly error: CapxulError;
+  /** The probe the surfaced error came from, in the frozen precedence order. */
+  readonly probe: DashboardAccessProbe;
   /** Re-runs each failed probe. */
   readonly retry: () => void;
 }
@@ -836,6 +876,12 @@ declare function Checking({ children }: {
 declare function DashboardError({ children }: {
   readonly children: (slice: DashboardAccessErrorSlice) => ReactNode;
 }): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Hands the destination and draws nothing. Reaching this part is a REQUEST to
+ * navigate, never an arrival: the app may cancel or supersede it, so nothing
+ * here — and nothing a consumer hangs off it — may claim a completed redirect
+ * (#1963 R05-1). The destination page's own normalized pageview proves arrival.
+ */
 declare function Redirect({ children }: {
   readonly children: (slice: DashboardAccessRedirectSlice) => ReactNode;
 }): import("react/jsx-runtime").JSX.Element | null;
@@ -874,8 +920,14 @@ interface PayrollSummarySlice {
 }
 interface PayrollGroupsSlice {
   readonly groups: readonly PayrollGroupRow[];
-  readonly save: (input: PayrollGroupInput) => Promise<CapxulResult<PayrollGroupRow>>;
-  readonly remove: (id: PayrollGroupId) => Promise<CapxulResult<void>>;
+  /**
+   * R13 (#1968): `options` is the browser attempt the caller captured before the
+   * employer pressed the button. It reaches the SDK operation unchanged, so the
+   * group's `ui_payroll_action_completed` and the durable `payroll_group_changed`
+   * share one correlation. Absent, the write keeps its own invocation context.
+   */
+  readonly save: (input: PayrollGroupInput, options?: InvocationOptions) => Promise<CapxulResult<PayrollGroupRow>>;
+  readonly remove: (id: PayrollGroupId, options?: InvocationOptions) => Promise<CapxulResult<void>>;
   readonly isSaving: boolean;
   readonly isLoading: boolean;
   readonly error: CapxulError | null;
@@ -967,7 +1019,14 @@ interface PayrollRunSummarySlice {
 interface PayrollRunActionsSlice {
   readonly recovery: "none" | "restoring" | "required" | "unavailable";
   readonly recoveryError: CapxulError | null;
-  readonly submit: () => void;
+  /**
+   * R13 (#1968): `options` is the browser attempt captured before the employer
+   * confirmed. It reaches `authorizeRun` unchanged, so the sheet's own
+   * `ui_payroll_action_completed` and the durable `payroll_run_transitioned`
+   * rows share one correlation. It is NEVER written into the persisted draft —
+   * a restored run keeps its own identity, not a stale attempt's.
+   */
+  readonly submit: (options?: InvocationOptions) => void;
   readonly isSubmitting: boolean;
   readonly blocked: boolean;
   readonly blockedReason: CapxulPayrollRunBlockedReason | null;
@@ -1036,7 +1095,7 @@ declare const capxulKeys: {
   orgRoles: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "roles"];
   orgTreasury: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "treasury"];
   orgPermissions: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "permissions"];
-  orgMe: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "me"];
+  orgMe: (orgId: OrgId | undefined, account: string | undefined) => readonly ["capxul", "org", "pending" | OrgId, "me", string];
   orgLifecycle: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "lifecycle"];
   contacts: (scope: string) => readonly ["capxul", "contacts", string];
   contactsList: (scope: string, includeHidden: boolean) => readonly ["capxul", "contacts", string, "all" | "visible"];
@@ -1051,4 +1110,4 @@ declare const capxulKeys: {
   payment: (paymentId: string | undefined) => readonly ["capxul", "payments", string];
 };
 //#endregion
-export { type AccountFailure, type AccountProgress, type ActionResult, type ActivityDetailSlice, type ActivityExportSlice, type ActivityFilterValues, type ActivityFiltersSlice, type ActivityLoadMoreSlice, type ActivityReceipt, type ActivityRow, type ActivityRowsSlice, type ActivitySearchSlice, type ActivitySummarySlice, type AuthenticatedState, type AuthenticationSlots, type CanReason, CapxulActivity, type CapxulActivityProps, type CapxulAuth, CapxulAuthenticationController, type CapxulBootstrapState, type CapxulBootstrapStatus, CapxulContacts, type CapxulContactsProps, CapxulDashboardAccess, type CapxulDashboardAccessProps, CapxulOnboardingController, CapxulOrgMember, type CapxulOrgMemberProps, CapxulPayroll, type CapxulPayrollProps, CapxulPayrollRun, type CapxulPayrollRunBlockedReason, type CapxulPayrollRunProps, CapxulProvider, type CapxulProviderProps, type CapxulSend, CapxulSendMoney, type CapxulSendMoneyBlockedReason, type CapxulSendMoneyProps, type Contact, type ContactRelationship, type ContactRow, type ContactsActor, type ContactsAddBlockedReason, type ContactsAddError, type ContactsAddSlice, type ContactsListOptions, type ContactsListSlice, type ContactsRefusal, type ContactsSummarySlice, type ControllerAction, type CreateOrganizationFailure, type CreateOrganizationSubmission, type CsvExport, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, type HandleAvailability, type ImageUploadInput, type ImageUploadTarget, type InvocationOptions, type NavigationAction, type OnboardingControllerProps, type OnboardingIntent, type OnboardingJourney, type OnboardingJourneyPosition, type OnboardingOrigin, type OnboardingStep, type OrgFailure, type OrgMemberAction, type OrgMemberCanSlice, type OrgMemberStanding, type OrgMemberStandingSlice, type OrgProgress, type OrganizationDetails, type OrganizationDraft, type OtpPendingState, type PayoutDraftChain, type PayoutDraftEntry, type PayrollGroupRow, type PayrollGroupsSlice, type PayrollRecipientOption, type PayrollRunActionsSlice, type PayrollRunAmountEntry, type PayrollRunAmountsSlice, type PayrollRunAssetSlice, type PayrollRunGroupOption, type PayrollRunPrefill, type PayrollRunRecipientsSlice, type PayrollRunStatus, type PayrollRunSummarySlice, type PayrollSummarySlice, type PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendMoneySourceError, type SendMoneySourceOption, type SendMoneySourceSlice, type SendResult, type SentPayment, type SentPayrollRun, type SignedOutState, type Slot, type SummaryWindow, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, type UseCapxulHandleAvailabilityReturn, type UseCapxulImageUploadReturn, type UseCapxulInviteMemberReturn, type UseCapxulOrgMembersOptions, type UseCapxulOrgMembersReturn, type UseCapxulOrgRolesOptions, type UseCapxulOrgRolesReturn, type UseCapxulOrgTreasuryOptions, type UseCapxulOrgTreasuryReturn, type UseCapxulOrgsReturn, type UseCapxulPayReturn, type UseCapxulPaymentReturn, type UseCapxulPaymentsReturn, type UseCapxulProfileReturn, type UseCapxulRedirectPaymentReturn, type UseCapxulUploadImageReturn, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHandleAvailability, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUploadImage };
+export { type AccountFailure, type AccountProgress, type ActionResult, type ActivityDetailSlice, type ActivityExportSlice, type ActivityFilterValues, type ActivityFiltersSlice, type ActivityLoadMoreSlice, type ActivityReceipt, type ActivityRow, type ActivityRowsSlice, type ActivitySearchSlice, type ActivitySummarySlice, type AuthenticatedState, type AuthenticationSlots, type CanReason, CapxulActivity, type CapxulActivityProps, type CapxulAuth, CapxulAuthenticationController, type CapxulBootstrapState, type CapxulBootstrapStatus, CapxulContacts, type CapxulContactsProps, CapxulDashboardAccess, type CapxulDashboardAccessProps, CapxulOnboardingController, CapxulOrgMember, type CapxulOrgMemberProps, CapxulPayroll, type CapxulPayrollProps, CapxulPayrollRun, type CapxulPayrollRunBlockedReason, type CapxulPayrollRunProps, CapxulProvider, type CapxulProviderProps, type CapxulSend, CapxulSendMoney, type CapxulSendMoneyBlockedReason, type CapxulSendMoneyProps, type Contact, type ContactRelationship, type ContactRow, type ContactsActor, type ContactsAddBlockedReason, type ContactsAddError, type ContactsAddSlice, type ContactsListOptions, type ContactsListSlice, type ContactsRefusal, type ContactsSummarySlice, type ControllerAction, type CreateOrganizationFailure, type CreateOrganizationSubmission, type CsvExport, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessProbe, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, type HandleAvailability, type ImageUploadInput, type ImageUploadTarget, type InvocationOptions, type NavigationAction, type OnboardingControllerProps, type OnboardingIntent, type OnboardingJourney, type OnboardingJourneyPosition, type OnboardingOrigin, type OnboardingStep, type OrgFailure, type OrgMemberAction, type OrgMemberCanSlice, type OrgMemberStanding, type OrgMemberStandingSlice, type OrgProgress, type OrganizationDetails, type OrganizationDraft, type OtpPendingState, type PayoutDraftChain, type PayoutDraftEntry, type PayrollGroupRow, type PayrollGroupsSlice, type PayrollRecipientOption, type PayrollRunActionsSlice, type PayrollRunAmountEntry, type PayrollRunAmountsSlice, type PayrollRunAssetSlice, type PayrollRunGroupOption, type PayrollRunPrefill, type PayrollRunRecipientsSlice, type PayrollRunStatus, type PayrollRunSummarySlice, type PayrollSummarySlice, type PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendMoneySourceError, type SendMoneySourceOption, type SendMoneySourceSlice, type SendResult, type SentPayment, type SentPayrollRun, type SignedOutState, type Slot, type SummaryWindow, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, type UseCapxulHandleAvailabilityReturn, type UseCapxulImageUploadReturn, type UseCapxulInviteMemberInput, type UseCapxulInviteMemberReturn, type UseCapxulOrgMembersOptions, type UseCapxulOrgMembersReturn, type UseCapxulOrgRolesOptions, type UseCapxulOrgRolesReturn, type UseCapxulOrgTreasuryOptions, type UseCapxulOrgTreasuryReturn, type UseCapxulOrgsReturn, type UseCapxulPayReturn, type UseCapxulPaymentReturn, type UseCapxulPaymentsReturn, type UseCapxulProfileReturn, type UseCapxulRedirectPaymentReturn, type UseCapxulUploadImageReturn, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHandleAvailability, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUploadImage };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { a as useCapxulAuth, c as useCapxulIdentityOrNull, d as capxulKeys, f as useCapxulClientOrNull, i as entered, l as useCapxulSend, n as CapxulOnboardingController, o as useCapxulDestination, p as useCapxul, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-BPEhjKX9.mjs";
+import { _ as useCapxul, a as useCapxulAuth, c as useCapxulIdentityOrNull, d as toInvocationControls, f as toInvocationOptions, g as useCapxulClientOrNull, h as capxulKeys, i as entered, l as useCapxulSend, m as actingAccount, n as CapxulOnboardingController, o as useCapxulDestination, p as accountKey, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-DXmEHrnw.mjs";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { CAPXUL_OPERATIONS, CapxulError, EVM_ADDRESS_RE, Errors, HANDLE_RE, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, fingerprintPaymentIntent, formatMoney, isCapxulError, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseMoney, paymentPhase, resolveIdentityDestination, toEvmAddress, toPartyId } from "@capxul/sdk";
@@ -47,8 +47,9 @@ function useCapxulProfile() {
 //#region src/hooks/use-capxul-account-balance.ts
 function useCapxulAccountBalance(options) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.accountBalance,
+		queryKey: accountKey(capxulKeys.accountBalance, identity),
 		queryFn: async () => {
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.accounts.read).accounts.read());
 		},
@@ -302,7 +303,7 @@ function useCapxulPayments(options) {
 	const client = useCapxulClientOrNull();
 	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.payments,
+		queryKey: accountKey(capxulKeys.payments, identity),
 		queryFn: async () => {
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.payments.list).payments.list());
 		},
@@ -311,8 +312,9 @@ function useCapxulPayments(options) {
 }
 function useCapxulPayment(paymentId, options) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.payment(paymentId),
+		queryKey: accountKey(capxulKeys.payment(paymentId), identity),
 		queryFn: async () => {
 			if (paymentId === void 0) throw Errors.invalidInput("paymentId", "required for payments.get");
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.payments.get).payments.get(paymentId));
@@ -430,7 +432,7 @@ function useCapxulActivity(params) {
 	const client = useCapxulClientOrNull();
 	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: [...capxulKeys.activity, params ?? {}],
+		queryKey: accountKey([...capxulKeys.activity, params ?? {}], identity),
 		queryFn: async () => {
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list).activity.list(params));
 		},
@@ -441,7 +443,7 @@ function useCapxulActivityDetail(reference, actor) {
 	const client = useCapxulClientOrNull();
 	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.activityDetail(reference, actor),
+		queryKey: accountKey(capxulKeys.activityDetail(reference, actor), identity),
 		queryFn: async () => {
 			if (reference === void 0) throw Errors.invalidInput("reference", "required for activity.get");
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.get).activity.get(reference, actor === void 0 ? void 0 : { actor }));
@@ -466,7 +468,7 @@ function useCapxulHoldings(params) {
 	const identity = useCapxulIdentityOrNull();
 	const actor = params?.actor;
 	return useQuery({
-		queryKey: capxulKeys.holdings(actor),
+		queryKey: accountKey(capxulKeys.holdings(actor), identity),
 		queryFn: async () => {
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.holdings.current).holdings.current(actor === void 0 ? void 0 : { actor }));
 		},
@@ -477,8 +479,9 @@ function useCapxulHoldings(params) {
 //#region src/hooks/use-capxul-orgs.ts
 function useCapxulOrgs(options) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.orgs,
+		queryKey: accountKey(capxulKeys.orgs, identity),
 		queryFn: async () => {
 			return unwrapCapxulResult(await requireBootstrappedClient(client, "orgs").orgs());
 		},
@@ -517,9 +520,10 @@ function useCapxulOrgRoles(orgId, options) {
 //#region src/hooks/use-capxul-org-treasury.ts
 function useCapxulOrgTreasury(orgId, options) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	const enabled = options?.enabled ?? true;
 	return useQuery({
-		queryKey: capxulKeys.orgTreasury(orgId),
+		queryKey: accountKey(capxulKeys.orgTreasury(orgId), identity),
 		queryFn: async () => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulOrgTreasury");
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.treasury).org(orgId).treasury());
@@ -547,9 +551,9 @@ function useCapxulInviteMember(orgId) {
 	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
 	return useMutation({
-		mutationFn: async (input) => {
+		mutationFn: async ({ options, ...input }) => {
 			if (orgId === void 0) throw Errors.invalidInput("orgId", "required for useCapxulInviteMember");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.invite).org(orgId).invite(input));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.invite).org(orgId).invite(input, toInvocationControls(options)));
 		},
 		onSuccess: async () => {
 			if (orgId === void 0) return;
@@ -879,6 +883,8 @@ function useCapxulUploadImage() {
 }
 //#endregion
 //#region src/headless/contacts/use-contacts.ts
+/** One captured snapshot, or nothing — never a fabricated empty options object. */
+const carry$1 = (options) => options === void 0 ? {} : { options };
 function useContacts(input) {
 	const { actor, onAdded, onFailed } = input;
 	const client = useCapxulClientOrNull();
@@ -895,35 +901,40 @@ function useContacts(input) {
 	const writeMutate = useMutation({
 		mutationFn: async (command) => {
 			const target = requireBook(book, `addressBook.${command.kind}`);
+			const controls = toInvocationControls(command.options);
 			return unwrapCapxulResult(command.kind === "rename" ? await target.label({
 				entryId: command.id,
 				label: command.name
-			}) : command.kind === "hide" ? await target.hide(command.id) : await target.unhide(command.id));
+			}, controls) : command.kind === "hide" ? await target.hide(command.id, controls) : await target.unhide(command.id, controls));
 		},
 		onSettled: invalidate,
-		onError: onFailed
+		onError: (error, command) => onFailed(error, command.options)
 	}).mutate;
 	const [value, setValue] = useState("");
 	const [addError, setAddError] = useState(null);
 	const addContact = useMutation({
-		mutationFn: async (ref) => unwrapCapxulResult(await requireBook(book, CAPXUL_OPERATIONS.addressBook.add).add({ ref })),
+		mutationFn: async (command) => unwrapCapxulResult(await requireBook(book, CAPXUL_OPERATIONS.addressBook.add).add({ ref: command.ref }, toInvocationControls(command.options))),
 		onSettled: invalidate
 	});
 	const addMutate = addContact.mutate;
 	const blockedReason = refusal !== null ? "org-unavailable" : value.trim() === "" ? "empty" : null;
 	const submitGate = useRef(false);
-	const submit = useCallback(() => {
+	const submit = useCallback((options) => {
 		if (blockedReason !== null || submitGate.current) return;
+		const attempt = toInvocationOptions(options);
 		submitGate.current = true;
 		setAddError(null);
-		addMutate(refFromTypedText(value), {
+		addMutate({
+			ref: refFromTypedText(value),
+			...carry$1(attempt)
+		}, {
 			onSuccess: (entry) => {
 				setValue("");
-				onAdded(toContact(entry));
+				onAdded(toContact(entry), attempt);
 			},
 			onError: (error) => {
 				setAddError(error.code === "INVALID_INPUT" ? "unresolved" : "failed");
-				onFailed(error);
+				onFailed(error, attempt);
 			},
 			onSettled: () => {
 				submitGate.current = false;
@@ -944,18 +955,21 @@ function useContacts(input) {
 		book,
 		scope,
 		refusal,
-		rename: useCallback((id, name) => writeMutate({
+		rename: useCallback((id, name, options) => writeMutate({
 			kind: "rename",
 			id,
-			name
+			name,
+			...carry$1(toInvocationOptions(options))
 		}), [writeMutate]),
-		hide: useCallback((id) => writeMutate({
+		hide: useCallback((id, options) => writeMutate({
 			kind: "hide",
-			id
+			id,
+			...carry$1(toInvocationOptions(options))
 		}), [writeMutate]),
-		unhide: useCallback((id) => writeMutate({
+		unhide: useCallback((id, options) => writeMutate({
 			kind: "unhide",
-			id
+			id,
+			...carry$1(toInvocationOptions(options))
 		}), [writeMutate]),
 		add: {
 			value,
@@ -973,10 +987,11 @@ function useContacts(input) {
 * query key, so React Query issues ONE request for them.
 */
 function useContactsList(engine, options) {
+	const identity = useCapxulIdentityOrNull();
 	const includeHidden = options.show === "all";
 	const { book, refusal } = engine;
 	const query = useQuery({
-		queryKey: capxulKeys.contactsList(engine.scope, includeHidden),
+		queryKey: accountKey(capxulKeys.contactsList(engine.scope, includeHidden), identity),
 		queryFn: async () => unwrapCapxulResult(await requireBook(book, CAPXUL_OPERATIONS.addressBook.list).list({ includeHidden })),
 		enabled: book !== null
 	});
@@ -989,9 +1004,9 @@ function useContactsList(engine, options) {
 			if (entries === void 0) return [];
 			return (limit === void 0 ? entries : entries.slice(0, limit)).map((entry) => Object.assign(toContact(entry), {
 				initials: initialsOf(entry.label),
-				rename: (name) => rename(entry.id, name),
-				hide: () => hide(entry.id),
-				unhide: () => unhide(entry.id)
+				rename: (name, attempt) => rename(entry.id, name, attempt),
+				hide: (attempt) => hide(entry.id, attempt),
+				unhide: (attempt) => unhide(entry.id, attempt)
 			}));
 		}, [
 			entries,
@@ -1165,9 +1180,10 @@ function activityDetailKey(actor, reference) {
 }
 function useActivityDetail(reference, actor) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	const enabled = useActivityEnabled() && reference !== void 0;
 	const detail = useQuery({
-		queryKey: capxulKeys.activityDetail(reference, actor),
+		queryKey: accountKey(capxulKeys.activityDetail(reference, actor), identity),
 		queryFn: async () => {
 			if (reference === void 0) throw Errors.invalidInput("reference", "required for activity.get");
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.get).activity.get(reference, actor === void 0 ? void 0 : { actor }));
@@ -1322,10 +1338,11 @@ function useUtcDay(active) {
 }
 function useActivitySummary(actor, window) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	const enabled = useActivityEnabled();
 	const range = resolveWindow(window, useUtcDay(window === "last30days") * DAY_MS);
 	const summary = useQuery({
-		queryKey: capxulKeys.activitySummary(actor, range),
+		queryKey: accountKey(capxulKeys.activitySummary(actor, range), identity),
 		queryFn: async () => {
 			const params = {};
 			if (actor !== void 0) params.actor = actor;
@@ -1335,7 +1352,7 @@ function useActivitySummary(actor, window) {
 		enabled
 	});
 	const primary = useQuery({
-		queryKey: [...capxulKeys.holdings(actor), "primary"],
+		queryKey: accountKey([...capxulKeys.holdings(actor), "primary"], identity),
 		queryFn: async () => {
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.holdings.primary).holdings.primary(actor === void 0 ? void 0 : { actor }));
 		},
@@ -1357,7 +1374,8 @@ function useActivitySummary(actor, window) {
 		pending: null,
 		count: summary.data?.count ?? 0,
 		isLoading,
-		error: asCapxulError$1(summary.error)
+		error: asCapxulError$1(summary.error),
+		...summary.data?.readWarning === void 0 ? {} : { readWarning: summary.data.readWarning }
 	};
 	const display = (raw) => formatMoney({
 		currency: bucket.currency,
@@ -1372,7 +1390,8 @@ function useActivitySummary(actor, window) {
 		pending: display(bucket.pendingIn),
 		count: summary.data?.count ?? 0,
 		isLoading,
-		error: asCapxulError$1(summary.error)
+		error: asCapxulError$1(summary.error),
+		...summary.data?.readWarning === void 0 ? {} : { readWarning: summary.data.readWarning }
 	};
 }
 //#endregion
@@ -1538,6 +1557,8 @@ function clampPageSize(pageSize) {
 function useActivity(input) {
 	const { actor, pageSize } = input;
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
+	const account = actingAccount(identity);
 	const enabled = useActivityEnabled();
 	const limit = clampPageSize(pageSize);
 	const warned = useRef(false);
@@ -1567,21 +1588,51 @@ function useActivity(input) {
 		if (filter !== void 0) params.filter = filter;
 		return params;
 	}, [actor, filter]);
+	const selectedRetry = useRef(void 0);
+	const takeSelectedRetry = useCallback(() => {
+		const attempt = selectedRetry.current;
+		selectedRetry.current = void 0;
+		return toInvocationControls(attempt);
+	}, []);
 	const query = useInfiniteQuery({
-		queryKey: [
+		queryKey: accountKey([
 			...capxulKeys.activity,
 			"list",
 			actor ?? "self",
 			limit,
 			filter ?? "none"
-		],
+		], identity),
 		queryFn: async ({ pageParam }) => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list).activity.list(listParams(pageParam, limit)));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list).activity.list(listParams(pageParam, limit), takeSelectedRetry()));
 		},
 		initialPageParam: void 0,
 		getNextPageParam: (last) => last.cursor ?? void 0,
 		enabled
 	});
+	const queryClient = useQueryClient();
+	useEffect(() => {
+		if (!enabled || client === null) return;
+		let stop;
+		let cancelled = false;
+		client.activity.subscribe(() => {
+			if (cancelled) return;
+			queryClient.invalidateQueries({ queryKey: capxulKeys.activity });
+		}, actor === void 0 ? void 0 : { actor }).then((result) => {
+			if (!result.ok) return;
+			if (cancelled) result.value();
+			else stop = result.value;
+		});
+		return () => {
+			cancelled = true;
+			stop?.();
+		};
+	}, [
+		account,
+		actor,
+		client,
+		enabled,
+		queryClient
+	]);
 	const pages = query.data?.pages;
 	const rows = useMemo(() => {
 		return (pages?.flatMap((page) => page.items) ?? []).map((item) => toActivityRow(item, actor)).filter((row) => matchesSearch(row, searchText));
@@ -1624,21 +1675,25 @@ function useActivity(input) {
 		observerRef.current = observer;
 	}, [loadMore]);
 	const [isExporting, setIsExporting] = useState(false);
-	const toCsv = useCallback(async () => {
+	const toCsv = useCallback(async (options) => {
 		setIsExporting(true);
+		const controls = toInvocationControls(toInvocationOptions(options));
 		try {
 			const bootstrapped = requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.list);
 			const items = [];
+			let readWarning;
 			let cursor;
 			for (let page = 0; page < EXPORT_PAGE_CEILING; page += 1) {
-				const result = unwrapCapxulResult(await bootstrapped.activity.list(listParams(cursor, EXPORT_PAGE_SIZE)));
+				const result = unwrapCapxulResult(await bootstrapped.activity.list(listParams(cursor, EXPORT_PAGE_SIZE), controls));
+				readWarning ??= result.readWarning;
 				items.push(...result.items);
 				cursor = result.cursor ?? void 0;
 				if (cursor === void 0) break;
 			}
 			return {
 				...buildCsv(items, actor, searchText),
-				truncated: cursor !== void 0
+				truncated: cursor !== void 0,
+				...readWarning === void 0 ? {} : { readWarning }
 			};
 		} finally {
 			setIsExporting(false);
@@ -1654,9 +1709,19 @@ function useActivity(input) {
 		setDirection(void 0);
 		setStatus([]);
 	}, []);
-	const retry = useCallback(() => {
+	const retry = useCallback((options) => {
+		selectedRetry.current = toInvocationOptions(options);
 		refetch();
-	}, [refetch]);
+		queryClient.invalidateQueries({
+			queryKey: capxulKeys.activitySummary(actor).slice(0, -1),
+			predicate: (cached) => cached.queryKey.at(-1) === accountKey([], identity)[0]
+		});
+	}, [
+		actor,
+		identity,
+		queryClient,
+		refetch
+	]);
 	return {
 		actor,
 		filters: {
@@ -1682,7 +1747,8 @@ function useActivity(input) {
 			isLoading: query.isLoading,
 			error: asCapxulError$1(query.error),
 			retry,
-			observedAt: pages === void 0 ? null : pages[pages.length - 1]?.observedAt ?? null
+			observedAt: pages === void 0 ? null : pages[pages.length - 1]?.observedAt ?? null,
+			...pages?.some((page) => page.readWarning === "indexer-unavailable") ? { readWarning: "indexer-unavailable" } : {}
 		},
 		loadMore: {
 			hasMore: hasNextPage,
@@ -1744,11 +1810,12 @@ function DetailInstance({ actor, reference, children }) {
 }
 function Detail({ reference, children }) {
 	const { actor } = useActivityContext();
+	const identity = useCapxulIdentityOrNull();
 	return /* @__PURE__ */ jsx(DetailInstance, {
 		actor,
 		reference,
 		children
-	}, activityDetailKey(actor, reference));
+	}, JSON.stringify(accountKey([activityDetailKey(actor, reference)], identity)));
 }
 function Export({ children }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivityContext().csv) });
@@ -1771,7 +1838,7 @@ function useOrgMeReading(orgId) {
 	const ready = client !== null && identity !== null && isClaimed$1(identity);
 	const mayStillOpen = client === null || identity === null || isRestoring$1(identity);
 	const query = useQuery({
-		queryKey: capxulKeys.orgMe(orgId),
+		queryKey: capxulKeys.orgMe(orgId, actingAccount(identity)),
 		queryFn: async () => {
 			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.org.me).org(orgId).me());
 		},
@@ -2275,6 +2342,16 @@ function decidePhase(input) {
 	if (input.orgLaneSettled && input.destination !== null) return "redirect";
 	return "checking";
 }
+/**
+* Which probe produced the surfaced error — the SAME precedence `error` itself
+* is chosen by, written once so the code and its source can never disagree.
+*/
+function probeOf(session, membership, lifecycle) {
+	if (session !== null) return "session";
+	if (membership !== null) return "membership";
+	if (lifecycle !== null) return "lifecycle";
+	return null;
+}
 /** The engine — all the logic. NOT exported from the package barrel. */
 function useDashboardAccess(scope) {
 	const client = useCapxulClientOrNull();
@@ -2311,6 +2388,7 @@ function useDashboardAccess(scope) {
 		lifecycle.refetch
 	]);
 	const error = sessionError ?? membershipError ?? lifecycleError;
+	const probe = probeOf(sessionError, membershipError, lifecycleError);
 	const phase = decidePhase({
 		error,
 		settled: client !== null && identity !== null && !isRestoring$1(identity) && membershipsSettled && lifecycleSettled,
@@ -2321,11 +2399,13 @@ function useDashboardAccess(scope) {
 	return useMemo(() => ({
 		phase,
 		error,
+		probe,
 		destination,
 		retry
 	}), [
 		phase,
 		error,
+		probe,
 		destination,
 		retry
 	]);
@@ -2370,12 +2450,19 @@ function Checking({ children }) {
 }
 function DashboardError({ children }) {
 	const state = usePart("error");
-	if (state === null || state.error === null) return null;
+	if (state === null || state.error === null || state.probe === null) return null;
 	return /* @__PURE__ */ jsx(Fragment, { children: children({
 		error: state.error,
+		probe: state.probe,
 		retry: state.retry
 	}) });
 }
+/**
+* Hands the destination and draws nothing. Reaching this part is a REQUEST to
+* navigate, never an arrival: the app may cancel or supersede it, so nothing
+* here — and nothing a consumer hangs off it — may claim a completed redirect
+* (#1963 R05-1). The destination page's own normalized pageview proves arrival.
+*/
 function Redirect({ children }) {
 	const state = usePart("redirect");
 	if (state === null || state.destination === null) return null;
@@ -2452,8 +2539,9 @@ function toRecipientOption(entry) {
 */
 function useOrgRoster(orgId) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	const query = useQuery({
-		queryKey: capxulKeys.contactsList(orgId ?? "pending", false),
+		queryKey: accountKey(capxulKeys.contactsList(orgId ?? "pending", false), identity),
 		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.addressBook.list, orgId).addressBook.list({ includeHidden: false })),
 		enabled: client !== null && orgId !== void 0
 	});
@@ -2474,16 +2562,18 @@ function useOrgRoster(orgId) {
 }
 function usePayrollGroups(orgId) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.payrollGroups(orgId),
+		queryKey: accountKey(capxulKeys.payrollGroups(orgId), identity),
 		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.groups.list, orgId).payroll.groups.list()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
 function usePayrollRuns(orgId) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.payrollRuns(orgId),
+		queryKey: accountKey(capxulKeys.payrollRuns(orgId), identity),
 		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.runs, orgId).payroll.runs()),
 		enabled: client !== null && orgId !== void 0
 	});
@@ -2498,29 +2588,34 @@ function usePayrollRuns(orgId) {
 */
 function useOrgTerms(orgId) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.payrollTerms(orgId),
+		queryKey: accountKey(capxulKeys.payrollTerms(orgId), identity),
 		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.terms, orgId).payroll.terms()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
 function useOrgTreasury(orgId) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.orgTreasury(orgId),
+		queryKey: accountKey(capxulKeys.orgTreasury(orgId), identity),
 		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.treasury, orgId).treasury()),
 		enabled: client !== null && orgId !== void 0
 	});
 }
 /**
 * The caller's own standing, read for its Budgets alone (ruling Q2 grades
-* them). Keyed as `CapxulOrgMember` keys it, so a payroll screen inside a
-* `.Can` wrapper reads `org(id).me()` once.
+* them). Keyed as `CapxulOrgMember` keys it — Organization AND acting account
+* (#2007 R19) — so a payroll screen inside a `.Can` wrapper still reads
+* `org(id).me()` once, and an account replacement is a miss for both of them
+* rather than the previous person's Budgets for both.
 */
 function useOrgMe(orgId) {
 	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.orgMe(orgId),
+		queryKey: capxulKeys.orgMe(orgId, actingAccount(identity)),
 		queryFn: async () => unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.me, orgId).me()),
 		enabled: client !== null && orgId !== void 0
 	});
@@ -2539,6 +2634,14 @@ function scopedClient(client, method, orgId) {
 //#region src/headless/payroll/use-payroll.ts
 /** Money reads the same way everywhere on this screen: amount then code. */
 const GRAMMAR$1 = { grammar: "code" };
+/**
+* One captured snapshot, or nothing — never a fabricated empty options object,
+* and never a DOM event a screen wired straight to `onClick`.
+*/
+function carry(options) {
+	const attempt = toInvocationOptions(options);
+	return attempt === void 0 ? {} : { options: attempt };
+}
 function toPayrollGroupRow(group) {
 	const currency = new Set(group.members.map((member) => member.currency)).size === 1 ? group.members[0]?.currency : void 0;
 	return {
@@ -2578,16 +2681,17 @@ function usePayroll(orgId) {
 	const write = useMutation({
 		mutationFn: async (command) => {
 			const payroll = scopedClient(client, CAPXUL_OPERATIONS.org.payroll.groups[command.kind], orgId).payroll;
+			const controls = toInvocationControls(command.options);
 			if (command.kind === "remove") {
-				unwrapCapxulResult(await payroll.groups.remove(command.id));
+				unwrapCapxulResult(await payroll.groups.remove(command.id, controls));
 				return null;
 			}
-			return unwrapCapxulResult(await payroll.groups.save(command.input));
+			return unwrapCapxulResult(await payroll.groups.save(command.input, controls));
 		},
 		onSettled: invalidate
 	});
 	const mutateAsync = write.mutateAsync;
-	const save = useCallback(async (input) => {
+	const save = useCallback(async (input, options) => {
 		const refusal = invalidGroup(input);
 		if (refusal !== null) return {
 			ok: false,
@@ -2596,7 +2700,8 @@ function usePayroll(orgId) {
 		try {
 			const saved = await mutateAsync({
 				kind: "save",
-				input
+				input,
+				...carry(options)
 			});
 			return saved === null ? {
 				ok: false,
@@ -2612,11 +2717,12 @@ function usePayroll(orgId) {
 			};
 		}
 	}, [mutateAsync]);
-	const remove = useCallback(async (id) => {
+	const remove = useCallback(async (id, options) => {
 		try {
 			await mutateAsync({
 				kind: "remove",
-				id
+				id,
+				...carry(options)
 			});
 			return {
 				ok: true,
@@ -3134,11 +3240,12 @@ function usePayrollRun(input) {
 		amountsParse: total !== null
 	});
 	const authorize = useMutation({
-		mutationFn: async (candidate) => {
+		mutationFn: async ({ candidate, options }) => {
 			if (candidate.scope !== currentScope.current) throw Errors.notAuthenticated();
 			return executeRunDraft(candidate, async (persisted, onRequestKey, onResolved) => {
 				if (candidate.scope === currentScope.current) setDraft(persisted);
 				return unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.authorizeRun, orgId).payroll.authorizeRun(persisted.input, {
+					...toInvocationControls(options),
 					onResolved,
 					onRequestKey: (key) => {
 						if (candidate.scope !== currentScope.current) throw Errors.notAuthenticated();
@@ -3147,14 +3254,15 @@ function usePayrollRun(input) {
 				}));
 			});
 		},
-		onSettled: (_run, _error, candidate) => {
+		onSettled: (_run, _error, { candidate }) => {
 			queryClient.invalidateQueries({ queryKey: capxulKeys.payrollRuns(orgId) });
 			if (candidate.scope === currentScope.current) restoreDraft(candidate.scope);
 		}
 	});
 	const totalDisplay = total === null ? null : formatMoney(total, GRAMMAR);
 	const authorizeMutate = authorize.mutate;
-	const submit = useCallback(() => {
+	const submit = useCallback((options) => {
+		const attempt = toInvocationOptions(options);
 		const permissionId = budgets[0]?.id;
 		if (blockedReason !== null || submitGate.current || draftBlocked || draftScope === null || assetMoney === null || selectedAsset === null) return;
 		if (permissionId === void 0 || totalDisplay === null || parsedAmounts === null) return;
@@ -3196,7 +3304,10 @@ function usePayrollRun(input) {
 			}
 		};
 		submitGate.current = true;
-		authorizeMutate(candidate, {
+		authorizeMutate({
+			candidate,
+			...attempt === void 0 ? {} : { options: attempt }
+		}, {
 			onSuccess: (run) => {
 				if (candidate.scope === currentScope.current) onRun({
 					id: run.id,

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-BPEhjKX9.mjs";
+import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-DXmEHrnw.mjs";
 import "react";
 import { jsx } from "react/jsx-runtime";
 import { createCapxulTestClient } from "@capxul/sdk/testing";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "4.2.0",
+  "version": "4.20.0-beta.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "4.2.0"
+    "@capxul/sdk": "4.20.0-beta.1"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",