@capxul/sdk 4.1.4 → 4.2.0-rc.10

package/dist/{observation-Bhdq9-l6.d.mts → production-Du4Vc7YD.d.mts}

@@ -1,6 +1,6 @@
-import { $ as PublishableKey, A as AppId, D as AllowanceKey, E as Address$1, F as ChainId, G as OrgId, H as EpochMs, I as CountryCode, J as PayrollGroupId, K as PartyId, L as CurrencyCode, M as AuthUserId, N as BlockNumber, O as AllowedOrigin, P as BudgetId, Q as Profile, R as DocumentHash, St as FailureMode, V as Email, W as Money, X as PermissionAssignmentId, Y as PayrollRunId, Z as PermissionId, _ as ClockPort, a as SignerStatusStore, at as WeiAmount, c as AccountProviderSource, et as RoleKey, ft as CapxulError, g as SmartAccount$1, gt as Failure, h as Session$1, it as TxHash, j as AuthSession, k as AnonymousDistinctId, l as AccountRequirement, m as Profile$1, mt as CapxulErrorDetails, n as CapxulSigner, nt as SmartAccount, p as CapxulResult, pt as CapxulErrorCode, q as PaymentCommandId, rt as TesterKind, tt as SessionToken, v as AuthClientPort, w as Account$1, x as AuthCachePort, y as CanSendOtpStatus, z as DurationMs } from "./signer-C0hZ6Kiy.mjs";
-import { Context, Effect, Layer, Schema, Scope, Tracer } from "effect";
+import { $ as PayrollGroupId, A as AllowanceKey, B as ChainId, C as AuthCachePort, D as Account$1, Et as FailureMode, F as AssetId, H as CurrencyCode, I as AuthSession, K as Email, L as AuthUserId, M as AnonymousDistinctId, N as AppId, Q as PaymentCommandId, R as BlockNumber, U as DocumentHash, V as CountryCode, W as DurationMs, X as OrgId, Y as Money, Z as PartyId, _ as Session$1, _t as CapxulErrorCode, at as RoleKey, b as AuthClientPort, bt as Failure, ct as TesterKind, d as AccountRequirement, et as PayrollRunId, g as Profile$1, gt as CapxulError, h as CapxulResult, i as CapxulSigner, it as PublishableKey, j as AllowedOrigin, k as Address$1, lt as TxHash, nt as PermissionId, ot as SessionToken, q as EpochMs, rt as Profile, s as SignerStatusStore, st as SmartAccount, tt as PermissionAssignmentId, u as AccountProviderSource, ut as WeiAmount, v as SmartAccount$1, vt as CapxulErrorDetails, x as CanSendOtpStatus, y as ClockPort, z as BudgetId } from "./OAuthBearerAuthClient-C-ip-z8M.mjs";
 import { Hex } from "viem";
+import { Context, Effect, Layer, Schema, Scope, Tracer } from "effect";
 import { FunctionReference } from "convex/server";
 //#region src/domain/machine/shell.d.ts
 declare const INVOCATION_PARENT_SPAN: unique symbol;
