@capxul/sdk 4.0.0 → 4.1.0

package/dist/{create-capxul-client-DyCEJZtD.mjs → create-capxul-client-rpLwGwD-.mjs}

@@ -1,5 +1,5 @@
 import { $ as CapxulError, A as toAuthUserId, C as WEI_RE, D as toAddress, E as toAccountId, G as toPayrollRunId, H as toOrgId, I as toEmail, M as toChainId, N as toCountryCode, P as toCurrencyCode, Q as CAPXUL_ERROR_CODES, S as SUPPORTED_CURRENCY_CODES, U as toPartyId, W as toPayrollGroupId, _ as deriveCapxulSafeAddress, at as boundedResponseHeaders, b as BYTES32_RE, ct as decodeChainCause, dt as isFailureMode, et as EXPECTED_OPERATION_OUTCOMES, ft as revertSummaryText, it as FAILURE_MODES$1, j as toBudgetId, lt as failureFingerprint, mt as redactSecrets, n as InMemoryAuthCacheAdapter, nt as isCapxulError, ot as chainCauseProperties, p as orgRoleKeyForLabel, pt as containsSensitiveMaterial, q as toRoleKey, r as BrowserAuthCacheAdapter, rt as CHAIN_UPSTREAMS, st as chainEvidenceLabel, tt as Errors, ut as isChainUpstream, v as validateHandle, w as ZERO_BYTES32, x as EVM_ADDRESS_RE$1, y as APP_ID_RE } from "./clock-C2AUlq1V.mjs";
-import { Context, Data, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Ref, Result, Schema, SchemaGetter, SchemaParser, Scope } from "effect";
+import { Cause, Clock, Context, Data, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Ref, Result, Schema, SchemaGetter, SchemaParser, Scope } from "effect";
 import { formatUnits, keccak256, parseUnits, recoverAddress, toBytes } from "viem";
 import { makeFunctionReference } from "convex/server";
 //#region src/domain/identity/model.ts
