@bounded-sh/core 0.0.65 → 0.0.67

package/dist/types.d.ts

@@ -23,6 +23,18 @@ export interface AuthProvider {
     restoreSession(): Promise<User | null>;
     logout(): Promise<void>;
     getNativeMethods(): Promise<any>;
+    /**
+     * Poll an already-broadcast EVM transaction through THIS provider's own
+     * transport, so `reconcileSetResult` never has to guess an RPC endpoint or
+     * cross wallet identities. Optional: a provider that cannot submit EVM
+     * transactions has nothing to reconcile, and a `submitted` receipt simply
+     * stays `submitted`.
+     *
+     * It must NEVER build a fresh transaction. It may rebroadcast the
+     * byte-identical fenced bytes only when `allowRebroadcast` is true and the
+     * fenced nonce is still unused.
+     */
+    reconcileEvmTransaction?(request: EvmReconcileRequest): Promise<TransactionReconciliation>;
 }
 export interface User {
     /**
@@ -103,13 +115,367 @@ export interface SolTransaction {
     /** Base64-encoded VersionedTransaction prebuilt server-side for sponsorship and/or required co-signers. */
     signedTransaction?: string;
 }
-export interface TransactionResult {
-    transactionSignature?: any;
-    signedTransaction?: any;
+/**
+ * Execution-lane tag for a Solana write. Reported verbatim by the realtime
+ * worker on its 202; the SDK never infers it from the app protocol.
+ */
+export type SolanaChainTag = 'solana_devnet' | 'solana_mainnet';
+/**
+ * Execution-lane tag for an EVM write, reported verbatim by the realtime worker
+ * as the resolved EVM NETWORK key (protocol tier × chain), e.g. `base_sepolia`
+ * on a testnet-tier app and `base_mainnet` on a mainnet-tier one. The
+ * `evm_<chain>` form is the worker's fallback when a network cannot be resolved.
+ *
+ * The SDK never derives this from `evmTransaction.chainId`: a receipt states
+ * where the write actually ran, and only the worker knows that.
+ */
+export type EvmChainTag = 'base_sepolia' | 'base_mainnet' | 'robinhood_testnet' | 'robinhood_mainnet' | 'eth_sepolia' | 'eth_mainnet' | `evm_${string}`;
+/**
+ * The execution lane a write actually ran on — NOT the app's declared protocol.
+ * Routing is per batch, so a batch touching only unflagged collections in a
+ * `realtime_devnet` app commits directly offchain and reports the offchain lane.
+ * Mirrors the CLI's `Chain` field ("reports which path ran").
+ *
+ * `'unknown'` is never a lane the platform runs; it appears only when a worker
+ * predating the batch-receipt contract returned a direct commit with no lane at
+ * all. Discarding a committed write's receipt over a missing tag would be worse
+ * than reporting the gap honestly.
+ */
+export type ChainTag = SolanaChainTag | EvmChainTag | 'realtime_offchain' | 'unknown' | (string & {});
+/**
+ * One requested write, keyed by its CONCRETE destination path (never by index).
+ * A `null` document means the entry was deleted or is absent.
+ *
+ * Positional correlation is provably wrong for Bounded writes: the worker
+ * processes deletes before upserts and returns the deleted document's PREVIOUS
+ * value, a missing delete and a passthrough write emit no result entry at all,
+ * and hooks run after the result array is captured. Only the path correlates.
+ */
+export type SetEntry = {
+    path: string;
+    document: Record<string, unknown> | null;
+};
+export type SetDocuments = SetEntry[];
+/** Solana expiry fence from the worker's 202, used for same-signature reconciliation. */
+export type SolanaFence = {
+    blockhash: string;
+    lastValidBlockHeight: number;
+};
+/**
+ * EVM fence for a SERVER-KEYPAIR write: the exact signed bytes plus the sender
+ * and nonce they consume. Reconciliation may rebroadcast these identical bytes
+ * while the nonce is still unused, which cannot produce a second execution.
+ * Injected browser wallets never produce one (the wallet holds the signed bytes).
+ */
+export type EvmFence = {
+    chainId: number;
+    sender: string;
+    nonce: number;
+    signedTransaction: string;
+};
+/**
+ * Whether server state was actually observed after a write.
+ *
+ * A successful sync HTTP call is NOT evidence of synchronization: the sync
+ * endpoint returns `null` for a document that is absent, lagging, or
+ * read-denied. `observed: true` requires every requested path to have been read
+ * back and validated; anything else reports `observed: false` with a reason.
+ */
+export type MirrorSync = {
+    observed: true;
+    documents: SetDocuments;
+} | {
+    observed: false;
+    reason: string;
+};
+/** The write committed directly on the worker (no client-signed transaction). */
+export type CommittedSetResult = {
+    status: 'committed';
+    /** The caller's own proposed writes — an echo, never authoritative state. */
+    requestedDocuments: SetDocuments;
+    /** Post-hook server state, when the worker reported it per concrete path. */
+    observation: MirrorSync;
+    chain: ChainTag;
+    /** The batch's own transaction id, verbatim from the worker receipt. Never lifted from a result document. */
+    transactionId: string | null;
+};
+/** A Solana transaction that confirmed on-chain without error. */
+export type SolanaConfirmedSetResult = {
+    status: 'confirmed';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: SolanaChainTag;
+    transactionId: string;
+    signedTransaction: string;
+    fence: SolanaFence;
+    /**
+     * The RPC response context slot observed at confirmation — deliberately NOT
+     * called `slot`. It is not the slot the transaction landed in; polling the
+     * mirror for a `_block_number` matching it would never succeed.
+     */
+    confirmationContextSlot: number;
+    mirrorSync: MirrorSync;
+};
+/** An EVM transaction whose receipt reported success. */
+export type EvmConfirmedSetResult = {
+    status: 'confirmed';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: EvmChainTag;
+    transactionId: string;
+    /** A real EVM block number. */
+    blockNumber: number;
+    mirrorSync: MirrorSync;
+};
+export type ConfirmedSetResult = SolanaConfirmedSetResult | EvmConfirmedSetResult;
+/**
+ * Solana broadcast whose confirmation outcome is unknown. The signature is
+ * derived from the signed bytes BEFORE broadcast, so it survives a lost send
+ * response. Never auto-resubmit — reconcile this same signature instead.
+ */
+export type SolanaSubmittedSetResult = {
+    status: 'submitted';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: SolanaChainTag;
+    transactionId: string;
+    signedTransaction: string;
+    fence: SolanaFence;
+    confirmation: {
+        state: 'unknown';
+        reason: string;
+    };
+};
+/**
+ * Server-keypair EVM broadcast with an unknown outcome. Fenced, so
+ * reconciliation may rebroadcast the byte-identical signed transaction while
+ * the nonce is unused. There is deliberately NO retry-safe terminal state here.
+ */
+export type EvmFencedSubmittedSetResult = {
+    status: 'submitted';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: EvmChainTag;
+    transactionId: string;
+    fence: EvmFence;
+    confirmation: {
+        state: 'unknown';
+        reason: string;
+    };
+};
+/**
+ * Injected-wallet EVM broadcast whose hash IS known (eth_sendTransaction
+ * returned before receipt polling timed out). Pollable, never rebroadcastable:
+ * the signed bytes live inside the wallet.
+ */
+export type EvmHashKnownSubmittedSetResult = {
+    status: 'submitted';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: EvmChainTag;
+    transactionId: string;
+    rebroadcastable: false;
+    confirmation: {
+        state: 'unknown';
+        reason: string;
+    };
+};
+/**
+ * Injected-wallet EVM send whose RESPONSE was lost, so no hash exists at all.
+ * Explicitly irreconcilable and never auto-retried: the wallet owns nonce
+ * selection and may have replaced the transaction outside our view.
+ */
+export type EvmIrreconcilableSubmittedSetResult = {
+    status: 'submitted';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: EvmChainTag;
+    transactionId: null;
+    confirmation: {
+        state: 'unknown';
+        reason: string;
+        reconcilable: false;
+    };
+};
+export type SubmittedSetResult = SolanaSubmittedSetResult | EvmFencedSubmittedSetResult | EvmHashKnownSubmittedSetResult | EvmIrreconcilableSubmittedSetResult;
+/**
+ * The one retry-safe terminal state: the write provably did NOT land. Reached
+ * only after observed blockhash expiry PLUS history proving the signature is
+ * absent. Solana only — nonce advancement is not proof an EVM write did not
+ * execute, so EVM has no equivalent by design.
+ */
+export type SolanaExpiredNotLandedSetResult = {
+    status: 'expired_not_landed';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: SolanaChainTag;
+    transactionId: string;
+    fence: SolanaFence;
+};
+/**
+ * `shouldSubmitTx: false`: the transaction was signed and NOT sent. There is no
+ * signature to report and nothing to mirror, so `transactionId` is `null` (not
+ * an empty string) and no synchronization is attempted. Solana only — the EVM
+ * providers sign and submit atomically.
+ */
+export type SolanaSignedSetResult = {
+    status: 'signed';
+    appId: string;
+    requestedDocuments: SetDocuments;
+    chain: SolanaChainTag;
+    transactionId: null;
+    signedTransaction: string;
+    fence: SolanaFence;
+};
+/**
+ * What every Bounded write resolves to. Discriminate on `status` first.
+ *
+ * NOTE ON DELIVERY: this is not exactly-once delivery. A direct write commits
+ * and runs hooks before its HTTP response is produced, so a LOST response to a
+ * direct write is ambiguous. The SDK never retries writes for that reason;
+ * resolve an ambiguous direct write by reading the path back, not by resubmitting.
+ */
+export type SetResult = CommittedSetResult | SolanaConfirmedSetResult | EvmConfirmedSetResult | SolanaSubmittedSetResult | EvmFencedSubmittedSetResult | EvmHashKnownSubmittedSetResult | EvmIrreconcilableSubmittedSetResult | SolanaExpiredNotLandedSetResult | SolanaSignedSetResult;
+/**
+ * What `AuthProvider.runTransaction` (and the Solana pre-built lane) resolves
+ * to. Discriminated so the identifier ESCAPES an unknown confirmation outcome:
+ * previously every lane awaited a receipt and threw on timeout, so a landed
+ * transaction surfaced as an error with no hash and invited a duplicate submit.
+ *
+ * Definitive failures — an EIP-1193 user rejection, pre-broadcast validation,
+ * or an on-chain revert/err — still THROW. Only an ambiguous transport outcome
+ * resolves as `submitted`.
+ */
+export type SolanaConfirmedTransactionResult = {
+    outcome: 'confirmed';
+    lane: 'solana';
+    transactionSignature: string;
+    /** Base64 signed transaction bytes. */
+    signedTransaction: string;
+    fence: SolanaFence;
+    /** RPC response context slot at confirmation, NOT the landing slot. */
+    confirmationContextSlot: number;
+};
+export type SolanaSubmittedTransactionResult = {
+    outcome: 'submitted';
+    lane: 'solana';
+    /** Derived from the signed bytes before broadcast, so a lost send cannot orphan it. */
+    transactionSignature: string;
+    signedTransaction: string;
+    fence: SolanaFence;
+    reason: string;
+};
+export type SolanaSignedTransactionResult = {
+    outcome: 'signed';
+    lane: 'solana';
+    transactionSignature: null;
+    signedTransaction: string;
+    fence: SolanaFence;
+};
+export type EvmConfirmedTransactionResult = {
+    outcome: 'confirmed';
+    lane: 'evm';
+    transactionSignature: string;
     blockNumber: number;
     gasUsed: string;
-    data?: any;
+    data?: unknown;
+};
+/** Server-keypair EVM: fenced, so the identical bytes may be rebroadcast. */
+export type EvmFencedSubmittedTransactionResult = {
+    outcome: 'submitted';
+    lane: 'evm';
+    transactionSignature: string;
+    fence: EvmFence;
+    reason: string;
+};
+/** Injected wallet, hash known: pollable, never rebroadcastable. */
+export type EvmHashKnownSubmittedTransactionResult = {
+    outcome: 'submitted';
+    lane: 'evm';
+    transactionSignature: string;
+    rebroadcastable: false;
+    reason: string;
+};
+/** Injected wallet, send response lost: no hash at all. */
+export type EvmIrreconcilableSubmittedTransactionResult = {
+    outcome: 'submitted';
+    lane: 'evm';
+    transactionSignature: null;
+    reconcilable: false;
+    reason: string;
+};
+export type SolanaTransactionResult = SolanaConfirmedTransactionResult | SolanaSubmittedTransactionResult | SolanaSignedTransactionResult;
+export type EvmTransactionResult = EvmConfirmedTransactionResult | EvmFencedSubmittedTransactionResult | EvmHashKnownSubmittedTransactionResult | EvmIrreconcilableSubmittedTransactionResult;
+export type TransactionResult = SolanaTransactionResult | EvmTransactionResult;
+/**
+ * The result of polling an already-broadcast transaction. Providers implement
+ * `reconcileEvmTransaction` to answer it for their own transport; Solana is
+ * reconciled by core against the configured RPC.
+ */
+export type TransactionReconciliation = 
+/** A receipt/status exists and reports success. */
+{
+    state: 'confirmed';
+    blockNumber?: number;
+    confirmationContextSlot?: number;
+}
+/** It landed and FAILED on-chain. The caller throws; this is not `submitted`. */
+ | {
+    state: 'failed';
+    reason: string;
+}
+/** Solana only: expiry observed AND history proves the signature is absent. */
+ | {
+    state: 'absent_after_expiry';
 }
+/** Nothing conclusive. Stays `submitted`. */
+ | {
+    state: 'unknown';
+    reason: string;
+};
+/**
+ * The Solana RPC surface the write + reconciliation lanes use. A real
+ * `Connection` satisfies it structurally; tests inject a double through
+ * `_overrides._solanaRpc` so the send-loss / confirm-timeout / exactly-one-
+ * broadcast / expiry paths are exercised without a validator.
+ */
+export interface SolanaWriteRpc {
+    sendRawTransaction(rawTransaction: Uint8Array, options?: {
+        skipPreflight?: boolean;
+        maxRetries?: number;
+    }): Promise<string>;
+    confirmTransaction(strategy: {
+        signature: string;
+        blockhash: string;
+        lastValidBlockHeight: number;
+    }, commitment?: any): Promise<{
+        value?: {
+            err?: unknown;
+        } | null;
+        context?: {
+            slot?: number;
+        };
+    }>;
+    getTransaction(signature: string, options?: any): Promise<any>;
+    getSignatureStatuses?(signatures: string[], config?: any): Promise<{
+        value?: Array<any>;
+        context?: {
+            slot?: number;
+        };
+    }>;
+    getBlockHeight?(commitment?: any): Promise<number>;
+}
+/** Request passed to a provider's `reconcileEvmTransaction`. */
+export type EvmReconcileRequest = {
+    transactionHash: string;
+    /** Present only for the fenced (server-keypair) receipt. */
+    fence?: EvmFence;
+    /**
+     * Whether the caller permits a byte-identical rebroadcast of `fence`'s signed
+     * transaction while its nonce is unused. Always false for injected wallets.
+     */
+    allowRebroadcast: boolean;
+};
 export interface TransactionReceipt {
 }
 export interface SubscriptionOptions {

package/dist/utils/core-platform.d.ts

@@ -6,6 +6,13 @@
  *
  * These are used instead of bare `atob()`/`btoa()` so the core package
  * works in React Native without requiring the consumer to polyfill globals.
+ *
+ * Both directions are UTF-8-safe: bare btoa / Buffer('binary') are LATIN-1 and
+ * throw (surrogate-pair emoji) or silently mangle (accents, CJK) any code point
+ * > 0xFF, corrupting user text - e.g. an AI-query `prompt` - before it is sent.
+ * safeBtoa base64s the UTF-8 bytes; safeAtob is its exact inverse, and the
+ * realtime worker decodes the same bytes as UTF-8 (src/utf8-base64.ts). ASCII is
+ * byte-identical either way, so JWT (decodeBase64Url) decoding is unaffected.
  */
 export declare function safeAtob(input: string): string;
 export declare function safeBtoa(input: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bounded-sh/core",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "description": "Shared client, data-plane, and transport primitives for Bounded, the full-stack app builder and runtime for AI-built apps: policy-enforced operations, files, functions, and realtime.",
   "homepage": "https://bounded.sh/docs/sdk",
   "main": "./dist/index.js",
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "rm -rf ./dist ./.rollup-tmp && tsc -p tsconfig.build.json --outDir .rollup-tmp --declarationDir .rollup-tmp --emitDeclarationOnly false && rollup -c && tsc -p tsconfig.build.json --emitDeclarationOnly --declarationDir dist && rm -rf ./.rollup-tmp",
     "watch": "rollup -c -w",
-    "test": "node src/client/run-config-network-test.mjs && node src/client/run-read-principal-test.mjs && node src/client/run-principal-collision-test.mjs && node src/client/run-abortable-read-test.mjs && node src/utils/run-api-abort-test.mjs && node src/utils/run-api-transient-get-retry-test.mjs && node src/utils/run-auth-api-issuer-switch-test.mjs && node src/utils/run-auth-api-server-credential-test.mjs && node src/utils/run-session-manager-binding-test.mjs && node src/utils/rn-session-manager-example.source.test.mjs && node src/utils/run-session-protocol-test.mjs && node src/utils/run-auth-token-freshness-test.mjs && node src/utils/run-api-401-recovery-test.mjs && node src/utils/run-server-session-manager-test.mjs && node src/utils/api-refresh-inflight-key.source.test.mjs && node src/client/run-row-shape-test.mjs && node src/client/run-transport-test.mjs && node src/client/run-queries-coalesce-test.mjs && node src/client/run-runexpression-overrides-test.mjs && node src/client/run-subscribe-query-test.mjs && node src/client/subscribe-query-defaults.source.test.mjs && node src/client/run-public-export-surface-test.mjs && node src/client/run-live-auth-test.mjs && node src/client/run-live-view-principal-test.mjs && node src/client/run-subscription-auth-error-test.mjs && node src/client/run-subscription-confirmation-retry-test.mjs && node src/client/subscription-handoff-grace.source.test.mjs && node src/client/run-onchain-validation-test.mjs && node src/client/run-evm-dispatch-test.mjs && node src/utils/evm/run-evm-utils-test.mjs && node src/client/websocket-auth-url.test.mjs && node src/client/run-create-client-http-test.mjs && node src/client/run-create-client-subscribe-test.mjs && node src/client/run-wallet-config-binding-test.mjs",
+    "test": "node src/client/run-config-network-test.mjs && node src/client/run-read-principal-test.mjs && node src/client/run-principal-collision-test.mjs && node src/client/run-abortable-read-test.mjs && node src/utils/run-api-abort-test.mjs && node src/utils/run-api-transient-get-retry-test.mjs && node src/utils/run-auth-api-issuer-switch-test.mjs && node src/utils/run-auth-api-server-credential-test.mjs && node src/utils/run-session-manager-binding-test.mjs && node src/utils/run-web-session-manager-signout-test.mjs && node src/utils/run-auth-api-refresh-per-token-test.mjs && node src/utils/run-core-platform-encode-test.mjs && node src/utils/rn-session-manager-example.source.test.mjs && node src/utils/run-session-protocol-test.mjs && node src/utils/run-auth-token-freshness-test.mjs && node src/utils/run-api-401-recovery-test.mjs && node src/utils/run-server-session-manager-test.mjs && node src/utils/api-refresh-inflight-key.source.test.mjs && node src/client/run-row-shape-test.mjs && node src/client/run-transport-test.mjs && node src/client/run-queries-coalesce-test.mjs && node src/client/run-runexpression-overrides-test.mjs && node src/client/run-subscribe-query-test.mjs && node src/client/subscribe-query-defaults.source.test.mjs && node src/client/run-public-export-surface-test.mjs && node src/client/run-decline-cause-test.mjs && node src/client/run-live-auth-test.mjs && node src/client/run-live-view-principal-test.mjs && node src/client/run-subscription-auth-error-test.mjs && node src/client/run-subscription-confirmation-retry-test.mjs && node src/client/subscription-handoff-grace.source.test.mjs && node src/client/run-onchain-validation-test.mjs && node src/client/run-evm-dispatch-test.mjs && node src/client/run-set-result-test.mjs && node src/client/run-reconcile-set-result-test.mjs && node src/client/run-set-file-result-test.mjs && node src/client/run-set-result-types-test.mjs && node src/utils/evm/run-evm-utils-test.mjs && node src/client/websocket-auth-url.test.mjs && node src/client/run-create-client-http-test.mjs && node src/client/run-create-client-subscribe-test.mjs && node src/client/run-wallet-config-binding-test.mjs",
     "prepare": "npm run build"
   },
   "files": [