@@ -78,6 +78,11 @@ interface OrgDraft {
 interface OrgSubmissionDraft extends OrgDraft {
   readonly bio?: string;
   readonly size?: string;
+  /**
+   * #1955: the logo uploaded on file pick. The org lane spreads this draft
+   * straight into `startOrResume`, which records it on the `orgs` insert.
+   */
+  readonly logoStorageId?: string;
 }
 /** The org lane, keyed by the active orgId — which does not exist yet while the
  * FIRST DURABLE ORG WRITE is in flight, hence `creating` carrying only a draft. */
@@ -279,7 +284,7 @@ interface TelemetryPort {
 }
 //#endregion
 //#region ../observability/src/index.d.ts
-declare const TELEMETRY_EVENT_NAMES: readonly ["auth_otp_requested", "auth_otp_delivered", "auth_otp_expired", "auth_verified", "auth_failed", "auth_signed_out", "onboarding_intent_selected", "onboarding_profile_submitted", "onboarding_organization_submitted", "onboarding_dashboard_reached", "provisioning_safe_created", "provisioning_safe_confirmed", "bootstrap_resolved", "bootstrap_failed", "member_activation_started", "member_activation_ready", "member_activation_failed", "organization_creation_started", "organization_creation_ready", "organization_creation_failed", "chain_upstream_fallback", "bundler_error", "receipt_pending", "operation_retried", "account_balance_read", "account_balance_failed", "faucet_requested", "faucet_confirmed", "faucet_failed", "org_create_started", "org_safe_created", "org_safe_confirmed", "org_roles_seeded", "org_created", "org_create_failed", "org_invite_sent", "org_invite_accepted", "org_invite_expired", "payment_initiated", "payment_settled", "payment_failed", "payment_verification_retry", "payment_lifecycle_transition", "quick_pay_external_address_acknowledged", "deposit_initiated", "deposit_settled", "permission_mirror_verification", "movement_scan_window", "movement_scan_checkpoint", "movement_scan_incident", "activity_annotation_saved", "ui_activity_action_completed", "contact_relationship_changed", "ui_contact_action_completed"];
+declare const TELEMETRY_EVENT_NAMES: readonly ["auth_otp_requested", "auth_otp_delivered", "auth_otp_expired", "auth_verified", "auth_failed", "identity_refused", "auth_signed_out", "onboarding_intent_selected", "onboarding_profile_submitted", "onboarding_organization_submitted", "onboarding_dashboard_reached", "provisioning_safe_created", "provisioning_safe_confirmed", "bootstrap_resolved", "bootstrap_failed", "member_activation_started", "member_activation_ready", "member_activation_failed", "organization_creation_started", "organization_creation_ready", "organization_creation_failed", "chain_upstream_fallback", "bundler_error", "receipt_pending", "operation_retried", "account_balance_read", "account_balance_failed", "faucet_requested", "faucet_confirmed", "faucet_failed", "org_create_started", "org_safe_created", "org_safe_confirmed", "org_roles_seeded", "org_created", "org_create_failed", "org_invite_sent", "org_invite_accepted", "org_invite_expired", "payment_initiated", "payment_settled", "payment_failed", "payment_verification_retry", "payment_lifecycle_transition", "quick_pay_external_address_acknowledged", "deposit_initiated", "deposit_settled", "permission_mirror_verification", "movement_scan_window", "movement_scan_checkpoint", "movement_scan_incident", "activity_annotation_saved", "ui_activity_action_completed", "contact_relationship_changed", "ui_contact_action_completed", "access_recovery_completed", "ui_access_step_completed", "org_invite_progressed", "invoice_issued", "invoice_request_transitioned", "ui_invoice_step_completed", "ui_treasury_step_completed", "ui_receive_step_completed", "payroll_group_changed", "payroll_run_transitioned", "ui_payroll_action_completed"];
 type TelemetryEventName = (typeof TELEMETRY_EVENT_NAMES)[number];
 type TelemetryProps = Record<string, unknown>;
 type TelemetryEvent = {
@@ -606,6 +611,10 @@ type BootstrapResolution = {
   readonly siteBaseUrl: string;
   readonly openfortPublishableKey: string;
   readonly shieldPublishableKey: string;
+  /** Openfort third-party auth provider the signer presents; absent means better-auth. */
+  readonly openfortAuthProvider?: "better-auth" | "oidc";
+  /** Origin of the Ponder indexer the SDK reads directly; absent means no indexer reads. */
+  readonly indexerUrl?: string;
   readonly engineeringTelemetry?: EngineeringTelemetryBootstrapPolicyV1;
 };
 type BootstrapErrorKind = "notAuthenticated" | "network" | "provider" | "malformedBody" | "invalidInput" | "rateLimited";
@@ -710,6 +719,16 @@ type UpdateIdentityInput = {
   readonly displayName?: string;
   readonly country?: CountryCode;
 };
+/** The chain families a payout address may name (#1955). */
+declare const PAYOUT_CHAINS: readonly ["evm", "solana", "starknet"];
+/**
+ * One payout address, named BY CHAIN FAMILY. The network is the deployment's
+ * and the backend derives it (#1955) — a caller never sends one.
+ */
+type PayoutAddress = {
+  readonly chain: (typeof PAYOUT_CHAINS)[number];
+  readonly address: string;
+};
 /**
  * D-ONBOARD (#669) — the onboarding-complete identity write. Composes the
  * existing create/update write into one idempotent upsert that ALSO sets the
@@ -717,6 +736,10 @@ type UpdateIdentityInput = {
  * allowed raw-0x class). `displayName` + `country` are required at onboarding
  * time. The returned `Profile` is the existing branded shape — the onboarding
  * flags live on the wire row and are not projected onto the read surface.
+ *
+ * #1955: it also carries the photo the signup form uploaded and the payout
+ * addresses it collected, so the backend writes all three in one transaction
+ * instead of the app binding them with two more calls afterwards.
  */
 type CompleteOnboardingIdentityInput = {
   readonly authUserId: AuthUserId;
@@ -726,6 +749,9 @@ type CompleteOnboardingIdentityInput = {
   readonly withdrawalAddress?: Address$1;
   /** One globally unique Party handle. */
   readonly handle: string;
+  /** Storage id from `media.uploadImage`; bound on the identity write itself. */
+  readonly imageStorageId?: string;
+  readonly payoutAddresses?: readonly PayoutAddress[];
 };
 declare const IdentityError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "IdentityError";
@@ -882,6 +908,118 @@ interface AccountReadPort {
   fundFromFaucet(input: FundFromFaucetInput): Effect.Effect<FundFromFaucetResult, AccountReadError, never>;
 }
 //#endregion
+//#region src/ports/indexer-read.d.ts
+/**
+ * IndexerReadPort is the SDK's read seam onto the Ponder read model
+ * (`apps/indexer`). Ponder holds what the chain said; Convex holds what the
+ * user meant. Nothing here is copied into Convex, nothing waits for a
+ * finality tag, and no write path may read through this port.
+ *
+ * Every read is scoped to one Safe and one page. The indexer accepts only the
+ * exact compiled statements in `apps/indexer/src/queries.ts`, so the adapter
+ * that implements this port reproduces those statements byte for byte and the
+ * service refuses anything else with 403.
+ */
+/** One page of rows for one Safe. `offset` defaults to 0 (the first page). */
+interface IndexerReadInput {
+  /** The Safe the caller owns. The indexer refuses a Safe outside the session claim. */
+  readonly safe: Address$1;
+  /** 1 to 1000 inclusive — the indexer's own bound. */
+  readonly limit: number;
+  readonly offset?: number;
+}
+/**
+ * The chain evidence every indexed row carries. `id` is the logical event id
+ * `chainId:txHash:transactionLogOrdinal`; it survives a reorg, so it is the
+ * key a Convex intent row stitches against.
+ */
+interface IndexerEventIdentity {
+  readonly id: string;
+  readonly chainId: ChainId;
+  readonly txHash: TxHash;
+  readonly transactionLogOrdinal: number;
+  readonly blockNumber: bigint;
+  readonly blockHash: string;
+  /** Block timestamp in epoch seconds. */
+  readonly timestamp: bigint;
+}
+interface IndexerTransferRow extends IndexerEventIdentity {
+  readonly assetId: AssetId;
+  readonly token: Address$1;
+  readonly from: Address$1;
+  readonly to: Address$1;
+  /**
+   * Raw token units, exact. This is an evidence boundary, so the row never
+   * carries Money or AssetAmount: the reader owns the asset's decimals.
+   */
+  readonly amount: bigint;
+}
+interface IndexerPaymentRow extends IndexerEventIdentity {
+  readonly contract: Address$1;
+  /** The protocol settlement id a Convex Payment command stitches against. */
+  readonly settlementId: string;
+  readonly sender: Address$1;
+  readonly recipient: Address$1;
+  readonly assetId: AssetId;
+  readonly token: Address$1;
+  /** Raw token units, exact. */
+  readonly amount: bigint;
+  readonly kind: number;
+  readonly documentHash: string;
+}
+/** A row of the indexer's signed-transfer `balance` view. */
+interface IndexerBalanceRow {
+  readonly chainId: ChainId;
+  readonly assetId: AssetId;
+  readonly address: Address$1;
+  /** Raw token units, exact. */
+  readonly amount: bigint;
+}
+/** One chain's sync position, from the indexer's native `/status` route. */
+interface IndexerChainStatus {
+  readonly chain: string;
+  readonly chainId: ChainId;
+  readonly blockNumber: bigint;
+  /** Block timestamp in epoch seconds. Its age is the freshness label. */
+  readonly blockTimestamp: bigint;
+}
+/**
+ * The tables this seam reads today. P04 adds the authority rows (`safe`,
+ * `safe_event`, `roles_module`) and P05 adds `commitment`: each is one more
+ * entry here plus its statement and decoder.
+ */
+interface IndexerRowsByTable {
+  readonly transfer: readonly IndexerTransferRow[];
+  readonly payment: readonly IndexerPaymentRow[];
+  readonly balance: readonly IndexerBalanceRow[];
+}
+type IndexerTable = keyof IndexerRowsByTable;
+declare const IndexerReadError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "IndexerReadError";
+} & Readonly<A>;
+declare class IndexerReadError extends IndexerReadError_base<{
+  readonly operation: string;
+  readonly publicCode: CapxulErrorCode;
+  readonly publicError: CapxulError;
+  readonly cause: unknown;
+  readonly details?: CapxulErrorDetails;
+}> {}
+interface IndexerReadPort {
+  /** One page of rows, newest block first. An empty page is a value, not an error. */
+  read<T extends IndexerTable>(table: T, input: IndexerReadInput): Effect.Effect<IndexerRowsByTable[T], IndexerReadError>;
+  /**
+   * The same page over the indexer's live stream. The first snapshot is
+   * `loading`; each later snapshot carries the whole page again. The indexer
+   * closes the stream on token expiry or revoked authority, which arrives as
+   * one `error` snapshot — the caller re-reads with a refreshed token.
+   *
+   * @internal-use — substrate reactive transport, like `ConvexCallPort.subscribe`.
+   */
+  subscribe<T extends IndexerTable>(table: T, input: IndexerReadInput, callback: (snapshot: Snapshot<IndexerRowsByTable[T]>) => void): Effect.Effect<Unsubscribe, IndexerReadError>;
+  /** Sync position per chain. Unauthenticated: a stale index is not a refusal. */
+  readonly status: Effect.Effect<readonly IndexerChainStatus[], IndexerReadError>;
+}
+//#endregion
 //#region src/flows/types.d.ts
 /** The runtime port bundle that `assembleCapxulClient` uses. */
 interface FlowPorts {
@@ -894,6 +1032,11 @@ interface FlowPorts {
   readonly clock: ClockPort;
   readonly telemetry: TelemetryPort;
   readonly convexCall: ConvexCallPort;
+  /**
+   * The Ponder read seam (P02). Optional: it is present only when the client
+   * was given an indexer origin, and every existing flow works without it.
+   */
+  readonly indexerRead?: IndexerReadPort;
 }
 /** Legacy method input retained by the imperative auth surface. */
 interface ExternalSigner {
@@ -929,6 +1072,8 @@ type StartOrResumeOrganizationInput = {
   /** #1064: optional onboarding-collected description + size bucket. */
   readonly bio?: string;
   readonly size?: string;
+  /** #1955: storage id from `media.uploadImage`, recorded on the org insert. */
+  readonly logoStorageId?: string;
   /** @internal Safe trace/correlation carriage owned by the identity flow. */
   readonly observationContext?: WireObservationContext;
 };
@@ -1019,7 +1164,16 @@ interface SmartAccountMethods {
 }
 //#endregion
 //#region src/surface/identity.d.ts
-interface CompleteProfileInput {
+/**
+ * #1955: what a create call may carry besides the three required fields — the
+ * photo already uploaded and the payout addresses the form collected.
+ */
+interface ProfileCarriage {
+  /** Storage id from `media.uploadImage`. */
+  readonly imageStorageId?: string;
+  readonly payoutAddresses?: readonly PayoutAddress[];
+}
+interface CompleteProfileInput extends ProfileCarriage {
   readonly displayName: string;
   readonly country: string;
   readonly handle: string;
@@ -1518,20 +1672,19 @@ interface ActivityAnnotationInput {
   readonly accountingCategory?: string;
   readonly memo?: string;
 }
+/**
+ * #1960 R02: the declared option type is the `InvocationControls` these methods
+ * have always forwarded to `deps.invocationControls`, so an Activity action can
+ * carry the correlation its UI observation already used. `{ signal }` callers
+ * are unaffected.
+ */
 interface ActivityMethods {
-  list(params?: ActivityListParams, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<ActivityPage>>;
-  summary(params?: ActivitySummaryParams, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<ActivitySummary>>;
-  get(reference: ActivityReference, options?: {
-    readonly signal?: AbortSignal;
+  list(params?: ActivityListParams, options?: InvocationControls): Promise<CapxulResult<ActivityPage>>;
+  summary(params?: ActivitySummaryParams, options?: InvocationControls): Promise<CapxulResult<ActivitySummary>>;
+  get(reference: ActivityReference, options?: InvocationControls & {
     readonly actor?: ActorReference;
   }): Promise<CapxulResult<ActivityDetail | null>>;
-  annotate(input: ActivityAnnotationInput, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<ActivityAnnotation>>;
+  annotate(input: ActivityAnnotationInput, options?: InvocationControls): Promise<CapxulResult<ActivityAnnotation>>;
 }
 interface OfframpQuoteInput {
   readonly actor?: ActorReference;
@@ -1685,25 +1838,19 @@ interface AddressBookLabelInput {
 interface AddressBookListInput {
   readonly includeHidden?: boolean;
 }
+/**
+ * #1960 R02: the declared option type is the `InvocationControls` these methods
+ * have always forwarded to `deps.invocationControls`. Naming it lets a caller
+ * that captured one user attempt hand the same `correlation_id`/`journey_id` to
+ * the operation the attempt starts. `{ signal }` callers are unaffected.
+ */
 interface AddressBookMethods {
-  list(input?: AddressBookListInput, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<readonly AddressBookEntry[]>>;
-  get(entryId: PartyId, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<AddressBookEntry | null>>;
-  add(input: AddressBookAddInput, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<AddressBookEntry>>;
-  hide(entryId: PartyId, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<AddressBookEntry>>;
-  unhide(entryId: PartyId, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<AddressBookEntry>>;
-  label(input: AddressBookLabelInput, options?: {
-    readonly signal?: AbortSignal;
-  }): Promise<CapxulResult<AddressBookEntry>>;
+  list(input?: AddressBookListInput, options?: InvocationControls): Promise<CapxulResult<readonly AddressBookEntry[]>>;
+  get(entryId: PartyId, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry | null>>;
+  add(input: AddressBookAddInput, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
+  hide(entryId: PartyId, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
+  unhide(entryId: PartyId, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
+  label(input: AddressBookLabelInput, options?: InvocationControls): Promise<CapxulResult<AddressBookEntry>>;
 }
 interface ActorRequest {
   readonly id: string;
@@ -2545,6 +2692,13 @@ type IdentityProfileDetails = {
   readonly displayName: string;
   readonly country: string;
   readonly handle: string;
+  /**
+   * #1955: the storage id `useCapxulUploadImage` handed back on file pick, and
+   * the payout addresses the form collected. The create call carries them, so
+   * the backend binds the photo and writes the rails in the same durable step.
+   */
+  readonly imageStorageId?: string;
+  readonly payoutAddresses?: readonly PayoutAddress[];
 };
 interface IdentityRuntime {
   readonly snapshot: () => IdentityState;
@@ -2636,6 +2790,13 @@ interface CapxulClient {
      * NOT on the public `client.accounts` surface.
      */
     readonly accounts: AccountsFaucetMethods;
+    /**
+     * Ponder read seam (P02). Present only when the client was built with an
+     * indexer origin, so every reader treats it as optional. Ponder holds what
+     * the chain said; Convex holds what the user meant. Reads here never run
+     * inside a write path and never wait for a finality tag.
+     */
+    readonly indexer?: IndexerReadPort;
     /** Quarantined Reference-harness evidence; never a product Organization method. */
     readonly organizationSetup: OrganizationSetupProofMethods;
     /** Product telemetry projection for internal composition and test harnesses. */
@@ -2835,4 +2996,57 @@ interface ObservationAdapter {
 /** Stable PostHog event used for typed failures that are expected product outcomes. */
 declare const CAPXUL_SDK_EXPECTED_OUTCOME_EVENT = "capxul_sdk_expected_outcome";
 //#endregion
-export { OrganizationPaymentItemInput as $, TelemetryIdentifyInput as $n, DestinationKind as $t, OrgView as A, TargetReference as An, AddressBookLabelInput as At, PayrollGroup as B, OrgLifecycle as Bn, ActivityKind as Bt, DetectPendingOrgInvitationsResult as C, PaymentTiming as Cn, ActorProfileMethods as Ct, OrgMethods as D, RecipientResolution as Dn, ActorRequestsMethods as Dt, MemberView as E, PaymentsPayInput as En, ActorRequestIssueInput as Et, RoleSpendCap as F, isSettingUpLifecycle as Fn, ActivityAnnotation as Ft, PayrollOptions as G, SubmittedPermissionExecution as Gn, ActivityReference as Gt, PayrollGroupMember as H, ActorRef as Hn, ActivityMethods as Ht, RoleView as I, CompleteProfileInput as In, ActivityAnnotationInput as It, PayrollRunStatus as J, PAYMENT_STATUSES as Jn, ActivitySummaryTotal as Jt, PayrollRun as K, InboxStatus as Kn, ActivitySummary as Kt, AuthorizeRunInput as L, IdentityMethods as Ln, ActivityDetail as Lt, OrganizationAuditLogItem as M, fingerprintPaymentIntent as Mn, InboxApproveInput as Mt, ResendInviteTokenInput as N, AccountLifecycle as Nn, InboxItem as Nt, OrgScopedMethods as O, Ref$1 as On, AddressBookAddInput as Ot, RoleDefinition as P, AccountSetupStep as Pn, InboxMethods as Pt, OrganizationPaymentInput as Q, TelemetryGroupInput as Qn, DestinationAddInput as Qt, AuthorizeRunOptions as R, SmartAccountMethods as Rn, ActivityFilter as Rt, CreateOrgInput as S, PaymentStatus as Sn, ActorProfile as St, MemberStatus as T, PaymentsMethods as Tn, ActorRequest as Tt, PayrollGroupsMethods as U, CurrentHoldings as Un, ActivityPage as Ut, PayrollGroupInput as V, OrgSetupStep as Vn, ActivityListParams as Vt, PayrollMethods as W, Permission as Wn, ActivityRange as Wt, PayrollTermsUnit as X, RequestStatus as Xn, DepositInstructions as Xt, PayrollRuns as Y, PaymentStatus$1 as Yn, ActorReference as Yt, OrganizationPaymentBatchInput as Z, TelemetryEvent as Zn, Destination as Zt, SystemMethods as _, PaymentDocumentRef as _n, OrganizationOnboardingInput as _t, SdkFailureObservation as a, FinancialOpsMethods as an, Readiness as ar, PermissionOptions as at, CurrentUserContext as b, PaymentDocumentsMethods as bn, ReadyAccountLifecycle as bt, PostHogObservabilityOptions as c, MovementActivityEvidence as cn, isClaimed as cr, PermissionReadResult as ct, CreateCapxulClientInput as d, OfframpQuoteInput as dn, InvocationControls as dr, OrgMeMethod as dt, DestinationListInput as en, TelemetryPort as er, OrganizationPaymentsMethods as et, IdentityProfileDetails as f, OfframpStatus as fn, OrgMeOptions as ft, Holding as g, PaymentDocumentKind as gn, OrganizationOnboarding as gt, HoldingsMethods as h, PaymentDirection as hn, OnboardingMethods as ht, ObservationDelivery as i, DestinationsMethods as in, OrgLane as ir, PermissionMethods as it, OrganizationAccount as j, TargetsMethods as jn, AddressBookMethods as jt, OrgTemplate as k, ResolvedTarget as kn, AddressBookEntry as kt, postHogObservability as l, OfframpMethods as ln, isRestoring as lr, Budget as lt, IdentityRuntimeSendResult as m, PaymentActivityEvidence as mn, CompletedPersonProfile as mt, ObservationAdapter as n, DestinationRail as nn, IdentityEvent as nr, PermissionChangeInput as nt, HostObservability as o, MeMethods as on, StateLabel as or, PermissionReplaceInput as ot, IdentityRuntime as p, Payment as pn, AccountsMethods as pt, PayrollRunItemInput as q, PAYMENT_DIRECTIONS as qn, ActivitySummaryParams as qt, ObservationContext as r, DestinationRemoveInput as rn, IdentityState as rr, PermissionCreateInput as rt, PostHogObservabilityClient as s, MeProfile as sn, destination as sr, PermissionRevokeInput as st, CAPXUL_SDK_EXPECTED_OUTCOME_EVENT as t, DestinationPayload as tn, Destination$1 as tr, PermissionAssignInput as tt, CapxulClient as u, OfframpQuote as un, IdentityTransition as ur, OrgMe as ut, SystemHealth as v, PaymentDocumentRender as vn, PersonOnboarding as vt, InviteMemberInput as w, PaymentType as wn, ActorRelationshipMethods as wt, CurrentUserMethods as x, PaymentMoney as xn, AccountMethods as xt, MediaMethods as y, PaymentDocumentVerification as yn, PersonOnboardingInput as yt, PayrollEngagementTerms as z, AuthMethods as zn, ActivityItem as zt };
+//#region src/ports/diagnostic.d.ts
+type DiagnosticDetail = Readonly<Record<string, unknown>>;
+interface DiagnosticPort {
+  readonly trace: (scope: string, detail: DiagnosticDetail) => void;
+}
+//#endregion
+//#region src/openfort/create-openfort-browser-signer.d.ts
+interface OpenfortBrowserSignerOptions {
+  readonly diagnostic?: DiagnosticPort;
+  /** Testing seam below the existing one-retry recovery owner. */
+  readonly signUserOpHash?: ((hash: Parameters<CapxulSigner["signUserOpHash"]>[0], delegate: CapxulSigner["signUserOpHash"]) => ReturnType<CapxulSigner["signUserOpHash"]>) | undefined;
+}
+//#endregion
+//#region src/production.d.ts
+/**
+ * Consumer-facing `createCapxulClient` input (SDK DX public surface · #326).
+ * The publishable key is the primary input; bootstrap host, invoke timeout,
+ * runtime detection, and auth-cache selection are SDK-owned defaults.
+ */
+interface CapxulClientInput {
+  readonly publishableKey: string;
+  /**
+   * One host-owned product/failure observability module around the host's
+   * existing analytics client. Omit for zero host observation work.
+   */
+  readonly observability?: HostObservability;
+  /**
+   * Init-time account readiness target (issue #159 · AC4). Threaded into
+   * `assembleCapxulClient` so `client.account.{getStatus,ensureReady}` reflect
+   * the consumer's chosen requirement. Optional — defaults to `"none"` (SDK
+   * publish readiness · I3) so `createCapxulClient({ publishableKey })` works
+   * with no account lane.
+   */
+  readonly requirement?: AccountRequirement;
+  /**
+   * Consumer-held signer (backend-orchestrated-deploy.md). Required for
+   * `requirement: "deployed"` flows: `provision` reads `getAddress()` and the
+   * deploy path signs the backend's SafeOp digest via `signUserOpHash()`. The
+   * backend orchestrates build + gas + paymaster + submit — the client never
+   * holds an RPC URL, a gas-sponsorship policy, or a bundler.
+   */
+  readonly signer?: CapxulSigner;
+}
+/** Per-client signing controls; only the testing entry exposes these to consumers. */
+interface ProductionSignerControls {
+  /** Final signing call. Address, readiness and session lifecycle retain their real owner. */
+  readonly signUserOpHash?: (hash: Parameters<CapxulSigner["signUserOpHash"]>[0], signer: CapxulSigner & {
+    readonly resetSession?: () => void;
+  }) => ReturnType<CapxulSigner["signUserOpHash"]>;
+  /** Embedded signing calls, including the existing recovery owner's single retry. */
+  readonly signEmbeddedUserOpHash?: OpenfortBrowserSignerOptions["signUserOpHash"];
+}
+//#endregion
+export { OrganizationPaymentBatchInput as $, RequestStatus as $n, Destination as $t, OrgScopedMethods as A, Ref$1 as An, AddressBookAddInput as At, AuthorizeRunOptions as B, SmartAccountMethods as Bn, ActivityFilter as Bt, CurrentUserMethods as C, PaymentMoney as Cn, AccountMethods as Ct, MemberStatus as D, PaymentsMethods as Dn, ActorRequest as Dt, InviteMemberInput as E, PaymentType as En, ActorRelationshipMethods as Et, ResendInviteTokenInput as F, AccountLifecycle as Fn, InboxItem as Ft, PayrollGroupsMethods as G, ActorRef as Gn, ActivityPage as Gt, PayrollGroup as H, OrgLifecycle as Hn, ActivityKind as Ht, RoleDefinition as I, AccountSetupStep as In, InboxMethods as It, PayrollRun as J, SubmittedPermissionExecution as Jn, ActivitySummary as Jt, PayrollMethods as K, CurrentHoldings as Kn, ActivityRange as Kt, RoleSpendCap as L, isSettingUpLifecycle as Ln, ActivityAnnotation as Lt, OrgView as M, TargetReference as Mn, AddressBookLabelInput as Mt, OrganizationAccount as N, TargetsMethods as Nn, AddressBookMethods as Nt, MemberView as O, PaymentsPayInput as On, ActorRequestIssueInput as Ot, OrganizationAuditLogItem as P, fingerprintPaymentIntent as Pn, InboxApproveInput as Pt, PayrollTermsUnit as Q, PaymentStatus$1 as Qn, DepositInstructions as Qt, RoleView as R, CompleteProfileInput as Rn, ActivityAnnotationInput as Rt, CurrentUserContext as S, PaymentDocumentsMethods as Sn, ReadyAccountLifecycle as St, DetectPendingOrgInvitationsResult as T, PaymentTiming as Tn, ActorProfileMethods as Tt, PayrollGroupInput as U, OrgSetupStep as Un, ActivityListParams as Ut, PayrollEngagementTerms as V, AuthMethods as Vn, ActivityItem as Vt, PayrollGroupMember as W, PayoutAddress as Wn, ActivityMethods as Wt, PayrollRunStatus as X, PAYMENT_DIRECTIONS as Xn, ActivitySummaryTotal as Xt, PayrollRunItemInput as Y, InboxStatus as Yn, ActivitySummaryParams as Yt, PayrollRuns as Z, PAYMENT_STATUSES as Zn, ActorReference as Zt, HoldingsMethods as _, PaymentDirection as _n, OnboardingMethods as _t, ObservationContext as a, DestinationRemoveInput as an, IdentityEvent as ar, PermissionCreateInput as at, SystemHealth as b, PaymentDocumentRender as bn, PersonOnboarding as bt, HostObservability as c, MeMethods as cn, Readiness as cr, PermissionReplaceInput as ct, postHogObservability as d, OfframpMethods as dn, isClaimed as dr, Budget as dt, DestinationAddInput as en, TelemetryEvent as er, OrganizationPaymentInput as et, CapxulClient as f, OfframpQuote as fn, isRestoring as fr, OrgMe as ft, IdentityRuntimeSendResult as g, PaymentActivityEvidence as gn, CompletedPersonProfile as gt, IdentityRuntime as h, Payment as hn, AccountsMethods as ht, ObservationAdapter as i, DestinationRail as in, Destination$1 as ir, PermissionChangeInput as it, OrgTemplate as j, ResolvedTarget as jn, AddressBookEntry as jt, OrgMethods as k, RecipientResolution as kn, ActorRequestsMethods as kt, PostHogObservabilityClient as l, MeProfile as ln, StateLabel as lr, PermissionRevokeInput as lt, IdentityProfileDetails as m, OfframpStatus as mn, InvocationControls as mr, OrgMeOptions as mt, ProductionSignerControls as n, DestinationListInput as nn, TelemetryIdentifyInput as nr, OrganizationPaymentsMethods as nt, ObservationDelivery as o, DestinationsMethods as on, IdentityState as or, PermissionMethods as ot, CreateCapxulClientInput as p, OfframpQuoteInput as pn, IdentityTransition as pr, OrgMeMethod as pt, PayrollOptions as q, Permission as qn, ActivityReference as qt, CAPXUL_SDK_EXPECTED_OUTCOME_EVENT as r, DestinationPayload as rn, TelemetryPort as rr, PermissionAssignInput as rt, SdkFailureObservation as s, FinancialOpsMethods as sn, OrgLane as sr, PermissionOptions as st, CapxulClientInput as t, DestinationKind as tn, TelemetryGroupInput as tr, OrganizationPaymentItemInput as tt, PostHogObservabilityOptions as u, MovementActivityEvidence as un, destination as ur, PermissionReadResult as ut, Holding as v, PaymentDocumentKind as vn, OrganizationOnboarding as vt, CreateOrgInput as w, PaymentStatus as wn, ActorProfile as wt, MediaMethods as x, PaymentDocumentVerification as xn, PersonOnboardingInput as xt, SystemMethods as y, PaymentDocumentRef as yn, OrganizationOnboardingInput as yt, AuthorizeRunInput as z, IdentityMethods as zn, ActivityDetail as zt };

package/dist/testing/index.d.mts

@@ -1,5 +1,85 @@
-import { $n as TelemetryIdentifyInput, Qn as TelemetryGroupInput, Zn as TelemetryEvent, n as ObservationAdapter, u as CapxulClient, ur as IdentityTransition } from "../observation-Bhdq9-l6.mjs";
+import { h as CapxulResult } from "../OAuthBearerAuthClient-C-ip-z8M.mjs";
+import { er as TelemetryEvent, f as CapxulClient, i as ObservationAdapter, n as ProductionSignerControls, nr as TelemetryIdentifyInput, pr as IdentityTransition, t as CapxulClientInput, tr as TelemetryGroupInput } from "../production-Du4Vc7YD.mjs";
 import { Effect, Layer } from "effect";
+//#region src/testing/production-client.d.ts
+/** Create the one production client with per-client controls at its signing boundaries. */
+declare function createCapxulProductionTestClient(input: CapxulClientInput, controls: ProductionSignerControls): Promise<CapxulResult<CapxulClient>>;
+//#endregion
+//#region src/testing/signer-faults.d.ts
+/**
+ * Which provider refusal to inject. The codes are the ones the SDK's own
+ * classifiers decode (`src/signer.ts`), so a fault reaches the public error
+ * contract through the real decode path rather than a shortcut.
+ *
+ * - `missing-signer` — Openfort's typed not-ready code. `openfortSignerNotReadyCode`
+ *   decodes it, so the production recovery wrapper runs its single retry (A02).
+ * - `user-rejected` — the EIP-1193 4001 result. `signerFailure` decodes it to
+ *   `SIGNER_REJECTED`, an expected refusal (A08).
+ * - `unexpected` — no provider code at all, so it stays an unexpected
+ *   `PROVIDER_ERROR` (A09).
+ */
+type SignerFaultKind = "missing-signer" | "user-rejected" | "unexpected";
+/** The value a controlled fault throws. Named so a test can assert its origin. */
+declare class ControlledSignerFault extends Error {
+  readonly kind: SignerFaultKind;
+  /** Provider code the SDK classifiers read; absent for `unexpected`. */
+  readonly code: string | number | undefined;
+  constructor(kind: SignerFaultKind);
+}
+/** Build one fault value without the harness, for a caller that writes its own control. */
+declare function signerFaultCause(kind: SignerFaultKind): ControlledSignerFault;
+interface SignerFaultPlan {
+  /**
+   * Fault the next embedded signature ONCE, beneath the production recovery
+   * wrapper, then delegate every later call to the real signer. The address
+   * read and the readiness cycle still run first, so the fault lands at the
+   * actual final signing boundary after the prepared-command equality checks.
+   */
+  readonly signOnce?: SignerFaultKind;
+  /**
+   * Call the production signer's own `resetSession()` ONCE, immediately before
+   * the next signature and after the command is prepared. The delegate then
+   * re-runs the real readiness cycle, so the configure request under test is
+   * the first one the browser observes after the `reset-session` record (A03).
+   *
+   * Throws when the composed signer owns no session — a silently skipped reset
+   * would leave the run looking green while proving nothing.
+   */
+  readonly resetSessionBeforeNextSign?: boolean;
+}
+/** What the seam did. JSON-serializable, so a browser test can read it back. */
+interface SignerSeamRecord {
+  readonly boundary: "reset-session" | "embedded-sign";
+  /** 1-based count of calls at that boundary. */
+  readonly attempt: number;
+  readonly hash?: string;
+  /** Present only on the call that actually threw. */
+  readonly fault?: SignerFaultKind;
+  readonly atMs: number;
+}
+interface ArmedSignerSeam {
+  /** Hand these to `createCapxulProductionTestClient`. */
+  readonly controls: ProductionSignerControls;
+  /** Oldest first. Empty until the client reaches a signing boundary. */
+  readonly records: () => readonly SignerSeamRecord[];
+  /** True once every armed one-shot has fired. */
+  readonly spent: () => boolean;
+}
+/**
+ * Arm one-shot faults on the production embedded signer.
+ *
+ * ```ts
+ * const seam = armSignerFaults({ signOnce: "user-rejected" });
+ * const client = await createCapxulProductionTestClient(input, seam.controls);
+ * const result = await client.org(orgId).permissions.create(command);
+ * // result.error.code === "SIGNER_REJECTED"; nothing was submitted.
+ * // seam.records() names the boundary that refused.
+ * ```
+ *
+ * An empty plan installs no controls, which composes the ordinary client.
+ */
+declare function armSignerFaults(plan?: SignerFaultPlan): ArmedSignerSeam;
+//#endregion
 //#region src/testing/telemetry/RecordingTelemetryAdapter.d.ts
 type RecordingTelemetryOperation = {
   readonly type: "emit";
@@ -51,4 +131,4 @@ interface CapxulTestObservation {
  */
 declare function createCapxulTestClient(options?: CreateCapxulTestClientOptions): CapxulTestClient;
 //#endregion
-export { CapxulTestClient, CapxulTestClock, CapxulTestObservation, CreateCapxulTestClientOptions, SeedTestIdentityInput, createCapxulTestClient };
+export { type ArmedSignerSeam, CapxulTestClient, CapxulTestClock, CapxulTestObservation, ControlledSignerFault, CreateCapxulTestClientOptions, type ProductionSignerControls, SeedTestIdentityInput, type SignerFaultKind, type SignerFaultPlan, type SignerSeamRecord, armSignerFaults, createCapxulProductionTestClient, createCapxulTestClient, signerFaultCause };

package/dist/testing/index.mjs

@@ -1,8 +1,105 @@
-import { M as fromWei, Z as redactTelemetryEvent, f as identityErrorFromCapxul, g as bootstrapErrorFromCapxul, i as smartAccountErrorFromCapxul, m as convexCallErrorFromCapxul, o as accountReadErrorFromCapxul, t as assembleCapxulClient, u as wireChainId, v as toWei } from "../create-capxul-client-B3ET402J.mjs";
-import { $ as CapxulError, A as toAuthUserId, B as toJwtToken, D as toAddress, E as toAccountId, F as toDurationMs, I as toEmail, J as toSessionToken, K as toPublishableKey, L as toEpochMs, M as toChainId, N as toCountryCode, O as toAllowedOrigin, R as toEpochSeconds, V as toKycTier, _ as deriveCapxulSafeAddress, k as toAppId, n as InMemoryAuthCacheAdapter, t as readClockNow, tt as Errors, u as authClientPortFromPromiseAdapter, v as validateHandle, z as toHandle } from "../clock-C2AUlq1V.mjs";
-import { Effect, Result, Semaphore } from "effect";
+import { D as fromWei, P as redactTelemetryEvent, a as smartAccountErrorFromCapxul, c as identityErrorFromCapxul, i as assembleCapxulClient, l as convexCallErrorFromCapxul, n as createCapxulClientWithSignerControls, o as accountReadErrorFromCapxul, s as wireChainId, u as bootstrapErrorFromCapxul, v as toWei } from "../production-BndbwuVx.mjs";
+import { G as toHandle, H as toEmail, I as toAuthUserId, K as toJwtToken, M as toAddress, N as toAllowedOrigin, P as toAppId, Q as toPublishableKey, R as toChainId, U as toEpochMs, V as toDurationMs, W as toEpochSeconds, d as authClientPortFromPromiseAdapter, et as toSessionToken, j as toAccountId, lt as Errors, n as readClockNow, q as toKycTier, r as InMemoryAuthCacheAdapter, rt as validateHandle, st as CapxulError, y as deriveCapxulSafeAddress, z as toCountryCode } from "../OAuthBearerAuthClient-IB2W1Fzj.mjs";
 import { keccak256 } from "viem";
+import { Effect, Result, Semaphore } from "effect";
 import { getFunctionName } from "convex/server";
+//#region src/testing/production-client.ts
+/** Create the one production client with per-client controls at its signing boundaries. */
+function createCapxulProductionTestClient(input, controls) {
+	return createCapxulClientWithSignerControls(input, controls);
+}
+//#endregion
+//#region src/testing/signer-faults.ts
+const FAULT_CODES = {
+	"missing-signer": "MISSING_SIGNER",
+	"user-rejected": 4001,
+	unexpected: void 0
+};
+/** The value a controlled fault throws. Named so a test can assert its origin. */
+var ControlledSignerFault = class extends Error {
+	kind;
+	/** Provider code the SDK classifiers read; absent for `unexpected`. */
+	code;
+	constructor(kind) {
+		super(`controlled signer fault (${kind})`);
+		this.name = "ControlledSignerFault";
+		this.kind = kind;
+		this.code = FAULT_CODES[kind];
+	}
+};
+/** Build one fault value without the harness, for a caller that writes its own control. */
+function signerFaultCause(kind) {
+	return new ControlledSignerFault(kind);
+}
+/**
+* Arm one-shot faults on the production embedded signer.
+*
+* ```ts
+* const seam = armSignerFaults({ signOnce: "user-rejected" });
+* const client = await createCapxulProductionTestClient(input, seam.controls);
+* const result = await client.org(orgId).permissions.create(command);
+* // result.error.code === "SIGNER_REJECTED"; nothing was submitted.
+* // seam.records() names the boundary that refused.
+* ```
+*
+* An empty plan installs no controls, which composes the ordinary client.
+*/
+function armSignerFaults(plan = {}) {
+	const records = [];
+	let pendingFault = plan.signOnce;
+	let pendingReset = plan.resetSessionBeforeNextSign === true;
+	let resetCalls = 0;
+	let embeddedCalls = 0;
+	function record(entry) {
+		records.push({
+			...entry,
+			atMs: Date.now()
+		});
+	}
+	const resetThenSign = async (hash, signer) => {
+		if (pendingReset) {
+			pendingReset = false;
+			resetCalls += 1;
+			if (signer.resetSession === void 0) throw new Error("armSignerFaults: resetSessionBeforeNextSign needs the embedded browser signer; this client composed a signer with no session");
+			signer.resetSession();
+			record({
+				boundary: "reset-session",
+				attempt: resetCalls,
+				hash
+			});
+		}
+		return signer.signUserOpHash(hash);
+	};
+	const faultThenDelegate = async (hash, delegate) => {
+		embeddedCalls += 1;
+		const fault = pendingFault;
+		if (fault === void 0) {
+			record({
+				boundary: "embedded-sign",
+				attempt: embeddedCalls,
+				hash
+			});
+			return delegate(hash);
+		}
+		pendingFault = void 0;
+		record({
+			boundary: "embedded-sign",
+			attempt: embeddedCalls,
+			hash,
+			fault
+		});
+		throw signerFaultCause(fault);
+	};
+	return {
+		controls: {
+			...plan.resetSessionBeforeNextSign === true ? { signUserOpHash: resetThenSign } : {},
+			...plan.signOnce === void 0 ? {} : { signEmbeddedUserOpHash: faultThenDelegate }
+		},
+		records: () => records.slice(),
+		spent: () => pendingFault === void 0 && !pendingReset
+	};
+}
+//#endregion
 //#region src/testing/account/InMemoryAccountReadAdapter.ts
 var InMemoryAccountReadAdapter = class {
 	#deps;
@@ -909,4 +1006,4 @@ function createCapxulTestClient(options = {}) {
 	};
 }
 //#endregion
-export { createCapxulTestClient };
+export { ControlledSignerFault, armSignerFaults, createCapxulProductionTestClient, createCapxulTestClient, signerFaultCause };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk",
-  "version": "4.1.4",
+  "version": "4.2.0-rc.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -48,11 +48,11 @@
     "vite-plus": "0.3.0",
     "vitest": "4.1.11",
     "@capxul/errors": "0.3.0",
-    "@capxul/observability": "4.1.4",
-    "@capxul/types": "0.3.0",
-    "@capxul/config": "0.3.0",
     "@capxul/typescript-config": "0.0.0",
-    "@capxul/wire": "0.7.0"
+    "@capxul/observability": "4.2.0-rc.10",
+    "@capxul/wire": "0.7.0",
+    "@capxul/types": "0.3.0",
+    "@capxul/config": "0.3.0"
   },
   "_permissionlessPinReason": "permissionless.toSafeSmartAccount is pinned to 0.3.4 for live Safe deployment E2E. Counterfactual address fixtures captured 2026-05-17 in packages/backend/convex/_shared/__tests__/counterfactual.test.ts and packages/config/tests/safe.test.ts must be re-verified before upgrading.",
   "scripts": {