@@ -440,12 +440,14 @@ const CAPXUL_OPERATIONS = {
 	},
 	activity: {
 		annotate: "activity.annotate",
+		emitAnnotationSaved: "activity.emitAnnotationSaved",
 		get: "activity.get",
 		list: "activity.list",
 		summary: "activity.summary"
 	},
 	addressBook: {
 		add: "addressBook.add",
+		emitRelationshipChanged: "addressBook.emitRelationshipChanged",
 		get: "addressBook.get",
 		hide: "addressBook.hide",
 		label: "addressBook.label",
@@ -508,6 +510,7 @@ const CAPXUL_OPERATIONS = {
 		createOrganization: "identity.CreateOrganization",
 		ensureAccount: "identity.EnsureAccount",
 		leaveOrganization: "identity.LeaveOrganization",
+		loadByAuthUserId: "identity.loadByAuthUserId",
 		loadCurrent: "identity.loadCurrent",
 		orgAt: "identity.OrgAt",
 		orgFailed: "identity.OrgFailed",
@@ -658,7 +661,8 @@ const CAPXUL_OPERATIONS = {
 	organizationPayments: {
 		pay: "organizationPayments.pay",
 		payBatch: "organizationPayments.payBatch",
-		prepareExecution: "organizationPayments.prepareExecution"
+		prepareExecution: "organizationPayments.prepareExecution",
+		retry: "organizationPayments.retry"
 	},
 	organizationSetup: { getProofReceipt: "organizationSetup.getProofReceipt" },
 	organizations: { detectAndAcceptPendingInvitations: "orgs.detectAndAcceptPendingInvitations" },
@@ -673,6 +677,7 @@ const CAPXUL_OPERATIONS = {
 		prepareExecution: "payments.prepareExecution",
 		prepareLifecycleExecution: "payments.prepareLifecycleExecution",
 		redirect: "payments.redirect",
+		retry: "payments.retry",
 		submitCommandExecution: "payments.submitCommandExecution",
 		submitExecution: "payments.submitExecution"
 	},
@@ -754,6 +759,7 @@ const CAPXUL_OPERATIONS = {
 	smartAccount: {
 		claim: "smartAccount.claim",
 		confirmDeployment: "smartAccount.confirmDeployment",
+		loadByAuthUserId: "smartAccount.loadByAuthUserId",
 		loadCurrent: "smartAccount.loadCurrent",
 		provision: "smartAccount.provision"
 	},
@@ -1538,6 +1544,148 @@ Schema.Struct({
 	name: Schema.Literal("movement_scan_incident"),
 	props: MovementScanIncidentProps
 });
+const ActivityReferenceProps = {
+	reference_kind: Schema.Literals(["payment", "movement"]),
+	reference_id: Schema.String
+};
+const ActivityFilterProps = {
+	filter_kind: Schema.optional(Schema.Literals([
+		"all",
+		"payment",
+		"movement"
+	])),
+	filter_direction: Schema.optional(Schema.Literals([
+		"all",
+		"in",
+		"out",
+		"self"
+	])),
+	filter_status: Schema.optional(Schema.Array(Schema.Literals([
+		"pending",
+		"settling",
+		"pending_claim",
+		"scheduled",
+		"streaming",
+		"settled",
+		"cancelled",
+		"failed"
+	])))
+};
+const ActivityActionProps = {
+	...TelemetryEnvelopeProps,
+	scope_kind: Schema.Literals(["account", "organization"]),
+	reason_code: Schema.optional(Schema.Literals(CAPXUL_ERROR_CODES))
+};
+Schema.Struct({
+	name: Schema.Literal("contact_relationship_changed"),
+	props: Schema.Struct({
+		...TelemetryEnvelopeProps,
+		change: Schema.Literals([
+			"added",
+			"renamed",
+			"hidden",
+			"restored"
+		]),
+		scope_kind: Schema.Literals(["account", "organization"]),
+		scope_id: Schema.String,
+		owner_party_id: Schema.String,
+		party_id: Schema.String,
+		hidden: Schema.Boolean,
+		occurred_at: Schema.Number,
+		operation: Schema.Literals([
+			CAPXUL_OPERATIONS.addressBook.add,
+			CAPXUL_OPERATIONS.addressBook.label,
+			CAPXUL_OPERATIONS.addressBook.hide,
+			CAPXUL_OPERATIONS.addressBook.unhide
+		])
+	})
+});
+const ContactActionProps = {
+	...TelemetryEnvelopeProps,
+	scope_kind: Schema.Literals(["account", "organization"]),
+	party_id: OptionalString,
+	reason_code: Schema.optional(Schema.Literals(CAPXUL_ERROR_CODES))
+};
+Schema.Struct({
+	name: Schema.Literal("ui_contact_action_completed"),
+	props: Schema.Union([
+		Schema.Struct({
+			...ContactActionProps,
+			action: Schema.Literal("add"),
+			outcome: Schema.Literals(["opened", "cancelled"])
+		}),
+		Schema.Struct({
+			...ContactActionProps,
+			action: Schema.Literal("refusal"),
+			outcome: Schema.Literal("displayed")
+		}),
+		Schema.Struct({
+			...ContactActionProps,
+			action: Schema.Literal("retry"),
+			outcome: Schema.Literal("requested")
+		})
+	])
+});
+Schema.Struct({
+	name: Schema.Literal("activity_annotation_saved"),
+	props: Schema.Struct({
+		...TelemetryEnvelopeProps,
+		...ActivityReferenceProps,
+		scope_kind: Schema.Literals(["account", "organization"]),
+		scope_id: Schema.String,
+		occurred_at: Schema.Number
+	})
+});
+Schema.Struct({
+	name: Schema.Literal("ui_activity_action_completed"),
+	props: Schema.Union([
+		Schema.Struct({
+			...ActivityActionProps,
+			...ActivityFilterProps,
+			action: Schema.Literal("filter"),
+			outcome: Schema.Literal("committed")
+		}),
+		Schema.Struct({
+			...ActivityActionProps,
+			action: Schema.Literal("refusal"),
+			outcome: Schema.Literal("displayed")
+		}),
+		Schema.Struct({
+			...ActivityActionProps,
+			action: Schema.Literal("retry"),
+			outcome: Schema.Literal("requested")
+		}),
+		Schema.Struct({
+			...ActivityActionProps,
+			...ActivityReferenceProps,
+			action: Schema.Literal("detail"),
+			outcome: Schema.Literals(["opened", "failed"])
+		}),
+		Schema.Struct({
+			...ActivityActionProps,
+			...ActivityReferenceProps,
+			action: Schema.Literal("receipt"),
+			outcome: Schema.Literals([
+				"document_rendered",
+				"explorer_opened",
+				"popup_blocked",
+				"failed"
+			])
+		}),
+		Schema.Struct({
+			...ActivityActionProps,
+			...ActivityFilterProps,
+			action: Schema.Literal("export"),
+			outcome: Schema.Literals([
+				"completed",
+				"partial",
+				"failed"
+			]),
+			row_count: Schema.optional(Schema.Number),
+			truncated: Schema.optional(Schema.Boolean)
+		})
+	])
+});
 function redactTelemetryEvent(event, options = {}) {
 	const props = redactTelemetryProps(event.name, event.props, options);
 	return props === void 0 ? { name: event.name } : {
@@ -3497,9 +3645,10 @@ const INVOCATION_OBSERVATION = Symbol("capxul.invocation-observation");
 const FAILURE_INVOCATION_SNAPSHOT = Symbol("capxul.failure-invocation-snapshot");
 /** @internal Attach one immutable, non-wire invocation snapshot to an SDK-owned object. */
 function attachInvocationObservation(target, source) {
-	const snapshot = Object.freeze(source.context === void 0 ? { active: source.active } : {
+	const snapshot = Object.freeze({
 		active: source.active,
-		context: Object.freeze({ ...source.context })
+		...source.actorId === void 0 ? {} : { actorId: source.actorId },
+		...source.context === void 0 ? {} : { context: Object.freeze({ ...source.context }) }
 	});
 	Object.defineProperty(target, INVOCATION_OBSERVATION, {
 		configurable: false,
@@ -3751,10 +3900,10 @@ const logIdentityTransition = (record) => (record.outcome === "applied" ? Effect
 //#region src/domain/machine/shell.ts
 const INVOCATION_PARENT_SPAN = Symbol("@capxul/sdk/identity-invocation-parent-span");
 function carryInvocationParentSpan(controls, parent) {
-	return {
+	return copyInvocationObservation(controls, {
 		...controls,
 		[INVOCATION_PARENT_SPAN]: parent
-	};
+	});
 }
 function withInvocationParentSpan(effect, controls) {
 	const parent = controls?.[INVOCATION_PARENT_SPAN];
@@ -4105,13 +4254,13 @@ async function toCapxulResult(program, layer) {
 * with `{ publicError }` rather than a bare `CapxulError`, so the wrapper is
 * unwrapped here — once — instead of at every call site.
 */
-async function runIfActive(signal, operation, effect, runPromise = Effect.runPromise) {
-	if (signal?.aborted === true) return {
+async function runIfActive(signal, operation, effect, runPromise = Effect.runPromise, observe) {
+	if (signal?.aborted === true && observe === void 0) return {
 		ok: false,
 		error: Errors.cancelled({ operation })
 	};
-	const program = effect().pipe(Effect.mapError((error) => error.publicError));
-	return runProgram(signal === void 0 ? program : Effect.raceFirst(program, Effect.callback((resume) => {
+	const program = signal?.aborted === true ? Effect.fail(Errors.cancelled({ operation })) : Effect.suspend(effect).pipe(Effect.mapError((error) => error.publicError));
+	const controlled = signal === void 0 ? program : Effect.raceFirst(program, Effect.callback((resume) => {
 		if (signal.aborted) {
 			resume(Effect.fail(Errors.cancelled({ operation })));
 			return Effect.void;
@@ -4119,7 +4268,8 @@ async function runIfActive(signal, operation, effect, runPromise = Effect.runPro
 		const onAbort = () => resume(Effect.fail(Errors.cancelled({ operation })));
 		signal.addEventListener("abort", onAbort, { once: true });
 		return Effect.sync(() => signal.removeEventListener("abort", onAbort));
-	})), runPromise);
+	}));
+	return runProgram(observe === void 0 ? controlled : observe(controlled), runPromise);
 }
 //#endregion
 //#region src/surface/_shared/effect-actor-bridge.ts
@@ -4170,22 +4320,52 @@ async function runPortEffect(effect, controls, operation = CAPXUL_OPERATIONS.run
 		orElse: () => Effect.fail({ publicError: Errors.providerTimeout("sdk", operation, timeoutMs) })
 	}))).pipe(Effect.mapError((failure) => failure.publicError)), controls, operation, runPromise);
 }
+/** Keep observation metadata while the compound operation owns cancellation. */
+function observationOnlyControls(controls) {
+	const { signal: _signal, timeoutMs: _timeoutMs, deadlineMs: _deadlineMs, ...observation } = controls ?? {};
+	return copyInvocationObservation(controls, observation);
+}
 /** Observe a public Effect that already uses the canonical CapxulError channel. */
 async function runCapxulEffect(effect, controls, operation = CAPXUL_OPERATIONS.runtime.port, runPromise = Effect.runPromise) {
 	const invocation = readInvocationObservation(controls);
-	const correlationId = safeEngineeringIdentifier(controls?.correlation_id ?? invocation?.context?.correlationId);
-	const observed = effect.pipe(Effect.tap(() => Effect.annotateCurrentSpan({ outcome: "succeeded" })), Effect.tapError((error) => {
-		const mode = error.mode ?? error.details?.failure_mode;
-		return Effect.annotateCurrentSpan({
-			outcome: portFailureOutcome(error.code),
-			failure_code: error.code,
-			...typeof mode === "string" ? { mode } : {}
-		});
-	}), Effect.tapDefect(() => Effect.annotateCurrentSpan({
-		outcome: "failed",
-		failure_code: "UNKNOWN"
-	})), Effect.withSpan(`identity.port.${operation}`), Effect.annotateSpans(correlationId === void 0 ? {} : { correlation_id: correlationId }));
-	return runIfActive(controls?.signal, operation, () => withInvocationParentSpan(observed, controls).pipe(Effect.mapError((publicError) => ({ publicError }))), runPromise);
+	const correlationId = safeEngineeringIdentifier(invocation?.context?.correlationId ?? controls?.correlation_id);
+	const context = invocation?.active === false ? void 0 : sanitizeObservationContext(invocation?.context);
+	const fields = {
+		operation,
+		...correlationId === void 0 ? {} : { correlation_id: correlationId },
+		...context?.sessionId === void 0 ? {} : {
+			session_id: context.sessionId,
+			sessionId: context.sessionId
+		},
+		...context?.journeyId === void 0 ? {} : { journey_id: context.journeyId },
+		...context?.release === void 0 ? {} : { release: context.release },
+		...context?.application === void 0 ? {} : { application: context.application },
+		...safeEngineeringIdentifier(invocation?.actorId) === void 0 ? {} : {
+			actor_id: invocation.actorId,
+			actor_kind: "authenticated",
+			posthogDistinctId: invocation.actorId
+		}
+	};
+	const result = await runIfActive(controls?.signal, operation, () => effect.pipe(Effect.mapError((publicError) => ({ publicError }))), runPromise, (program) => withInvocationParentSpan(Effect.gen(function* () {
+		const startedAt = yield* Clock.currentTimeMillis;
+		const exit = yield* Effect.exit(program.pipe(Effect.catchDefect((cause) => Effect.fail(Errors.unknown(cause)))));
+		const duration_ms = (yield* Clock.currentTimeMillis) - startedAt;
+		const error = Exit.isFailure(exit) ? Cause.squash(exit.cause) : void 0;
+		const failure = error instanceof CapxulError ? error : void 0;
+		const outcome = Exit.isSuccess(exit) ? "succeeded" : failure?.code === "CANCELLED" ? "cancelled" : failure !== void 0 && EXPECTED_OPERATION_OUTCOMES.has(failure.code) ? "refused" : "failed";
+		const completion = {
+			...fields,
+			duration_ms,
+			outcome,
+			...failure === void 0 ? {} : { failure_code: failure.code },
+			...typeof failure?.mode === "string" ? { mode: failure.mode } : {},
+			...failure?.mode === void 0 && typeof failure?.details?.failure_mode === "string" ? { mode: failure.details.failure_mode } : {}
+		};
+		yield* Effect.annotateCurrentSpan(completion).pipe(Effect.catchCause(() => Effect.void));
+		yield* (outcome === "failed" ? Effect.logError("capxul_sdk_operation") : Effect.logInfo("capxul_sdk_operation")).pipe(Effect.annotateLogs(completion), Effect.catchCause(() => Effect.void));
+		return yield* Exit.isSuccess(exit) ? Effect.succeed(exit.value) : Effect.failCause(exit.cause);
+	}).pipe(Effect.withSpan(operation)), controls));
+	return !result.ok && invocation !== void 0 ? markFailureInvocationSnapshot(result, invocation) : result;
 }
 /** Map machine-internal failure state onto the public SDK error vocabulary. */
 function publicIdentityFailure(failure) {
@@ -4399,76 +4579,110 @@ function makeActorRelationshipMethods(deps) {
 	const fns = actorScopeContract;
 	return {
 		addressBook: {
-			list: (input, options) => mapOk$1(CAPXUL_OPERATIONS.addressBook.list, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.addressBook.list, () => convexCall.query(fns.addressBookList, {
-				actor,
-				...input?.includeHidden === void 0 ? {} : { includeHidden: input.includeHidden }
-			})), (entries) => entries.map(mapAddressBookEntry)),
-			get: (entryId, options) => mapOk$1(CAPXUL_OPERATIONS.addressBook.get, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.addressBook.get, () => convexCall.query(fns.addressBookGet, {
-				actor,
-				partyId: entryId
-			})), (entry) => entry === null ? null : mapAddressBookEntry(entry)),
-			add: async (input, options) => {
+			list: (input, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.addressBook.list, Effect.suspend(() => convexCall.query(fns.addressBookList, copyInvocationObservation(controls, {
+					actor,
+					...input?.includeHidden === void 0 ? {} : { includeHidden: input.includeHidden }
+				}))), (entries) => entries.map(mapAddressBookEntry)), controls, CAPXUL_OPERATIONS.addressBook.list, deps.runPromise);
+			},
+			get: (entryId, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.addressBook.get, Effect.suspend(() => convexCall.query(fns.addressBookGet, copyInvocationObservation(controls, {
+					actor,
+					partyId: entryId
+				}))), (entry) => entry === null ? null : mapAddressBookEntry(entry)), controls, CAPXUL_OPERATIONS.addressBook.get, deps.runPromise);
+			},
+			add: (input, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
 				const ref = normalizeRefForBackend$1(input.ref, "ref");
-				if (!ref.ok) return ref;
-				return mapOk$1(CAPXUL_OPERATIONS.addressBook.add, await awaitableConvex(options?.signal, CAPXUL_OPERATIONS.addressBook.add, () => convexCall.mutation(fns.addressBookAdd, {
+				if (!ref.ok) return runCapxulEffect(Effect.fail(ref.error), controls, CAPXUL_OPERATIONS.addressBook.add, deps.runPromise);
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.addressBook.add, Effect.suspend(() => convexCall.mutation(fns.addressBookAdd, copyInvocationObservation(controls, {
 					actor,
 					ref: ref.value,
 					...input.label === void 0 ? {} : { label: input.label }
-				})), mapAddressBookEntry);
+				}))), mapAddressBookEntry), controls, CAPXUL_OPERATIONS.addressBook.add, deps.runPromise);
+			},
+			hide: (entryId, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.addressBook.hide, Effect.suspend(() => convexCall.mutation(fns.addressBookHide, copyInvocationObservation(controls, {
+					actor,
+					partyId: entryId
+				}))), mapAddressBookEntry), controls, CAPXUL_OPERATIONS.addressBook.hide, deps.runPromise);
 			},
-			hide: (entryId, options) => mapOk$1(CAPXUL_OPERATIONS.addressBook.hide, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.addressBook.hide, () => convexCall.mutation(fns.addressBookHide, {
-				actor,
-				partyId: entryId
-			})), mapAddressBookEntry),
-			unhide: (entryId, options) => mapOk$1(CAPXUL_OPERATIONS.addressBook.unhide, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.addressBook.unhide, () => convexCall.mutation(fns.addressBookUnhide, {
-				actor,
-				partyId: entryId
-			})), mapAddressBookEntry),
-			label: (input, options) => mapOk$1(CAPXUL_OPERATIONS.addressBook.label, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.addressBook.label, () => convexCall.mutation(fns.addressBookLabel, {
-				actor,
-				partyId: input.entryId,
-				label: input.label
-			})), mapAddressBookEntry)
+			unhide: (entryId, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.addressBook.unhide, Effect.suspend(() => convexCall.mutation(fns.addressBookUnhide, copyInvocationObservation(controls, {
+					actor,
+					partyId: entryId
+				}))), mapAddressBookEntry), controls, CAPXUL_OPERATIONS.addressBook.unhide, deps.runPromise);
+			},
+			label: (input, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.addressBook.label, Effect.suspend(() => convexCall.mutation(fns.addressBookLabel, copyInvocationObservation(controls, {
+					actor,
+					partyId: input.entryId,
+					label: input.label
+				}))), mapAddressBookEntry), controls, CAPXUL_OPERATIONS.addressBook.label, deps.runPromise);
+			}
 		},
 		requests: {
-			issue: async (input, options) => {
+			issue: (input, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
 				const payer = normalizeRefForBackend$1(input.payer, "payer");
-				if (!payer.ok) return payer;
-				return mapOk$1(CAPXUL_OPERATIONS.requests.issue, await awaitableConvex(options?.signal, CAPXUL_OPERATIONS.requests.issue, () => convexCall.mutation(fns.requestsIssue, {
+				if (!payer.ok) return runCapxulEffect(Effect.fail(payer.error), controls, CAPXUL_OPERATIONS.requests.issue, deps.runPromise);
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.requests.issue, Effect.suspend(() => convexCall.mutation(fns.requestsIssue, copyInvocationObservation(controls, {
 					actor,
 					payer: payer.value,
 					amount: input.amount,
 					reference: input.reference,
 					...input.memo === void 0 ? {} : { memo: input.memo },
 					...input.expiresAt === void 0 ? {} : { expiresAt: input.expiresAt }
-				})), (request) => mapActorRequest(request, input.payer));
+				}))), (request) => mapActorRequest(request, input.payer)), controls, CAPXUL_OPERATIONS.requests.issue, deps.runPromise);
+			},
+			list: (options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.requests.list, Effect.suspend(() => convexCall.query(fns.requestsList, copyInvocationObservation(controls, { actor }))), (requests) => requests.map((request) => mapActorRequest(request))), controls, CAPXUL_OPERATIONS.requests.list, deps.runPromise);
 			},
