@capxul/mcp 4.0.0 → 4.1.0

package/dist/main.mjs

@@ -8,7 +8,7 @@ import { createHash } from "node:crypto";
 import { createServer } from "node:http";
 import { localhostHostValidation, localhostOriginValidation, toNodeHandler } from "@modelcontextprotocol/node";
 import { z } from "zod";
-import { Cause, Context, Data, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Ref, Result, Schedule, Schema, SchemaGetter, SchemaIssue, SchemaParser, Scope, Tracer } from "effect";
+import { Cause, Clock, Context, Data, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Ref, Result, Schedule, Schema, SchemaGetter, SchemaIssue, SchemaParser, Scope, Tracer } from "effect";
 import { FetchHttpClient, Headers, HttpClient } from "effect/unstable/http";
 import { OtlpExporter, OtlpLogger, OtlpSerialization, OtlpTracer } from "effect/unstable/observability";
 import { resolve } from "path";
@@ -4056,12 +4056,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",
@@ -4124,6 +4126,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",
@@ -4274,7 +4277,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" },
@@ -4289,6 +4293,7 @@ const CAPXUL_OPERATIONS = {
 		prepareExecution: "payments.prepareExecution",
 		prepareLifecycleExecution: "payments.prepareLifecycleExecution",
 		redirect: "payments.redirect",
+		retry: "payments.retry",
 		submitCommandExecution: "payments.submitCommandExecution",
 		submitExecution: "payments.submitExecution"
 	},
@@ -4370,6 +4375,7 @@ const CAPXUL_OPERATIONS = {
 	smartAccount: {
 		claim: "smartAccount.claim",
 		confirmDeployment: "smartAccount.confirmDeployment",
+		loadByAuthUserId: "smartAccount.loadByAuthUserId",
 		loadCurrent: "smartAccount.loadCurrent",
 		provision: "smartAccount.provision"
 	},
@@ -5139,6 +5145,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 redactTelemetryProps(name, props, options = {}) {
 	if (props === void 0) return void 0;
 	const clone = cloneProps$1(props);
@@ -7091,9 +7239,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,
@@ -7123,6 +7272,12 @@ function markFailureInvocationSnapshot(failure, snapshot) {
 	});
 	return failure;
 }
+/** @internal Read the call-start delivery decision; undefined means a direct adapter call. */
+function readFailureInvocationSnapshot(failure) {
+	if (typeof failure !== "object" || failure === null) return void 0;
+	const snapshot = failure[FAILURE_INVOCATION_SNAPSHOT];
+	return typeof snapshot === "object" && snapshot !== null && "active" in snapshot ? snapshot : void 0;
+}
 //#endregion
 //#region ../../packages/sdk/src/surface/_shared/provisioning-telemetry.ts
 async function emitProvisioningTelemetry(telemetry, smartAccount) {
@@ -9740,10 +9895,10 @@ const logIdentityTransition = (record) => (record.outcome === "applied" ? Effect
 //#region ../../packages/sdk/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];
@@ -10094,13 +10249,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;
@@ -10108,7 +10263,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 ../../packages/sdk/src/surface/_shared/effect-actor-bridge.ts
@@ -10159,22 +10315,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) {
@@ -10733,76 +10919,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) => 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)
+			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);
+			},
+			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) => 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))
+			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);
+			},
+			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) => {
@@ -10879,22 +11099,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",
@@ -11262,6 +11472,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 }
@@ -11315,7 +11527,7 @@ const moneyExecutionContract = {
 };
 //#endregion
 //#region ../../packages/sdk/package.json
-var version$1 = "4.0.0";
+var version$1 = "4.1.0";
 //#endregion
 //#region ../../packages/sdk/src/telemetry/exception-projection.ts
 /** Fixed fallback for failures that have no safe message. */
@@ -11394,7 +11606,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;
@@ -11426,7 +11639,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++) {
@@ -11438,7 +11651,7 @@ function report(adapter, kind, operation, cause, invocation, origin) {
 	const kindName = normalizeErrorKind(errorKind$1(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);
@@ -11452,6 +11665,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 {
@@ -11867,17 +12081,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" })
@@ -11901,16 +12115,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];
@@ -11931,28 +12145,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 ../../packages/sdk/src/surface/payment-execution.ts
@@ -12391,51 +12605,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, {})),
@@ -12487,58 +12702,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",
@@ -12551,7 +12772,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: {
@@ -12577,8 +12798,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);
+			}
 		}
 	};
 }
