@bounded-sh/core 0.0.64 → 0.0.66

package/dist/client/decline.d.ts

@@ -7,6 +7,8 @@ export type DeclineReason = 'rule' | 'invariant';
 export interface DeclineBoundary {
     type: string;
     field?: string;
+    /** Stable reason when one boundary type has multiple rejection modes. */
+    cause?: 'cap_exceeded' | 'append_only_update' | 'append_only_delete';
     cap?: number;
     windowSeconds?: number;
     current?: number;

package/dist/client/functions.d.ts

@@ -1,3 +1,4 @@
+import { type ClientConfig } from './config';
 export type InvokeOptions = {
     /** Per-call timeout (ms) for the HTTP request to the dispatcher. */
     timeoutMs?: number;
@@ -10,6 +11,13 @@ export type InvokeOptions = {
      */
     _overrides?: {
         _getAuthHeaders?: () => Promise<Record<string, string>>;
+        /**
+         * @internal Fully-resolved config snapshot for a server `WalletClient`. When
+         * present, the invoke targets THIS config's dispatcher (functionsUrl) + appId
+         * instead of the mutable process-global `init()` config - so a later global
+         * init() can never retarget the wallet client's function calls (CTA-05).
+         */
+        _config?: ClientConfig;
     };
 };
 export declare class FunctionInvokeError extends Error {

package/dist/client/live-effects.d.ts

@@ -83,11 +83,13 @@ export interface LiveIntent {
 }
 /**
  * The tick may return the bare next state, OR `{ state, effects }` to also emit
- * effects this tick. Use {@link withEffects} to build the wrapper unambiguously.
+ * effects this tick. Use {@link withEffects} to build the wrapper: `effects` is
+ * required, because it is the marker the runtime recognizes the wrapper by (a bare
+ * state that merely has a `state` field must never be unwrapped).
  */
 export type LiveTickResult<S> = S | {
     state: S;
-    effects?: Effect[];
+    effects: Effect[];
 };
 /** A Bounded live module (game/realtime-room logic) that can emit effects. */
 export interface LiveModule<S = unknown> {

package/dist/client/operations.d.ts

@@ -1,4 +1,4 @@
-import type { AuthProvider } from '../types';
+import type { AuthProvider, MirrorSync, SetResult, SolanaWriteRpc } from '../types';
 import { type ClientConfig } from './config';
 import type { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
 import { type EvmTransactionPolicy } from '../utils/evm/evm-transaction-validation';
@@ -27,6 +27,12 @@ export type RequestOverrides = {
      * shared read cache. Threaded internally by the scoped read-only client.
      */
     _readOnly?: boolean;
+    /**
+     * @internal Solana RPC seam for the write + reconciliation lanes. Supplied by
+     * tests so send-loss, confirmation-timeout and expiry paths are exercised
+     * deterministically; production builds a `Connection` from `config.rpcUrl`.
+     */
+    _solanaRpc?: SolanaWriteRpc;
 };
 export type SetOptions = {
     shouldSubmitTx?: boolean;
@@ -257,18 +263,42 @@ export declare function runExpressionMany(many: {
     returnType?: 'Bool' | 'String' | 'Int' | 'UInt';
     _overrides?: RequestOverrides;
 }[]): Promise<RunExpressionResult[]>;
+/**
+ * Best-effort mirror read. A confirmed transaction must NEVER be lost to a
+ * synchronization failure, so this reports its outcome in `mirrorSync` and
+ * never rejects. It reads the CONCRETE destination paths, so a collection
+ * insert with a generated id syncs the path that actually exists.
+ */
+export declare function attemptMirrorSync(paths: string[], options?: SetOptions, settleMs?: number): Promise<MirrorSync>;
 /**
  * Write a document at `path`. Sugar for a one-element {@link setMany}.
  *
  * **Delete:** pass `null` as the document to delete it — `set(path, null)` is
  * the delete (there is no separate `del`/`remove`). It is routed through the
- * collection's policy `delete` rule and broadcasts a delete to subscribers.
+ * collection's policy `delete` rule and broadcasts a delete to subscribers, and
+ * the deleted entry surfaces as a `null` document under its path.
+ *
+ * Resolves to a discriminated {@link SetResult}; discriminate on `status`.
+ */
+export declare function set(path: string, document: any, options?: SetOptions): Promise<SetResult>;
+/**
+ * Atomically write (or delete, with a `null` document) a batch of documents.
+ *
+ * Resolves to a discriminated {@link SetResult}:
+ * - `committed` — the worker applied the batch directly.
+ * - `confirmed` — a client-signed chain transaction landed successfully.
+ * - `submitted` — broadcast happened but the outcome is unknown. NEVER
+ *   resubmit; call `reconcileSetResult`/`waitForSetResult` on the receipt.
+ * - `expired_not_landed` — Solana only, and the one retry-safe terminal state.
+ * - `signed` — `shouldSubmitTx: false`; signed and deliberately not sent.
+ *
+ * `requestedDocuments` is always the caller's own echo; authoritative server
+ * state appears only under `observation`/`mirrorSync` once actually observed.
  */
-export declare function set(path: string, document: any, options?: SetOptions): Promise<any>;
 export declare function setMany(many: {
     path: string;
     document: any;
-}[], options?: SetOptions): Promise<any>;
+}[], options?: SetOptions): Promise<SetResult>;
 export declare function clearCache(path?: string, opts?: {
     prompt?: string;
 }): void;
@@ -284,10 +314,65 @@ export declare function clearReadCacheForAuthChange(): void;
 export declare function getFiles(path: string, options?: {
     _overrides?: RequestOverrides;
 }): Promise<any>;
+/**
+ * The result of a `setFile` UPLOAD.
+ *
+ * The two uncertain states are deliberately different words, because they have
+ * opposite consequences:
+ * - `visibility: 'unknown'` — the object DEFINITELY committed; only the
+ *   anonymous-read evaluation failed. Never re-upload it.
+ * - `status: 'unknown'` — the PUT's transport outcome is ambiguous, so the
+ *   object may or may not exist. It carries the concrete path retained from
+ *   `/storage/url` and is explicitly NOT retry-safe: the one-time upload nonce
+ *   is consumed before staging, and re-calling `setFile` on a COLLECTION path
+ *   would mint a second path and orphan the first object while still billing
+ *   for it. Resolve it out of band rather than by re-uploading.
+ */
+export type FileUploadResult = {
+    status: 'uploaded';
+    /** The worker's concrete path (a collection upload's id is generated server-side). */
+    path: string;
+    /**
+     * Durable public URL, or `null` when the collection's read rule does not
+     * admit anonymous readers. A non-null URL stays valid only while that read
+     * rule keeps admitting anonymous readers — the URL is re-evaluated on every
+     * GET, so tightening the rule revokes it.
+     */
+    url: string | null;
+    visibility: 'public' | 'private' | 'unknown';
+} | {
+    status: 'unknown';
+    path: string;
+    reason: string;
+    retrySafe: false;
+};
+/**
+ * The result of a `setFile` DELETION — a distinct shape, because a delete has
+ * no URL and no visibility. The worker answers 404 when no file exists at the
+ * path and the shared request layer normalizes that into a non-throwing
+ * response, so an unconditional `deleted: true` would report a deletion that
+ * never happened.
+ */
+export type FileDeleteResult = {
+    path: string;
+    deleted: true;
+} | {
+    path: string;
+    deleted: false;
+    alreadyAbsent: true;
+};
+export declare function setFile(path: string, file: File, options?: {
+    _overrides?: RequestOverrides;
+    metadata?: Record<string, any>;
+}): Promise<FileUploadResult>;
+export declare function setFile(path: string, file: null, options?: {
+    _overrides?: RequestOverrides;
+    metadata?: Record<string, any>;
+}): Promise<FileDeleteResult>;
 export declare function setFile(path: string, file: File | null, options?: {
     _overrides?: RequestOverrides;
     metadata?: Record<string, any>;
-}): Promise<boolean>;
+}): Promise<FileUploadResult | FileDeleteResult>;
 export declare function signMessage(message: string): Promise<string>;
 export declare function signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
 export declare function signAndSubmitTransaction(transaction: Transaction | VersionedTransaction, feePayer?: PublicKey): Promise<string>;

package/dist/client/reconcile.d.ts

@@ -0,0 +1,51 @@
+import type { RequestOverrides } from './operations';
+import type { SetResult } from '../types';
+export type ReconcileSetResultOptions = {
+    /**
+     * The same per-request overrides `set` accepts. Supply `_config`/`authProvider`
+     * so a receipt minted by a server `WalletClient` reconciles through THAT
+     * client's app binding and provider rather than the process-global one.
+     */
+    _overrides?: RequestOverrides;
+    /**
+     * Whether a server-keypair EVM receipt may rebroadcast its byte-identical
+     * fenced transaction while the nonce is unused. Defaults to `true`. It is
+     * always refused for an injected-wallet receipt, whose signed bytes live
+     * inside the wallet.
+     */
+    allowRebroadcast?: boolean;
+};
+export type WaitForSetResultOptions = ReconcileSetResultOptions & {
+    /** Total wall-clock bound. Default 60s. */
+    timeoutMs?: number;
+    /** Maximum reconciliation attempts. Default 20. */
+    maxAttempts?: number;
+    /** Delay between attempts. Default 3s. */
+    pollIntervalMs?: number;
+    /** Minimum spacing between permitted rebroadcasts. Default 15s. */
+    minRebroadcastIntervalMs?: number;
+    /** Cancels the wait. The latest `submitted` receipt is returned, never discarded. */
+    signal?: AbortSignal;
+};
+/**
+ * Poll the SAME signature/hash a `submitted` receipt carries and return the
+ * resulting `SetResult`.
+ *
+ * - Terminal receipts (`committed`, `confirmed`, `expired_not_landed`,
+ *   `signed`) are returned unchanged; nothing was left open.
+ * - An irreconcilable injected-wallet receipt (`transactionId: null`) is
+ *   rejected immediately: no identifier exists to poll.
+ * - A transaction that landed and FAILED throws, exactly as it would have on
+ *   the original write.
+ */
+export declare function reconcileSetResult(receipt: SetResult, options?: ReconcileSetResultOptions): Promise<SetResult>;
+/**
+ * Reconcile repeatedly until the receipt leaves `submitted` or the bound is hit.
+ *
+ * The bound is mandatory, because some states are permanently non-terminal by
+ * design: an unidentified nonce consumer or a permanently underpriced EVM
+ * transaction never resolves. On exhaustion (or abort) this returns the LATEST
+ * `submitted` receipt with its identifier intact rather than hanging or
+ * throwing the identifier away.
+ */
+export declare function waitForSetResult(receipt: SetResult, options?: WaitForSetResultOptions): Promise<SetResult>;

package/dist/client/solana-operations.d.ts

@@ -1,9 +1,19 @@
-import type { AuthProvider, TransactionResult } from '../types';
+import type { VersionedTransaction } from '@solana/web3.js';
+import type { AuthProvider, SolanaTransactionResult } from '../types';
 import type { SetOptions } from './operations';
-export declare function handleSolanaTransaction(tx: any, authProvider: AuthProvider, options: SetOptions | undefined, expectedWritePaths: string[]): Promise<TransactionResult>;
+/**
+ * Derive the transaction signature from the SIGNED bytes, before broadcasting.
+ *
+ * Without this the signature is only learned when `sendRawTransaction` resolves,
+ * so an RPC that accepted the bytes but whose response was lost throws with
+ * nothing recorded — and a retry builds a DIFFERENT transaction that can land
+ * beside the first.
+ */
+export declare function deriveTransactionSignature(signedTransaction: VersionedTransaction): string;
+export declare function isDefinitiveSolanaSendFailure(error: unknown): boolean;
 export declare function handlePreBuiltTransaction(tx: {
     serializedTransaction: string;
     blockhash: string;
     lastValidBlockHeight: number;
     network: string;
-}, authProvider: AuthProvider, options: SetOptions | undefined, expectedWritePaths: string[]): Promise<TransactionResult>;
+}, authProvider: AuthProvider, options: SetOptions | undefined, expectedWritePaths: string[]): Promise<SolanaTransactionResult>;