-			list: (options) => mapOk$1(CAPXUL_OPERATIONS.requests.list, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.requests.list, () => convexCall.query(fns.requestsList, { actor })), (requests) => requests.map((request) => mapActorRequest(request))),
-			get: (requestId, options) => mapOk$1(CAPXUL_OPERATIONS.requests.get, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.requests.get, () => convexCall.query(fns.requestsGet, {
-				actor,
-				paymentRequestId: requestId
-			})), (request) => request === null ? null : mapActorRequest(request)),
-			cancel: (requestId, options) => mapOk$1(CAPXUL_OPERATIONS.requests.cancel, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.requests.cancel, () => convexCall.mutation(fns.requestsCancel, {
-				actor,
-				paymentRequestId: requestId
-			})), (request) => mapActorRequest(request))
+			get: (requestId, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.requests.get, Effect.suspend(() => convexCall.query(fns.requestsGet, copyInvocationObservation(controls, {
+					actor,
+					paymentRequestId: requestId
+				}))), (request) => request === null ? null : mapActorRequest(request)), controls, CAPXUL_OPERATIONS.requests.get, deps.runPromise);
+			},
+			cancel: (requestId, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.requests.cancel, Effect.suspend(() => convexCall.mutation(fns.requestsCancel, copyInvocationObservation(controls, {
+					actor,
+					paymentRequestId: requestId
+				}))), (request) => mapActorRequest(request)), controls, CAPXUL_OPERATIONS.requests.cancel, deps.runPromise);
+			}
 		},
 		inbox: {
-			list: (options) => mapOk$1(CAPXUL_OPERATIONS.inbox.list, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.inbox.list, () => convexCall.query(fns.inboxList, { actor })), (items) => items.map(mapInboxItem)),
-			approve: async (input, options) => {
-				const result = await awaitableConvex(options?.signal, CAPXUL_OPERATIONS.inbox.approve, () => convexCall.mutation(fns.inboxApprove, {
+			list: (options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.inbox.list, Effect.suspend(() => convexCall.query(fns.inboxList, copyInvocationObservation(controls, { actor }))), (items) => items.map(mapInboxItem)), controls, CAPXUL_OPERATIONS.inbox.list, deps.runPromise);
+			},
+			approve: (input, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => convexCall.mutation(fns.inboxApprove, copyInvocationObservation(controls, {
 					actor,
 					paymentRequestId: input.requestId,
 					...input.timing === void 0 ? {} : { timing: input.timing },
 					...input.permissionId === void 0 ? {} : { permissionId: input.permissionId }
-				}));
-				if (!result.ok) return result;
-				return mapApprovedInboxPayment(result.value, input);
+				}))).pipe(Effect.flatMap((prepared) => {
+					const result = mapApprovedInboxPayment(prepared, input);
+					return result.ok ? Effect.succeed(result.value) : Effect.fail({ publicError: result.error });
+				})), controls, CAPXUL_OPERATIONS.inbox.approve, deps.runPromise);
 			},
