@capxul/sdk-react 4.2.0-rc.3 → 4.2.0-rc.5

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/capxul-source.json

@@ -1,11 +1,11 @@
 {
   "source": {
-    "commit": "4547e113caca6cf936b489dda3c22c68ea2f30d8",
-    "tree": "6ccaeaf77b6d8fef28eacd312d0b884a383c502f",
+    "commit": "72be9c2d5c9b2dcdd27fa5c5acb22163ddec5c44",
+    "tree": "1529290d3427ecf12fece6ff70fbea35b077b6a9",
     "branch": "codex/programme-rc",
     "repository": "https://github.com/Xelmar-tech/infrastructure",
     "lockfileSha256": "5870f53b72706d103220c1bcf733cb4fb71196aea32a9cfbdc277d73cc959264"
   },
   "name": "@capxul/sdk-react",
-  "version": "4.2.0-rc.3"
+  "version": "4.2.0-rc.5"
 }

package/dist/{controllers-BWmKRFy6.d.mts → controllers-COGAAS-c.d.mts}

@@ -106,11 +106,23 @@ type AccountProgress = Exclude<Readiness, {
 type AccountFailure = Extract<Readiness, {
   at: "failed";
 }>;
+/**
+ * The Organization lane while it still owes an answer. `loading` widens the
+ * lane's `orgId` to `string | null`: after a reload the SDK asks the backend
+ * whether a setup is pending, and until that read lands the claimed identity
+ * holds no Organization id at all. The identity model keeps its own `loading`
+ * id non-null — only this slot type carries the pre-attach window.
+ */
 type OrgProgress = Exclude<OrgLane, {
   at: "failed";
 } | {
   at: "ready";
-}>;
+} | {
+  at: "loading";
+}> | {
+  readonly at: "loading";
+  readonly orgId: string | null;
+};
 type OrgFailure = Extract<OrgLane, {
   at: "failed";
 }>;
@@ -157,11 +169,8 @@ type ProfileSlotProps = {
 interface OnboardingControllerProps {
   readonly intent: "personal" | "organization" | null;
   readonly organizationProfile: ProfileDetails | null;
-  readonly submittedOrganization: CreateOrganizationSubmission | null;
-  readonly recoveryOptions?: () => InvocationOptions;
   readonly onIntent: (intent: "personal" | "organization") => void;
   readonly onOrganizationProfile: (profile: ProfileDetails | null) => void;
-  readonly onSubmittedOrganization: (submission: CreateOrganizationSubmission | null) => void;
   readonly navigation: {
     readonly selectorBack: NavigationAction;
     readonly profileCancel: NavigationAction;
@@ -178,8 +187,6 @@ interface OnboardingControllerProps {
     readonly organization: Slot<{
       state: AuthenticatedState;
       profileDetails: ProfileDetails;
-      submitted: CreateOrganizationSubmission | null;
-      pinnedHandle: string | null;
       submit: (organization: OrganizationDetails, options: InvocationOptions) => ReturnType<CapxulAuth["createOrganization"]>;
       back: NavigationAction;
       cancel: NavigationAction;

package/dist/{controllers-ByS8ZrVm.mjs → controllers-DHXq3gJY.mjs}

@@ -151,10 +151,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 +189,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,12 +244,61 @@ 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);
@@ -303,13 +381,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,
@@ -386,12 +464,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,
@@ -406,6 +485,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
@@ -435,13 +519,6 @@ function createAuth(client, clearAuthenticatedQueries) {
 			const event = state.phase === "authenticated" && state.account.at === "claimed" ? { _tag: "RetryOrganization" } : { _tag: "RetryAccount" };
 			const result = await runtime.send(event, invocation);
 			return failure(result) ?? { ok: true };
-		}),
-		resumeSubmittedOrganization: (submission, options) => guarded(runtime, "createOrganization", options, async (invocation) => {
-			const prepared = await prepareOrganization(submission, invocation);
-			return prepared.ok ? { ok: true } : {
-				ok: false,
-				reason: prepared.reason
-			};
 		})
 	};
 }
@@ -487,17 +564,15 @@ 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 });
 		};