@@ -17375,6 +17602,7 @@ function makeConnectionId() {
 //#region ../../packages/sdk/src/adapters/convex-call/ConvexCallAdapter.ts
 /** Exact floor-first allowlist; every additional handler must migrate its validator first. */
 const OBSERVED_CONVEX_ACTIONS = /* @__PURE__ */ new Set([
+	"payroll/actions:authorizeRun",
 	"account/actions:readBalance",
 	"holdings/actions:current",
 	"smartAccount/actions:claim",
@@ -17392,12 +17620,36 @@ const OBSERVED_CONVEX_ACTIONS = /* @__PURE__ */ new Set([
 	"moneyExecution/paymentCommandActions:submitPaymentCommandExecution"
 ]);
 const OBSERVED_CONVEX_QUERIES = /* @__PURE__ */ new Set([
+	"movement/activity:list",
+	"movement/activity:summary",
+	"movement/activity:get",
+	"financialOps/queries:verifyPaymentDocument",
+	"financialOps/queries:renderStoredDocument",
+	"financialOps/addressBook:list",
+	"financialOps/addressBook:get",
+	"financialOps/requestsInbox:list",
+	"financialOps/requestsInbox:get",
+	"financialOps/requestsInbox:inboxList",
+	"payroll/queries:runs",
+	"payroll/queries:groups",
+	"payroll/queries:terms",
 	"financialOps/queries:resolveRecipient",
 	"identity/queries:loadByAuthUserId",
 	"smartAccount/queries:loadByAuthUserId",
 	"org/lifecycle:load"
 ]);
 const OBSERVED_CONVEX_MUTATIONS = /* @__PURE__ */ new Set([
+	"movement/activity:annotate",
+	"financialOps/addressBook:add",
+	"financialOps/addressBook:hide",
+	"financialOps/addressBook:unhide",
+	"financialOps/addressBook:label",
+	"financialOps/requestsInbox:issue",
+	"financialOps/requestsInbox:cancel",
+	"financialOps/requestsInbox:approve",
+	"financialOps/requestsInbox:decline",
+	"payroll/mutations:saveGroup",
+	"payroll/mutations:removeGroup",
 	"identity/mutations:create",
 	"identity/mutations:update",
 	"identity/mutations:completeOnboarding",
@@ -17466,7 +17718,7 @@ var ConvexCallAdapter = class {
 		const carriedContext = sanitizeObservationContext(args.observationContext);
 		let hostContext;
 		const invocationSnapshot = readInvocationObservation(args);
-		if (invocationSnapshot !== void 0) hostContext = invocationSnapshot.context;
+		if (invocationSnapshot !== void 0) hostContext = invocationSnapshot.active ? invocationSnapshot.context : void 0;
 		else {
 			const resolveContext = this.#observation?.resolveContext;
 			if (resolveContext !== void 0) try {
@@ -43307,13 +43559,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 })
@@ -43346,7 +43599,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,
@@ -43395,41 +43648,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
@@ -43526,12 +43811,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,
@@ -43544,14 +43831,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 {
@@ -43564,7 +43851,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 {}
@@ -43578,35 +43865,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);
+			}
 		}
 	};
 }
@@ -44055,6 +44355,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)
@@ -44184,6 +44486,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) },
@@ -44192,6 +44496,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) },
@@ -44601,6 +44907,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,
@@ -44620,7 +44928,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;
@@ -44673,21 +44981,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,
@@ -44838,7 +45146,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)),
@@ -44846,10 +45154,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
 //#region ../../packages/sdk/src/host-observability.ts
@@ -46247,7 +46559,7 @@ function stdioIdentity(env = process.env, options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "4.0.0";
+var version = "4.1.0";
 //#endregion
 //#region src/deps.ts
 const NO_IDENTITY = async () => void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/mcp",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "private": false,
   "description": "Capxul MCP server for auth, Account readiness, identity, Organizations, relationships, requests, destinations, and testnet funding over Streamable HTTP.",
   "keywords": [
@@ -51,7 +51,7 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
     "vite-plus": "0.3.0",
     "@capxul/config": "0.3.0",
-    "@capxul/sdk": "4.0.0",
+    "@capxul/sdk": "4.1.0",
     "@capxul/typescript-config": "0.0.0"
   },
   "scripts": {