-			decline: (requestId, options) => mapOk$1(CAPXUL_OPERATIONS.inbox.decline, awaitableConvex(options?.signal, CAPXUL_OPERATIONS.inbox.decline, () => convexCall.mutation(fns.inboxDecline, {
-				actor,
-				paymentRequestId: requestId
-			})), mapInboxItem)
+			decline: (requestId, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(mapReply(CAPXUL_OPERATIONS.inbox.decline, Effect.suspend(() => convexCall.mutation(fns.inboxDecline, copyInvocationObservation(controls, {
+					actor,
+					paymentRequestId: requestId
+				}))), mapInboxItem), controls, CAPXUL_OPERATIONS.inbox.decline, deps.runPromise);
+			}
 		},
 		profile: {
 			get: (options) => {
@@ -4545,22 +4759,12 @@ function missingConvexCall(operation) {
 * promise and the caller's `if (!result.ok)` never runs (ADR-0023: errors are
 * values, and a code crosses the seam).
 */
-async function mapOk$1(operation, resultOrPromise, f) {
-	const result = await resultOrPromise;
-	if (!result.ok) return result;
-	try {
-		return {
-			ok: true,
-			value: f(result.value)
-		};
-	} catch (cause) {
-		return {
-			ok: false,
-			error: cause instanceof CapxulError ? cause : Errors.providerError("convex", operation, cause)
-		};
-	}
+function mapReply(operation, program, project) {
+	return program.pipe(Effect.flatMap((value) => Effect.try({
+		try: () => project(value),
+		catch: (cause) => ({ publicError: cause instanceof CapxulError ? cause : Errors.providerError("convex", operation, cause) })
+	})));
 }
-const awaitableConvex = runIfActive;
 const ADDRESS_BOOK_RELATIONSHIPS = [
 	"paid",
 	"paidBy",
@@ -4928,6 +5132,8 @@ function makeAccountMethods(deps) {
 	return {
 		methods: {
 			...makeActorRelationshipMethods({
+				...deps.runPromise === void 0 ? {} : { runPromise: deps.runPromise },
+				...deps.invocationControls === void 0 ? {} : { invocationControls: deps.invocationControls },
 				actor: { kind: "account" },
 				...deps.convexCall === void 0 ? {} : { convexCall: deps.convexCall },
 				...deps.profileMethods === void 0 ? {} : { accountProfileMethods: deps.profileMethods }
@@ -4981,7 +5187,7 @@ const moneyExecutionContract = {
 };
 //#endregion
 //#region package.json
-var version = "4.0.0";
+var version = "4.1.0";
 //#endregion
 //#region src/telemetry/exception-projection.ts
 /** Fixed fallback for failures that have no safe message. */
@@ -5037,7 +5243,16 @@ function postHogFailureObservation(policy, fixedSnapshot) {
 		const directSnapshot = callStartSnapshot === void 0 ? policy.snapshot() : void 0;
 		if (!(callStartSnapshot?.active ?? directSnapshot?.active) || policy.client === null || policy.client === void 0) return;
 		const safeFailure = sanitizeFailureObservation(failure);
-		return [safeFailure, postHogProperties(safeFailure, callStartSnapshot?.context ?? directSnapshot?.context)];
+		const directContext = callStartSnapshot?.context ?? directSnapshot?.context;
+		const actorId = callStartSnapshot?.actorId;
+		return [safeFailure, {
+			...postHogProperties(safeFailure, directContext),
+			...actorId !== void 0 && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(actorId) ? {
+				actor_id: actorId,
+				actor_kind: "authenticated",
+				distinct_id: actorId
+			} : {}
+		}];
 	};
 	const captureOperationFailure = (failure) => {
 		const prepared = prepare(failure);
@@ -5142,7 +5357,8 @@ function observeSdkClient(client, adapter, snapshot) {
 	};
 	const processOutput = (output, path, invocation) => {
 		if (isFailedResult(output)) {
-			report(adapter, "operation", path.join("."), output.error, invocation);
+			const captured = readFailureInvocationSnapshot(output);
+			report(adapter, "operation", path.join("."), output.error, captured ?? invocation, void 0, captured !== void 0);
 			return output;
 		}
 		if (isCapxulResult(output)) return output;
@@ -5174,7 +5390,7 @@ function reportedByMachine(cause) {
 	}
 	return false;
 }
-function report(adapter, kind, operation, cause, invocation, origin) {
+function report(adapter, kind, operation, cause, invocation, origin, authoritativeSnapshot = false) {
 	if (origin === "machine") {
 		let link = cause;
 		for (let depth = 0; depth < 8 && typeof link === "object" && link !== null; depth++) {
@@ -5186,7 +5402,7 @@ function report(adapter, kind, operation, cause, invocation, origin) {
 	const kindName = normalizeErrorKind(errorKind(cause));
 	const context = sanitizeObservationContext({
 		...invocation.context,
-		...isCapxulError(cause) && cause.correlationId !== void 0 ? { correlationId: cause.correlationId } : {}
+		...!authoritativeSnapshot && isCapxulError(cause) && cause.correlationId !== void 0 ? { correlationId: cause.correlationId } : {}
 	});
 	const detail = failureDetail(cause);
 	const evidence = failureEvidence(cause);
@@ -5200,6 +5416,7 @@ function report(adapter, kind, operation, cause, invocation, origin) {
 		...evidence
 	}, {
 		active: invocation.active,
+		...invocation.actorId === void 0 ? {} : { actorId: invocation.actorId },
 		...context === void 0 ? {} : { context }
 	});
 	try {
@@ -5728,17 +5945,17 @@ async function fingerprintPaymentIntent(intent) {
 function matchesIntent(expected) {
 	return async (request) => await fingerprintPaymentIntent(request) === await fingerprintPaymentIntent(expected);
 }
-async function abandonPrepared$1(deps, executionId, closePayment, reason, result, onPreparedClosed) {
+async function abandonPrepared$1(deps, executionId, closePayment, reason, result, onPreparedClosed, controls) {
 	if (!closePayment) return result;
-	const abandoned = await runIfActive(void 0, CAPXUL_OPERATIONS.moneyExecution.abandonPaymentExecution, () => deps.convexCall.action(deps.functions.abandonPaymentExecution, { input: {
+	const abandoned = await runIfActive(void 0, CAPXUL_OPERATIONS.moneyExecution.abandonPaymentExecution, () => withInvocationParentSpan(Effect.suspend(() => deps.convexCall.action(deps.functions.abandonPaymentExecution, copyInvocationObservation(controls, { input: {
 		executionId,
 		reason
-	} }));
+	} }))), controls), deps.runPromise);
 	if (!abandoned.ok) return abandoned;
 	if (abandoned.value) onPreparedClosed?.();
 	return result;
 }
-async function executePrepared(deps, prepare, isExpectedRequest, closePaymentOnExit, onPreparedClosed, signal) {
+async function executePrepared(deps, prepare, isExpectedRequest, closePaymentOnExit, onPreparedClosed, signal, controls) {
 	if (isAborted$2(signal)) return {
 		ok: false,
 		error: Errors.cancelled({ operation: "payments" })
@@ -5762,16 +5979,16 @@ async function executePrepared(deps, prepare, isExpectedRequest, closePaymentOnE
 	if (!await isExpectedRequest(prepared.value.request)) return abandonPrepared$1(deps, prepared.value.executionId, closePaymentOnExit, "prepared_mismatch", {
 		ok: false,
 		error: Errors.invalidInput("payment", "prepared command mismatch")
-	}, onPreparedClosed);
+	}, onPreparedClosed, controls);
 	const expectedSafe = deriveCapxulSafeAddress({ email: session.email });
 	if (prepared.value.chainId !== deps.chainId || prepared.value.signerAddress.toLowerCase() !== signerAddress.toLowerCase() || prepared.value.userOpSenderSafe.toLowerCase() !== expectedSafe.toLowerCase()) return abandonPrepared$1(deps, prepared.value.executionId, closePaymentOnExit, "prepared_mismatch", {
 		ok: false,
 		error: Errors.invalidInput("payment", "prepared authority mismatch")
-	}, onPreparedClosed);
+	}, onPreparedClosed, controls);
 	if (isAborted$2(signal)) return abandonPrepared$1(deps, prepared.value.executionId, closePaymentOnExit, "cancelled", {
 		ok: false,
 		error: Errors.cancelled({ operation: "payments" })
-	}, onPreparedClosed);
+	}, onPreparedClosed, controls);
 	if (prepared.value.emitPaymentInitiated && "items" in prepared.value.request) for (const [index, item] of prepared.value.request.items.entries()) {
 		const paymentId = prepared.value.paymentIds[index];
 		const recipient = prepared.value.recipientObservations[index];
@@ -5792,28 +6009,28 @@ async function executePrepared(deps, prepare, isExpectedRequest, closePaymentOnE
 		return abandonPrepared$1(deps, prepared.value.executionId, closePaymentOnExit, "signer_rejected", {
 			ok: false,
 			error: signerFailure(deps.signer.source, "signUserOpHash", cause)
-		}, onPreparedClosed);
+		}, onPreparedClosed, controls);
 	}
 	if (isAborted$2(signal)) return abandonPrepared$1(deps, prepared.value.executionId, closePaymentOnExit, "cancelled", {
 		ok: false,
 		error: Errors.cancelled({ operation: "payments" })
-	}, onPreparedClosed);
-	return runIfActive(void 0, CAPXUL_OPERATIONS.payments.submitCommandExecution, () => deps.convexCall.action(deps.functions.submitPaymentCommandExecution, { input: {
+	}, onPreparedClosed, controls);
+	return runIfActive(void 0, CAPXUL_OPERATIONS.payments.submitCommandExecution, () => withInvocationParentSpan(Effect.suspend(() => deps.convexCall.action(deps.functions.submitPaymentCommandExecution, copyInvocationObservation(controls, { input: {
 		executionId: prepared.value.executionId,
 		signature
-	} }));
+	} }))), controls), deps.runPromise);
 }
-function executePaymentLifecycle(deps, intent, signal) {
-	return executePrepared(deps, (signerAddress) => runIfActive(signal, CAPXUL_OPERATIONS.payments.prepareLifecycleExecution, () => deps.convexCall.action(deps.functions.preparePaymentLifecycleExecution, { input: {
+function executePaymentLifecycle(deps, intent, signal, controls) {
+	return executePrepared(deps, (signerAddress) => runIfActive(signal, CAPXUL_OPERATIONS.payments.prepareLifecycleExecution, () => withInvocationParentSpan(Effect.suspend(() => deps.convexCall.action(deps.functions.preparePaymentLifecycleExecution, copyInvocationObservation(controls, { input: {
 		signerAddress,
 		intent
-	} })), matchesIntent(intent), false, void 0, signal);
+	} }))), controls), deps.runPromise), matchesIntent(intent), false, void 0, signal, controls);
 }
-function executeOrganizationPayment(deps, input, signal, onPreparedClosed) {
-	return executePrepared(deps, (signerAddress) => runIfActive(signal, CAPXUL_OPERATIONS.organizationPayments.prepareExecution, () => deps.convexCall.action(deps.functions.prepareOrganizationPaymentExecution, { input: {
+function executeOrganizationPayment(deps, input, signal, onPreparedClosed, controls) {
+	return executePrepared(deps, (signerAddress) => runIfActive(signal, CAPXUL_OPERATIONS.organizationPayments.prepareExecution, () => withInvocationParentSpan(Effect.suspend(() => deps.convexCall.action(deps.functions.prepareOrganizationPaymentExecution, copyInvocationObservation(controls, { input: {
 		...input,
 		signerAddress
-	} })), matchesIntent(input), true, onPreparedClosed, signal);
+	} }))), controls), deps.runPromise), matchesIntent(input), true, onPreparedClosed, signal, controls);
 }
 //#endregion
 //#region src/surface/payment-execution.ts
@@ -6252,51 +6469,52 @@ function makeFinancialOpsMethods(deps) {
 			chainId: deps.chainId,
 			convexCall: deps.convexCall,
 			functions: executionFns,
-			signer: deps.signer
-		}
-	};
-	const runLifecycle = async (intent, signal) => {
-		const execution = lifecycleDependencies();
-		if (!execution.ok) return execution;
-		try {
-			const submitted = await executePaymentLifecycle(execution.value, intent, signal);
-			if (!submitted.ok) return submitted;
-			const payments = submitted.value.payments;
-			const payment = payments[0];
-			if (payment === void 0 || payments.length !== 1) return {
-				ok: false,
-				error: Errors.unknown()
-			};
-			return {
-				ok: true,
-				value: normalizePaymentTiming(payment)
-			};
-		} catch (cause) {
-			return {
-				ok: false,
-				error: cause instanceof CapxulError ? cause : Errors.unknown(cause)
-			};
-		}
-	};
-	const retryPayment = async (paymentId, signal) => {
-		const execution = lifecycleDependencies();
-		if (!execution.ok) return execution;
-		try {
-			const submitted = await executePaymentLifecycle(execution.value, {
-				kind: "retry",
-				paymentId
-			}, signal);
-			return submitted.ok ? {
-				ok: true,
-				value: submitted.value.payments.map((payment) => normalizePaymentTiming(payment))
-			} : submitted;
-		} catch (cause) {
-			return {
-				ok: false,
-				error: cause instanceof CapxulError ? cause : Errors.unknown(cause)
-			};
+			signer: deps.signer,
+			...deps.runPromise === void 0 ? {} : { runPromise: deps.runPromise }
 		}
 	};
+	const runLifecycle = (intent, controls, operation) => runCapxulEffect(Effect.gen(function* () {
+		const captured = carryInvocationParentSpan(controls, yield* Effect.currentSpan.pipe(Effect.orDie));
+		const result = yield* Effect.tryPromise({
+			try: async () => {
+				const execution = lifecycleDependencies();
+				if (!execution.ok) return execution;
+				const submitted = await executePaymentLifecycle(execution.value, intent, controls?.signal, captured);
+				if (!submitted.ok) return submitted;
+				const payments = submitted.value.payments;
+				const payment = payments[0];
+				if (payment === void 0 || payments.length !== 1) return {
+					ok: false,
+					error: Errors.unknown()
+				};
+				return {
+					ok: true,
+					value: normalizePaymentTiming(payment)
+				};
+			},
+			catch: (cause) => cause instanceof CapxulError ? cause : Errors.unknown(cause)
+		});
+		return yield* result.ok ? Effect.succeed(result.value) : Effect.fail(result.error);
+	}), observationOnlyControls(controls), operation, deps.runPromise);
+	const retryPayment = (paymentId, controls) => runCapxulEffect(Effect.gen(function* () {
+		const captured = carryInvocationParentSpan(controls, yield* Effect.currentSpan.pipe(Effect.orDie));
+		const result = yield* Effect.tryPromise({
+			try: async () => {
+				const execution = lifecycleDependencies();
+				if (!execution.ok) return execution;
+				const submitted = await executePaymentLifecycle(execution.value, {
+					kind: "retry",
+					paymentId
+				}, controls?.signal, captured);
+				return submitted.ok ? {
+					ok: true,
+					value: submitted.value.payments.map((payment) => normalizePaymentTiming(payment))
+				} : submitted;
+			},
+			catch: (cause) => cause instanceof CapxulError ? cause : Errors.unknown(cause)
+		});
+		return yield* result.ok ? Effect.succeed(result.value) : Effect.fail(result.error);
+	}), observationOnlyControls(controls), CAPXUL_OPERATIONS.payments.retry, deps.runPromise);
 	return {
 		me: {
 			get: (options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.me.get, () => deps.convexCall.query(fns.me, {})),
@@ -6348,58 +6566,64 @@ function makeFinancialOpsMethods(deps) {
 		},
 		payments: {
 			pay,
-			retry: (paymentId, options) => retryPayment(paymentId, options?.signal),
+			retry: (paymentId, options) => retryPayment(paymentId, deps.invocationControls?.(options) ?? options),
 			createCommitment: (input, options) => pay(input, options),
 			claim: (paymentId, options) => runLifecycle({
 				kind: "claim",
 				paymentId
-			}, options?.signal),
+			}, deps.invocationControls?.(options) ?? options, CAPXUL_OPERATIONS.payments.claim),
 			list: async (options) => mapOk(await runIfActive(options?.signal, CAPXUL_OPERATIONS.payments.list, () => deps.convexCall.query(fns.listPayments, {})), (payments) => payments.map(normalizePaymentTiming)),
 			get: async (paymentId, options) => mapOk(await runIfActive(options?.signal, CAPXUL_OPERATIONS.payments.get, () => deps.convexCall.query(fns.getPayment, { paymentId })), (payment) => payment === null ? null : normalizePaymentTiming(payment)),
 			cancel: (paymentId, options) => runLifecycle({
 				kind: "cancel",
 				paymentId
-			}, options?.signal),
+			}, deps.invocationControls?.(options) ?? options, CAPXUL_OPERATIONS.payments.cancel),
 			redirect: async (input, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
 				const recipient = normalizeTargetForBackend(input.to, "to");
-				if (!recipient.ok) return recipient;
+				if (!recipient.ok) return runCapxulEffect(Effect.fail(recipient.error), observationOnlyControls(controls), CAPXUL_OPERATIONS.payments.redirect, deps.runPromise);
 				return runLifecycle({
 					kind: "redirect",
 					paymentId: input.paymentId,
 					recipient: recipient.value
-				}, options?.signal);
+				}, controls, CAPXUL_OPERATIONS.payments.redirect);
 			}
 		},
 		activity: {
-			list: (params, options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.activity.list, () => deps.convexCall.query(fns.activityList, { input: {
-				...activityActorField(params?.actor),
-				...params?.cursor === void 0 ? {} : { cursor: params.cursor },
-				...params?.limit === void 0 ? {} : { limit: params.limit },
-				...params?.range === void 0 ? {} : { range: params.range },
-				...params?.filter === void 0 ? {} : { filter: params.filter }
-			} })),
-			summary: (params, options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.activity.summary, () => deps.convexCall.query(fns.activitySummary, { input: {
-				...activityActorField(params?.actor),
-				...params?.window === void 0 ? {} : { window: params.window }
-			} })),
+			list: (params, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => deps.convexCall.query(fns.activityList, copyInvocationObservation(controls, { input: {
+					...activityActorField(params?.actor),
+					...params?.cursor === void 0 ? {} : { cursor: params.cursor },
+					...params?.limit === void 0 ? {} : { limit: params.limit },
+					...params?.range === void 0 ? {} : { range: params.range },
+					...params?.filter === void 0 ? {} : { filter: params.filter }
+				} }))), controls, CAPXUL_OPERATIONS.activity.list, deps.runPromise);
+			},
+			summary: (params, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => deps.convexCall.query(fns.activitySummary, copyInvocationObservation(controls, { input: {
+					...activityActorField(params?.actor),
+					...params?.window === void 0 ? {} : { window: params.window }
+				} }))), controls, CAPXUL_OPERATIONS.activity.summary, deps.runPromise);
+			},
 			get: (reference, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
 				const actor = actorReferenceToBackend(options?.actor);
-				return runIfActive(options?.signal, CAPXUL_OPERATIONS.activity.get, () => deps.convexCall.query(fns.activityGet, {
+				return runPortEffect(Effect.suspend(() => deps.convexCall.query(fns.activityGet, copyInvocationObservation(controls, {
 					input: {
 						kind: reference.kind,
 						id: reference.id,
 						...reference.kind === "payment" ? activityActorField(reference.actor) : {}
 					},
 					...actor === void 0 ? {} : { actor }
-				}).pipe(Effect.map(normalizeActivityDetail)));
+				}))).pipe(Effect.map(normalizeActivityDetail)), controls, CAPXUL_OPERATIONS.activity.get, deps.runPromise);
 			},
 			annotate: (input, options) => {
-				if (input.actor !== void 0 && input.reference.kind === "payment" && input.reference.actor !== void 0 && !sameActor(input.actor, input.reference.actor)) return Promise.resolve({
-					ok: false,
-					error: Errors.invalidInput("reference.actor", "must match the annotation actor")
-				});
+				const controls = deps.invocationControls?.(options) ?? options;
+				if (input.actor !== void 0 && input.reference.kind === "payment" && input.reference.actor !== void 0 && !sameActor(input.actor, input.reference.actor)) return runCapxulEffect(Effect.fail(Errors.invalidInput("reference.actor", "must match the annotation actor")), controls, CAPXUL_OPERATIONS.activity.annotate, deps.runPromise);
 				const referenceActor = input.reference.kind === "payment" ? activityActorField(input.reference.actor).actor : void 0;
-				return runIfActive(options?.signal, CAPXUL_OPERATIONS.activity.annotate, () => deps.convexCall.mutation(fns.activityAnnotate, { input: {
+				return runPortEffect(Effect.suspend(() => deps.convexCall.mutation(fns.activityAnnotate, copyInvocationObservation(controls, { input: {
 					...activityActorField(input.actor),
 					reference: input.reference.kind === "payment" && referenceActor !== void 0 ? {
 						kind: "payment",
@@ -6412,7 +6636,7 @@ function makeFinancialOpsMethods(deps) {
 					...input.counterpartyLabel === void 0 ? {} : { counterpartyLabel: input.counterpartyLabel },
 					...input.accountingCategory === void 0 ? {} : { accountingCategory: input.accountingCategory },
 					...input.memo === void 0 ? {} : { memo: input.memo }
-				} }));
+				} }))), controls, CAPXUL_OPERATIONS.activity.annotate, deps.runPromise);
 			}
 		},
 		offramp: {
@@ -6438,8 +6662,14 @@ function makeFinancialOpsMethods(deps) {
 			}
 		},
 		paymentDocuments: {
-			verify: (documentHash, options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.paymentDocuments.verify, () => deps.convexCall.query(fns.verifyPaymentDocument, { documentHash })),
-			render: (documentHash, options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.paymentDocuments.render, () => deps.convexCall.query(fns.renderStoredDocument, { documentHash }))
+			verify: (documentHash, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => deps.convexCall.query(fns.verifyPaymentDocument, copyInvocationObservation(controls, { documentHash }))), controls, CAPXUL_OPERATIONS.paymentDocuments.verify, deps.runPromise);
+			},
+			render: (documentHash, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => deps.convexCall.query(fns.renderStoredDocument, copyInvocationObservation(controls, { documentHash }))), controls, CAPXUL_OPERATIONS.paymentDocuments.render, deps.runPromise);
+			}
 		}
 	};
 }