-		const auth = createAuth(client, clearAuthenticatedQueries);
 		return {
 			runtime,
 			send,
-			auth,
-			resumeSubmittedOrganization: auth.resumeSubmittedOrganization,
+			auth: createAuth(client, clearAuthenticatedQueries),
 			addTransitionListener
 		};
 	}, [
@@ -535,9 +610,6 @@ function useCapxulSend() {
 function useCapxulAuth() {
 	return useIdentityContext().auth;
 }
-function useResumeSubmittedOrganization() {
-	return useIdentityContext().resumeSubmittedOrganization;
-}
 function useCapxulDestination() {
 	const state = useCapxulIdentity();
 	const next = resolveIdentityDestination(state);
@@ -748,29 +820,24 @@ function CapxulAuthenticationController({ slots }) {
 function ready(destination) {
 	return destination?.to === "dashboardPersonal" || destination?.to === "dashboardOrganization";
 }
+/**
+* The pre-attach window: a claimed identity holding no Organization while the
+* SDK asks the backend whether one is pending. The controller reports progress
+* only when no form step is left to render. An app that still holds an
+* Organization profile and has not submitted through this mount is entering
+* the form, not resuming it — a member who starts an Organization from the
+* dashboard is claimed with a complete Profile before they ever see the form,
+* so reporting progress on the claim alone would hide the form for good.
+*/
+const ATTACHING = {
+	at: "loading",
+	orgId: null
+};
 function CapxulOnboardingController(props) {
 	const state = useCapxulIdentity();
 	const destination = useCapxulDestination();
 	const auth = useCapxulAuth();
-	const resumeSubmittedOrganization = useResumeSubmittedOrganization();
-	const resumedSubmission = useRef(null);
-	const [failedRecovery, setFailedRecovery] = useState(null);
-	const submission = props.submittedOrganization;
-	const accountAt = state.phase === "authenticated" ? state.account.at : null;
-	useEffect(() => {
-		if (props.intent !== "organization" || submission === null || props.recoveryOptions === void 0 || accountAt !== "unknown" && accountAt !== "counterfactual" || resumedSubmission.current === submission) return;
-		resumedSubmission.current = submission;
-		setFailedRecovery(null);
-		resumeSubmittedOrganization(submission, props.recoveryOptions()).then((result) => {
-			if (!result.ok) setFailedRecovery(submission);
-		});
-	}, [
-		accountAt,
-		props.intent,
-		props.recoveryOptions,
-		resumeSubmittedOrganization,
-		submission
-	]);
+	const submitted = useRef(false);
 	if (state.phase !== "authenticated") return null;
 	const { slots, navigation } = props;
 	if (props.intent === null) return slots.intent({
@@ -784,37 +851,24 @@ function CapxulOnboardingController(props) {
 		completePersonal: auth.completePersonal,
 		cancel: navigation.profileCancel
 	});
-	if (props.intent === "organization" && props.organizationProfile === null && submission === null) return slots.profile({
+	if (props.intent === "organization" && !state.profileComplete) return props.organizationProfile === null ? slots.profile({
 		intent: "organization",
 		state,
 		continueOrganization: props.onOrganizationProfile,
 		cancel: navigation.profileCancel
-	});
-	if (props.intent === "organization" && props.organizationProfile !== null && submission === null) return organizationForm(props, state, auth, null);
-	if (submission !== null && failedRecovery === submission && state.account.at !== "claimed") return organizationForm(props, state, auth, submission);
-	if (submission !== null && state.account.at !== "claimed") {
-		if (state.account.at === "failed") {
-			const retry = state.account.retryable ? (options) => auth.createOrganization(submission, options) : void 0;
-			return slots.accountFailure({
-				state,
-				account: state.account,
-				...retry === void 0 ? {} : { retry }
-			});
-		}
-		return slots.accountProgress({
-			state,
-			account: state.account
-		});
-	}
-	if (submission !== null && state.account.at === "claimed") {
+	}) : organizationForm(props, state, auth, submitted);
+	if (props.intent === "organization" && state.account.at === "claimed") {
 		const org = state.account.org;
-		if (org === null) return organizationForm(props, state, auth, submission);
+		if (org === null) return props.organizationProfile === null || submitted.current ? slots.organizationProgress({
+			state,
+			org: ATTACHING
+		}) : organizationForm(props, state, auth, submitted);
 		if (org.at === "failed") {
-			const retry = org.retryable ? org.orgId === null ? (options) => auth.createOrganization(submission, options) : auth.retry : void 0;
+			const retryable = org.retryable && org.orgId !== null;
 			return slots.organizationFailure({
 				state,
 				org,
-				...retry === void 0 ? {} : { retry }
+				...retryable ? { retry: auth.retry } : {}
 			});
 		}
 		if (org.at !== "ready") return slots.organizationProgress({
@@ -837,26 +891,20 @@ function CapxulOnboardingController(props) {
 	}) : null;
 }
 function organizationForm(props, state, auth, submitted) {
-	const profileDetails = submitted?.profileDetails ?? props.organizationProfile;
+	const profileDetails = props.organizationProfile;
 	if (profileDetails === null) return null;
 	return props.slots.organization({
 		state,
 		profileDetails,
-		submitted,
-		pinnedHandle: submitted?.organization.handle ?? null,
 		submit: (organization, options) => {
-			if (submitted !== null) return auth.createOrganization(submitted, options);
-			const normalized = normalizeOrganization(organization);
-			if (normalized === null) return auth.createOrganization({
+			submitted.current = true;
+			return auth.createOrganization({
 				profileDetails,
 				organization
-			}, options);
-			const next = {
-				profileDetails,
-				organization: normalized
-			};
-			props.onSubmittedOrganization(next);
-			return auth.createOrganization(next, options);
+			}, options).then((result) => {
+				if (!result.ok) submitted.current = false;
+				return result;
+			});
 		},
 		back: () => {
 			props.onOrganizationProfile(null);
@@ -866,4 +914,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 { useCapxulAuth as a, useCapxulIdentityOrNull as c, toInvocationControls as d, toInvocationOptions as f, useCapxul as h, entered as i, useCapxulSend as l, useCapxulClientOrNull as m, CapxulOnboardingController as n, useCapxulDestination as o, capxulKeys as p, CapxulProvider as r, useCapxulIdentity as s, CapxulAuthenticationController as t, useCapxulTransitions as u };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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 { 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-COGAAS-c.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";
@@ -383,9 +383,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 +421,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 +437,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;
@@ -545,7 +556,12 @@ interface ActivityRowsSlice {
   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;
 }
@@ -589,7 +605,8 @@ interface CsvExport {
   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

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-ByS8ZrVm.mjs";
+import { a as useCapxulAuth, c as useCapxulIdentityOrNull, d as toInvocationControls, f as toInvocationOptions, h as useCapxul, i as entered, l as useCapxulSend, m as useCapxulClientOrNull, n as CapxulOnboardingController, o as useCapxulDestination, p as capxulKeys, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-DHXq3gJY.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";
@@ -879,6 +879,8 @@ function useCapxulUploadImage() {
 }
 //#endregion
 //#region src/headless/contacts/use-contacts.ts
+/** One captured snapshot, or nothing — never a fabricated empty options object. */
+const carry = (options) => options === void 0 ? {} : { options };
 function useContacts(input) {
 	const { actor, onAdded, onFailed } = input;
 	const client = useCapxulClientOrNull();
@@ -895,35 +897,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(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 +951,21 @@ function useContacts(input) {
 		book,
 		scope,
 		refusal,
-		rename: useCallback((id, name) => writeMutate({
+		rename: useCallback((id, name, options) => writeMutate({
 			kind: "rename",
 			id,
-			name
+			name,
+			...carry(toInvocationOptions(options))
 		}), [writeMutate]),
-		hide: useCallback((id) => writeMutate({
+		hide: useCallback((id, options) => writeMutate({
 			kind: "hide",
-			id
+			id,
+			...carry(toInvocationOptions(options))
 		}), [writeMutate]),
-		unhide: useCallback((id) => writeMutate({
+		unhide: useCallback((id, options) => writeMutate({
 			kind: "unhide",
-			id
+			id,
+			...carry(toInvocationOptions(options))
 		}), [writeMutate]),
 		add: {
 			value,
@@ -989,9 +999,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,
@@ -1567,6 +1577,12 @@ 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: [
 			...capxulKeys.activity,
@@ -1576,7 +1592,7 @@ function useActivity(input) {
 			filter ?? "none"
 		],
 		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,
@@ -1624,14 +1640,15 @@ 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 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));
 				items.push(...result.items);
 				cursor = result.cursor ?? void 0;
 				if (cursor === void 0) break;
@@ -1654,7 +1671,8 @@ function useActivity(input) {
 		setDirection(void 0);
 		setStatus([]);
 	}, []);
-	const retry = useCallback(() => {
+	const retry = useCallback((options) => {
+		selectedRetry.current = toInvocationOptions(options);
 		refetch();
 	}, [refetch]);
 	return {

package/dist/testing/index.d.mts

@@ -1,4 +1,4 @@
-import { a as AuthenticationSlots, d as OnboardingControllerProps } from "../controllers-BWmKRFy6.mjs";
+import { a as AuthenticationSlots, d as OnboardingControllerProps } from "../controllers-COGAAS-c.mjs";
 import * as React from "react";
 import { ReactNode } from "react";
 import { CapxulTestClient, CapxulTestClock, CapxulTestObservation, CreateCapxulTestClientOptions, SeedTestIdentityInput, createCapxulTestClient } from "@capxul/sdk/testing";

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-ByS8ZrVm.mjs";
+import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-DHXq3gJY.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-rc.3",
+  "version": "4.2.0-rc.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "4.2.0-rc.3"
+    "@capxul/sdk": "4.2.0-rc.5"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",