@@ -8336,13 +8566,14 @@ function executionDependencies$1(input) {
 		convexCall: input.convexCall,
 		functions: moneyExecutionContract,
 		signer: input.signer,
+		...input.runPromise === void 0 ? {} : { runPromise: input.runPromise },
 		...input.telemetry === void 0 ? {} : { telemetry: input.telemetry }
 	};
 }
 function makeOrganizationPaymentsMethods(deps, orgId) {
 	const requestKeyScope = deps.requestKeyScope ?? `client-${crypto.randomUUID()}`;
 	const inFlightOrganizationPayments = /* @__PURE__ */ new Map();
-	const execute = async (input, signal, operation = "organization-pay-batch") => {
+	const execute = async (input, signal, operation = "organization-pay-batch", controls) => {
 		if (signal?.aborted === true) return {
 			ok: false,
 			error: Errors.cancelled({ operation })
@@ -8375,7 +8606,7 @@ function makeOrganizationPaymentsMethods(deps, orgId) {
 				requestKey: requestKey.key,
 				items: input.items,
 				...input.lineage === void 0 ? {} : { lineage: input.lineage }
-			}, controller.signal, () => requestState.resolved = true);
+			}, controller.signal, () => requestState.resolved = true, controls);
 			flight = {
 				controller,
 				promise: submission,
@@ -8424,41 +8655,73 @@ function makeOrganizationPaymentsMethods(deps, orgId) {
 		return normalized;
 	};
 	return {
-		retry: async (paymentId, options) => {
-			const execution = executionDependencies$1(deps);
-			if (execution === null) return {
-				ok: false,
-				error: Errors.notImplemented("organizationPayments", "executionComposition")
-			};
-			const result = await executePaymentLifecycle(execution, {
-				kind: "retry",
-				paymentId
-			}, options?.signal);
-			if (!result.ok) return result;
-			return {
-				ok: true,
-				value: result.value.payments.map((payment) => normalizePaymentTiming(payment))
-			};
+		retry: (paymentId, options) => {
+			const controls = deps.invocationControls?.(options) ?? options;
+			return runCapxulEffect(Effect.gen(function* () {
+				const parent = yield* Effect.currentSpan.pipe(Effect.orDie);
+				const captured = carryInvocationParentSpan(controls, parent);
+				const completed = yield* Effect.tryPromise({
+					try: async () => {
+						const execution = executionDependencies$1(deps);
+						if (execution === null) return {
+							ok: false,
+							error: Errors.notImplemented("organizationPayments", "executionComposition")
+						};
+						const result = await executePaymentLifecycle(execution, {
+							kind: "retry",
+							paymentId
+						}, controls?.signal, captured);
+						if (!result.ok) return result;
+						return {
+							ok: true,
+							value: result.value.payments.map((payment) => normalizePaymentTiming(payment))
+						};
+					},
+					catch: (cause) => cause instanceof CapxulError ? cause : Errors.unknown(cause)
+				});
+				return yield* completed.ok ? Effect.succeed(completed.value) : Effect.fail(completed.error);
+			}), observationOnlyControls(controls), CAPXUL_OPERATIONS.organizationPayments.retry, deps.runPromise);
 		},
-		pay: async (input, options) => {
-			const { permissionId, requestKey: providedRequestKey, lineage, ...item } = input;
-			const result = await execute({
-				permissionId,
-				...providedRequestKey === void 0 ? {} : { requestKey: providedRequestKey },
-				items: [item],
-				...lineage === void 0 ? {} : { lineage }
-			}, options?.signal, "organization-pay");
-			if (!result.ok) return result;
-			const payment = result.value[0];
-			return payment === void 0 ? {
-				ok: false,
-				error: Errors.unknown()
-			} : {
-				ok: true,
-				value: payment
-			};
+		pay: (input, options) => {
+			const controls = deps.invocationControls?.(options) ?? options;
+			return runCapxulEffect(Effect.gen(function* () {
+				const parent = yield* Effect.currentSpan.pipe(Effect.orDie);
+				const captured = carryInvocationParentSpan(controls, parent);
+				const completed = yield* Effect.tryPromise({
+					try: async () => {
+						const { permissionId, requestKey: providedRequestKey, lineage, ...item } = input;
+						const result = await execute({
+							permissionId,
+							...providedRequestKey === void 0 ? {} : { requestKey: providedRequestKey },
+							items: [item],
+							...lineage === void 0 ? {} : { lineage }
+						}, controls?.signal, "organization-pay", captured);
+						if (!result.ok) return result;
+						const payment = result.value[0];
+						return payment === void 0 ? {
+							ok: false,
+							error: Errors.unknown()
+						} : {
+							ok: true,
+							value: payment
+						};
+					},
+					catch: (cause) => cause instanceof CapxulError ? cause : Errors.unknown(cause)
+				});
+				return yield* completed.ok ? Effect.succeed(completed.value) : Effect.fail(completed.error);
+			}), observationOnlyControls(controls), CAPXUL_OPERATIONS.organizationPayments.pay, deps.runPromise);
 		},
-		payBatch: (input, options) => execute(input, options?.signal)
+		payBatch: (input, options) => {
+			const controls = deps.invocationControls?.(options) ?? options;
+			return runCapxulEffect(Effect.gen(function* () {
+				const parent = yield* Effect.currentSpan.pipe(Effect.orDie);
+				const completed = yield* Effect.tryPromise({
+					try: () => execute(input, controls?.signal, void 0, carryInvocationParentSpan(controls, parent)),
+					catch: (cause) => cause instanceof CapxulError ? cause : Errors.unknown(cause)
+				});
+				return yield* completed.ok ? Effect.succeed(completed.value) : Effect.fail(completed.error);
+			}), observationOnlyControls(controls), CAPXUL_OPERATIONS.organizationPayments.payBatch, deps.runPromise);
+		}
 	};
 }
 //#endregion
@@ -8555,12 +8818,14 @@ function executionDependencies(deps) {
 		chainId: deps.chainId,
 		convexCall: deps.convexCall,
 		functions: moneyExecutionContract,
+		...deps.runPromise === void 0 ? {} : { runPromise: deps.runPromise },
 		signer: deps.signer
 	};
 }
 function makePayrollMethods(deps, orgId) {
 	const requestKeyScope = deps.requestKeyScope ?? `client-${crypto.randomUUID()}`;
-	async function authorize(input, signal) {
+	async function authorize(input, controls) {
+		const signal = controls?.signal;
 		const execution = executionDependencies(deps);
 		if (execution === null) return {
 			ok: false,
@@ -8573,14 +8838,14 @@ function makePayrollMethods(deps, orgId) {
 		let authorized;
 		let preparedClosed = false;
 		const submitted = await executePrepared(execution, async (signerAddress) => {
-			const prepared = await runIfActive(signal, AUTHORIZE_RUN, () => deps.convexCall.action(payrollContract.authorizeRun, { input: {
+			const prepared = await runIfActive(signal, AUTHORIZE_RUN, () => withInvocationParentSpan(Effect.suspend(() => deps.convexCall.action(payrollContract.authorizeRun, copyInvocationObservation(controls, { input: {
 				orgId,
 				permissionId: input.permissionId,
 				requestKey: requestKey.key,
 				signerAddress,
 				period: input.period,
 				items: input.items
-			} }));
+			} }))), controls), deps.runPromise);
 			if (!prepared.ok) return prepared;
 			authorized = prepared.value.run;
 			return {
@@ -8593,7 +8858,7 @@ function makePayrollMethods(deps, orgId) {
 			requestKey: requestKey.key,
 			runId: authorized.id,
 			items: input.items
-		})(request), true, () => preparedClosed = true, signal);
+		})(request), true, () => preparedClosed = true, signal, controls);
 		try {
 			await requestKey.finish(submitted.ok || preparedClosed);
 		} catch {}
@@ -8607,35 +8872,48 @@ function makePayrollMethods(deps, orgId) {
 		};
 	}
 	return {
-		runs: (options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.payroll.runs, () => Effect.map(deps.convexCall.query(payrollContract.runs, { orgId }), toPayrollRuns)),
-		authorizeRun: async (input, options) => {
-			if (options?.signal?.aborted === true) return {
-				ok: false,
-				error: Errors.cancelled({ operation: AUTHORIZE_RUN })
-			};
-			try {
-				return await authorize(input, options?.signal);
-			} catch (cause) {
-				return {
-					ok: false,
-					error: cause instanceof CapxulError ? cause : Errors.unknown(cause)
-				};
-			}
+		runs: (options) => {
+			const controls = deps.invocationControls?.(options) ?? options;
+			return runPortEffect(Effect.suspend(() => deps.convexCall.query(payrollContract.runs, copyInvocationObservation(controls, { orgId }))).pipe(Effect.map(toPayrollRuns)), controls, CAPXUL_OPERATIONS.payroll.runs, deps.runPromise);
+		},
+		authorizeRun: (input, options) => {
+			const controls = deps.invocationControls?.(options) ?? options;
+			return runCapxulEffect(Effect.gen(function* () {
+				if (controls?.signal?.aborted === true) return yield* Effect.fail(Errors.cancelled({ operation: AUTHORIZE_RUN }));
+				const parent = yield* Effect.currentSpan.pipe(Effect.orDie);
+				const result = yield* Effect.tryPromise({
+					try: () => authorize(input, carryInvocationParentSpan(controls, parent)),
+					catch: (cause) => cause instanceof CapxulError ? cause : Errors.unknown(cause)
+				});
+				return yield* result.ok ? Effect.succeed(result.value) : Effect.fail(result.error);
+			}), observationOnlyControls(controls), AUTHORIZE_RUN, deps.runPromise);
+		},
+		terms: (options) => {
+			const controls = deps.invocationControls?.(options) ?? options;
+			return runPortEffect(Effect.suspend(() => deps.convexCall.query(payrollContract.terms, copyInvocationObservation(controls, { orgId }))), controls, CAPXUL_OPERATIONS.payroll.terms, deps.runPromise);
 		},
-		terms: (options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.payroll.terms, () => deps.convexCall.query(payrollContract.terms, { orgId })),
 		groups: {
-			list: (options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.payroll.groups.list, () => Effect.map(deps.convexCall.query(payrollContract.groups, { orgId }), (groups) => groups.map(toPayrollGroup))),
-			save: (input, options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.payroll.groups.save, () => Effect.map(deps.convexCall.mutation(payrollContract.saveGroup, {
-				orgId,
-				...input.id === void 0 ? {} : { id: String(input.id) },
-				name: input.name,
-				tone: input.tone,
-				members: input.members
-			}), toPayrollGroup)),
-			remove: (id, options) => runIfActive(options?.signal, CAPXUL_OPERATIONS.payroll.groups.remove, () => Effect.map(deps.convexCall.mutation(payrollContract.removeGroup, {
-				orgId,
-				id
-			}), () => void 0))
+			list: (options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => deps.convexCall.query(payrollContract.groups, copyInvocationObservation(controls, { orgId }))).pipe(Effect.map((groups) => groups.map(toPayrollGroup))), controls, CAPXUL_OPERATIONS.payroll.groups.list, deps.runPromise);
+			},
+			save: (input, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => deps.convexCall.mutation(payrollContract.saveGroup, copyInvocationObservation(controls, {
+					orgId,
+					...input.id === void 0 ? {} : { id: String(input.id) },
+					name: input.name,
+					tone: input.tone,
+					members: input.members
+				}))).pipe(Effect.map(toPayrollGroup)), controls, CAPXUL_OPERATIONS.payroll.groups.save, deps.runPromise);
+			},
+			remove: (id, options) => {
+				const controls = deps.invocationControls?.(options) ?? options;
+				return runPortEffect(Effect.suspend(() => deps.convexCall.mutation(payrollContract.removeGroup, copyInvocationObservation(controls, {
+					orgId,
+					id
+				}))).pipe(Effect.asVoid), controls, CAPXUL_OPERATIONS.payroll.groups.remove, deps.runPromise);
+			}
 		}
 	};
 }
@@ -9084,6 +9362,8 @@ function makeOrgMethods(deps) {
 			const convexCall = deps.convexCall;
 			return {
 				...makeActorRelationshipMethods({
+					...deps.runPromise === void 0 ? {} : { runPromise: deps.runPromise },
+					...deps.invocationControls === void 0 ? {} : { invocationControls: deps.invocationControls },
 					actor: {
 						kind: "org",
 						orgId: String(orgId)
@@ -9213,6 +9493,8 @@ function makeOrgMethods(deps) {
 				}, String(orgId)),
 				payments: convexCall === void 0 ? makeNotImplementedOrganizationPaymentsMethods() : makeOrganizationPaymentsMethods({
 					convexCall,
+					...deps.runPromise === void 0 ? {} : { runPromise: deps.runPromise },
+					...deps.invocationControls === void 0 ? {} : { invocationControls: deps.invocationControls },
 					...deps.requestKeyScope === void 0 ? {} : { requestKeyScope: deps.requestKeyScope },
 					...deps.actor === void 0 ? {} : { actor: deps.actor },
 					...deps.chainId === void 0 ? {} : { chainId: Number(deps.chainId) },
@@ -9221,6 +9503,8 @@ function makeOrgMethods(deps) {
 				}, String(orgId)),
 				payroll: convexCall === void 0 ? makeUnavailablePayrollMethods() : makePayrollMethods({
 					convexCall,
+					...deps.runPromise === void 0 ? {} : { runPromise: deps.runPromise },
+					...deps.invocationControls === void 0 ? {} : { invocationControls: deps.invocationControls },
 					...deps.requestKeyScope === void 0 ? {} : { requestKeyScope: deps.requestKeyScope },
 					...deps.actor === void 0 ? {} : { actor: deps.actor },
 					...deps.chainId === void 0 ? {} : { chainId: Number(deps.chainId) },
@@ -9522,6 +9806,8 @@ function assembleCapxulClient(input) {
 	let detectPendingOrgInvitations;
 	let kickProvisioning;
 	const financialOps = makeFinancialOpsMethods({
+		runPromise: effectRunner.runPromise,
+		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls, actor.authSession()?.authUserId),
 		actor,
 		chainId: input.bootstrap.chainId,
 		convexCall: input.ports.convexCall,
@@ -9541,7 +9827,7 @@ function assembleCapxulClient(input) {
 		profileMethods: financialOps.me,
 		convexCall: input.ports.convexCall,
 		runPromise: effectRunner.runPromise,
-		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls),
+		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls, actor.authSession()?.authUserId),
 		...input.signer === void 0 ? {} : { signer: input.signer }
 	});
 	kickProvisioning = accountBundle.kickProvisioning;
@@ -9594,21 +9880,21 @@ function assembleCapxulClient(input) {
 		convexCall: input.ports.convexCall,
 		telemetry: input.ports.telemetry,
 		runPromise: effectRunner.runPromise,
-		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls)
+		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls, actor.authSession()?.authUserId)
 	});
 	const accounts = makeAccountsMethods({
 		accountReadPort: input.ports.accountRead,
 		chainId: input.bootstrap.chainId,
 		telemetry: input.ports.telemetry,
 		runPromise: effectRunner.runPromise,
-		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls)
+		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls, actor.authSession()?.authUserId)
 	});
 	const orgMethods = makeOrgMethods({
 		actor,
 		chainId: input.bootstrap.chainId,
 		telemetry: input.ports.telemetry,
 		runPromise: effectRunner.runPromise,
-		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls),
+		invocationControls: (controls) => withHostObservationControls(observation.hostObservationSnapshot, controls, actor.authSession()?.authUserId),
 		requestKeyScope: `${input.bootstrap.convexUrl}:${String(input.bootstrap.chainId)}`,
 		...selectedOrgPort === void 0 ? {} : { orgPort: selectedOrgPort },
 		convexCall: input.ports.convexCall,
@@ -9759,7 +10045,7 @@ function transitionError(record) {
 }
 function withHostObservation(actor, snapshot) {
 	if (snapshot === void 0) return actor;
-	const controls = (input) => withHostObservationControls(snapshot, input);
+	const controls = (input) => withHostObservationControls(snapshot, input, actor.authSession()?.authUserId);
 	return {
 		...actor,
 		ask: (event, input) => actor.ask(event, controls(input)),
@@ -9767,10 +10053,14 @@ function withHostObservation(actor, snapshot) {
 		restoreAuthSession: (session, input) => actor.restoreAuthSession(session, controls(input))
 	};
 }
-function withHostObservationControls(snapshot, input) {
-	const copied = { ...input };
-	const captured = snapshot?.();
-	return captured === void 0 ? copied : attachInvocationObservation(copied, captured);
+function withHostObservationControls(snapshot, input, actorId) {
+	const previous = readInvocationObservation(input);
+	if (previous !== void 0) return attachInvocationObservation({ ...input }, previous);
+	const captured = snapshot?.() ?? { active: true };
+	return attachInvocationObservation({ ...input }, {
+		...captured,
+		...actorId === void 0 ? {} : { actorId }
+	});
 }
 //#endregion
 export { stampTelemetryEnvelope as $, safeExceptionLabel as A, resolveFailureMode as B, observeFailedResult as C, normalizeExceptionErrorKind as D, SDK_VERSION as E, causeChain as F, sanitizeObservationContext as G, readInvocationObservation as H, injectedWalletSigner as I, CAPXUL_FUNCTIONS as J, PAYMENT_DIRECTIONS as K, isSignerNotReadySignal as L, fromWei as M, isSettingUpLifecycle as N, normalizeExceptionOperation as O, formatTraceparent as P, redactTelemetryProps as Q, openfortSignerNotReadyCode as R, observationContextProps as S, EXCEPTION_MESSAGE as T, OBSERVATION_CONTEXT_HEADER as U, copyInvocationObservation as V, encodeObservationContextHeader as W, EngineeringTelemetryBootstrapPolicy as X, BootstrapEnvelope as Y, redactTelemetryEvent as Z, fingerprintPaymentIntent as _, AccountReadPortTag as a, isRestoring as at, failureDetail as b, retryIdempotentRead as c, IdentityPortTag as d, CAPXUL_OPERATIONS as et, identityErrorFromCapxul as f, bootstrapErrorFromCapxul as g, BootstrapPortTag as h, smartAccountErrorFromCapxul as i, isClaimed as it, version as j, projectSdkException as k, PRODUCT_INVOCATION as l, convexCallErrorFromCapxul as m, detectAuthCacheAdapter as n, normalizeCapxulOperation as nt, accountReadErrorFromCapxul as o, ConvexCallPortTag as p, PAYMENT_STATUSES as q, SmartAccountPortTag as r, destination as rt, TelemetryPortTag as s, assembleCapxulClient as t, isCapxulOperation as tt, wireChainId as u, toWei as v, postHogFailureObservation as w, failureEvidenceProps as x, CAPXUL_SDK_EXPECTED_OUTCOME_EVENT as y, signerFailure as z };