@bsv/wallet-toolbox 2.6.4 → 2.7.0

package/CHANGELOG.md

@@ -6,9 +6,74 @@ attention to changes that materially alter behavior or extend functionality.
 
 ## wallet-toolbox (unreleased)
 
-- Finish broadcasting durable permission-token grants before resuming the
-  waiting application request, preventing the grant transaction from briefly
-  reserving the wallet's funding inputs out from under the resumed action.
+- Keep mainnet and testnet ChainTracks usable from browser and webview wallets:
+  browser runtimes temporarily select the CORS-enabled legacy service while
+  Node runtimes retain Arcade/go-chaintracks v2. `Services.getHeight` now falls
+  back to WhatsOnChain if ChainTracks is unavailable and preserves the original
+  ChainTracks error when both providers fail.
+- Route `ttn` wallets through the isolated `teratestnet` overlay preset and
+  enable the public TTN Arcade broadcaster/proof provider by default. TTN does
+  not register the incompatible legacy ARC BEEF fallback. Other chain defaults
+  are unchanged, and an empty Arcade URL explicitly disables Arcade.
+- Reconcile Arcade broadcast outcomes as durable wallet state. Retryable
+  locktime and parent conditions remain pending, while validator failures fail
+  the request and explicit missing-input or conflict evidence atomically fails
+  every local transaction copy and quarantines its wallet-owned inputs without
+  depending on WhatsOnChain. Cached accepted/seen labels can no longer revive a
+  terminal conflict; only a mined event whose Merkle proof validates through
+  the configured chain tracker may repair it. Arcade also participates in the
+  shared transaction-status service so double-spend review remains conservative
+  on networks with no explorer. A scheduled paged pass also reconciles aged
+  pending requests from durable Arcade lifecycle state, including orphan-mempool
+  losers whose SSE event was missed; mined/known evidence wins over rejection.
+  Inconclusive or absent UTXO providers no longer
+  masquerade as a spent-output verdict in invalid-change release, stale-input
+  reconciliation, proof recovery, or storage diagnostics. Invalid-change review
+  returns conclusive read-only findings plus unknown diagnostics. Direct release
+  blocks atomically with machine-readable `WERR_UTXO_REVIEW_INCONCLUSIVE` when
+  any result is unknown. Monitor Admin uses bounded, five-second-deadline pages
+  and can explicitly release the confirmed-spent subset while retaining unknowns;
+  every mutation rechecks ownership/allocation under lock and records audit
+  evidence. Monitor Admin scans by default and requires explicit confirmation.
+  The
+  Arcade SSE cursor advances only after both event storage work and cursor
+  persistence succeed; either failure leaves the event queued for ordered retry.
+- Replace 32-satoshi default-basket fragments with a progressive liquidity
+  policy targeting 144 useful 5,000-satoshi outputs. New actions create at most
+  eight outputs from real surplus and migrate at most four fee-positive legacy
+  fragments, while a same-tier compatibility plan guarantees that optional
+  shaping cannot refuse an action the former planner could fund. Explicitly
+  funded actions materialize change from their existing surplus without
+  gathering pool inputs, and SQLite policy migrations use sync-compatible UTC
+  ISO timestamps.
+- Prefer completed, then unproven, then sending parents. Plans above 16 inputs
+  compare exact transaction-plus-BEEF bytes before accepting pending ancestry;
+  pending change remains an unconditional last-resort funding source. Align
+  action-batch reservation/planning and add a read-only Monitor liquidity
+  report. All work limits are configurable and accept `-1` for explicit
+  operator-selected unlimited behavior.
+- Restore delayed broadcast for durable permission-token persistence. Permission
+  grants no longer inherit network-broadcast latency; the managed-change policy
+  handles queued ancestry without hiding it or preferring it over settled funds.
+- Isolate each in-memory action batch by explicit staged-output or `sendWith`
+  membership, so unrelated immediate actions and `noSend` roots cannot be
+  captured by or commit a workspace. Add an exact-input resume protocol for
+  expired leases, structured lifecycle errors, and a provider-enforced
+  cumulative reservation limit that defaults to 256 outputs and can be
+  configured, including `-1` for operator-selected unlimited operation.
+- Keep the combined action-batch, managed-liquidity, browser-fallback, and
+  fail-safe reconciliation browser/mobile cost bounded by exact packed-artifact
+  contracts. Local verification measures 1,557,683 raw / 366,927 gzip / 287,337
+  Brotli bytes with Vite, 1,215,983 raw / 333,466 gzip / 268,497 Brotli bytes
+  with esbuild, 1,617,544 raw Metro bytes, and 3,271,146 raw / 1,302,110 gzip /
+  1,025,812 Brotli Hermes bytes. Reviewed raw ceilings are 1,561,000 Vite bytes,
+  1,220,000 esbuild bytes, 1,710,000 Metro bytes, and 3,275,000 Hermes bytes;
+  compressed ceilings remain independently governed.
+- Fix `WalletStorageManager.getStoreEndpointURL` / `getStores().endpointURL` to
+  duck-type provider `endpointUrl` instead of matching
+  `constructor.name === 'StorageClient'`. Production minifiers rename classes,
+  so the name check left remote stores with `endpointURL: undefined` while
+  sync still worked; clients that select a backup by URL (make primary) failed.
 - Let Storage Server operators select an explicit listener host while retaining
   the historical omitted-host behavior for existing callers. The official
   Wallet Infrastructure image uses this to bind direct-mode traffic on IPv4

package/README.md

@@ -26,12 +26,16 @@ BSV Desktop and BSV Browser are the BSV Association reference wallet application
 | **MockChain**      | In-memory blockchain for testing — mock mining, UTXO tracking, and merkle proof generation without a network                                     |
 | **Entropy**        | `EntropyCollector` gathers mouse/touch entropy for high-quality randomness in browser environments                                               |
 
-Durable permission grants finish broadcasting their internal token transaction
-before the waiting application request resumes. This keeps the grant atomic from
-the caller's perspective and makes its funding change immediately reusable by a
-following wallet action. If broadcasting is unavailable, the grant rejects and
-the application can safely surface the error and retry; ephemeral one-time grants
-remain off-chain.
+Durable permission grants queue their internal token transaction for delayed
+broadcast, so permission approval does not inherit network-broadcast latency.
+The funding planner prefers settled change and uses queued permission ancestry
+only as a last resort, keeping the application path fast without hiding funds.
+
+Immediate actions prefer completed, then unproven, then sending change. A
+pathological settled plan is compared with pending alternatives by exact
+serialized BEEF plus transaction bytes; queued ancestry is used only when it is
+necessary or smaller. Pending change is never withheld, so queued
+work cannot strand the balance behind a large reserved input.
 
 ### Packages
 
@@ -43,9 +47,13 @@ The toolbox publishes three npm packages from this repo:
 
 ### ChainTracks sources and networks
 
-Wallet services do not require a WhatsOnChain key for ChainTracks. Mainnet,
-testnet, and TerraTestNet use the public Arcade/go-chaintracks v2 HTTP and SSE
-surfaces by default. Bulk batches still pass through local serialization, hash,
+Wallet services do not require a WhatsOnChain key for ChainTracks. Node
+runtimes on mainnet, testnet, and TerraTestNet use the public
+Arcade/go-chaintracks v2 HTTP and SSE surfaces by default. Browser and webview
+runtimes on mainnet/testnet temporarily select the legacy CORS-enabled service
+until the v2 edge serves CORS and OPTIONS; `Services.getHeight` also falls back
+to WhatsOnChain on those networks if ChainTracks is unavailable. Bulk batches
+still pass through local serialization, hash,
 continuity, and genesis checks; providers are tried in priority order; and a
 synchronized tracker can continue serving its last-good checked data during a
 provider outage. WhatsOnChain remains a mainnet/testnet fallback and anonymous
@@ -60,8 +68,51 @@ go-chaintracks client; existing legacy v1 URLs and explicit clients remain
 compatible. Browser and mobile distributions expose the same fetch/SSE client
 without Node `Buffer` or filesystem dependencies.
 
-Arcade is the browser-safe HTTPS/SSE gateway for Teranode-backed header data.
-Direct Teranode P2P is not included in browser/mobile artifacts.
+Arcade is the HTTPS/SSE gateway for Teranode-backed header data. Its v2 edge
+must allow browser origins and OPTIONS before browser defaults can use it;
+direct Teranode P2P is not included in browser/mobile artifacts.
+
+TTN wallets also register
+`https://arcade-v2-ttn-us-1.bsvblockchain.tech` as their first broadcast and
+Merkle-proof provider. Mainnet and testnet Arcade broadcasting remains opt-in.
+Pass an explicit `arcadeUrl` to override the TTN endpoint or an empty string to
+disable it. TTN overlay lookups use the separate `teratestnet` resolver preset
+and never fall back to testnet discovery.
+
+### Broadcast rejection and monitor reconciliation
+
+When Arcade is configured, Wallet Toolbox consumes Arcade's status code and
+validator detail instead of treating every `REJECTED` event alike. Retryable
+parent and locktime conditions stay pending. Terminal validator failures fail
+the request, and explicit missing-input or conflict evidence also quarantines
+every wallet-owned copy of the consumed input in the same storage transaction.
+That quarantine uses Arcade's positive rejection evidence and does not require
+WhatsOnChain or another UTXO explorer.
+
+Arcade is also registered as a transaction-status provider, so monitor review
+continues on networks without WhatsOnChain. A scheduled bounded pass revisits
+aged pending requests and applies durable Arcade lifecycle verdicts that may
+have arrived while SSE was disconnected, including `SEEN_IN_ORPHAN_MEMPOOL`.
+Mined/known evidence takes precedence over a stale rejection. Provider absence
+and provider errors are treated as inconclusive, never as proof that an output
+was spent.
+After an input conflict has been recorded, a later cached accepted/seen label
+cannot restore the failed transaction; recovery requires a mined status and a
+Merkle proof validated by the configured chain tracker. Arcade SSE events are
+acknowledged in order only after their storage update and cursor persistence
+succeed, so a transient storage failure is retried instead of skipped.
+
+Invalid-change review applies the same positive-evidence rule. Only an
+explicit successful `isUtxo: false` result is considered spent; a provider
+error, rate limit, timeout, missing provider, missing script, or malformed
+response is unknown. Read-only scans return the conclusive picture plus the
+unknown count. Direct destructive release remains all-or-nothing: any unknown
+throws `WERR_UTXO_REVIEW_INCONCLUSIVE` before mutation. The authenticated
+Monitor Admin tool instead uses 20-output pages (four provider calls in flight,
+five-second per-output review deadline) and may explicitly release the
+positively spent subset while retaining and reporting unknowns. Each confirmed
+spent output is rechecked for ownership and allocation state under the write
+lock, and every release or blocked release records bounded audit evidence.
 
 Core ChainTracks factories accept a final source-options argument when an
 application must override the defaults. Set `disableChaintracks`, `disableCdn`,
@@ -122,6 +173,11 @@ See [Managed change, sweeping, and recovery](./docs/managed-change-policy.md)
 for the default-basket invariant, automatic funding policy, and supported
 `internalizeAction` repair paths.
 
+See [Managed-change liquidity policy](./docs/managed-change-liquidity.md) for
+the 144-output / 5,000-satoshi defaults, gradual legacy-wallet migration,
+pending-parent policy, exact BEEF comparison, operator tuning, action-batch
+alignment, monitoring, and rollout guidance.
+
 See [In-memory action batch planning](./docs/action-batch-planning.md) for
 capability-negotiated `noSend` planning, compact manifests, compressed binary
 pack transport, atomic commit, compatibility behavior, and retained benchmarks.
@@ -139,7 +195,7 @@ The planner uses the same exact / least-over / largest-under selection policy
 as the historical allocator, but proves economic sufficiency before writing a
 transaction and claims every selected input in one database transaction. Knex
 storage automatically adds a composite funding-selection index on migration;
-IndexedDB schema version 3 adds corresponding user/basket and outpoint indexes
+IndexedDB schema version 4 adds corresponding user/basket and outpoint indexes
 and resolves transaction-status eligibility in one indexed pass.
 
 The retained fragmented-funding benchmark is runnable with:

package/docs/action-batch-planning.md

@@ -17,12 +17,34 @@ Large first actions use compact bootstrap only when the provider also advertises
 `compactBegin: true`; this keeps new clients compatible with older version-1
 servers during a rolling deployment.
 
+One `Wallet` instance owns at most one in-memory action-batch workspace. An
+independent `noSend` graph created while that workspace is open uses the ordinary
+persistent path; it is not captured merely because the calls overlap. Storage
+providers may host many concurrent batches for different wallets or sessions,
+and their output reservations remain disjoint. A future client-side multi-workspace
+router would also need defined semantics for a `sendWith` request or child action
+that joins more than one graph; this version deliberately does not imply those
+semantics.
+
 The original manifest and one-blob-per-request transport remain version 1. A
 provider can independently advertise the additive `manifestVersion: 2`,
-`commitByDigest`, and `packedUploads` capabilities. A new client uses each
-optimization only when its provider advertises it. Old clients ignore the extra
-fields, new clients retain the version-1 path against old providers, and the two
-new storage methods are optional for third-party `WalletStorage` implementations.
+`commitByDigest`, `resume`, `maxReservedOutputs`, and `packedUploads`
+capabilities. A new client uses each optimization only when its provider
+advertises it. Old clients ignore the extra fields, new clients retain the
+version-1 path against old providers, and additive storage methods remain
+optional for third-party `WalletStorage` implementations. The exported capability
+helper does not advertise `resume` by default; built-in providers opt in because
+they implement the optional `resumeActionBatch` method.
+
+The retained browser platform contract measures the resumable implementation at
+1,548,179 raw / 364,550 gzip / 285,697 Brotli bytes with Vite and 1,209,217 raw /
+331,318 gzip / 267,001 Brotli bytes with esbuild. Every browser size ceiling
+remains unchanged.
+
+The mobile contract measures 1,609,633 raw / 405,646 gzip / 315,527 Brotli
+Metro bytes and 3,253,366 raw / 1,293,591 gzip / 1,018,837 Brotli Hermes bytes.
+Only the Hermes raw ceiling advances, by less than 0.15%; every compressed and
+Metro ceiling remains unchanged.
 
 The capability and its methods are Wallet Toolbox storage extensions. They do not
 extend `WalletInterface`, `CreateActionArgs`, `SignActionArgs`, `noSend`,
@@ -36,17 +58,26 @@ extend `WalletInterface`, `CreateActionArgs`, `SignActionArgs`, `noSend`,
    output-script lengths at bootstrap. Signed transactions and the external
    proof frontier follow through the binary commit path, so a hexadecimal
    script is not duplicated into a large JSON request.
-2. The wallet plans, signs, validates, and indexes subsequent actions locally. A
-   shared BEEF graph avoids retaining repeated ancestry. The signed transaction
-   is the canonical source for output scripts; format 2 carries script digests
-   for validation, rather than carrying the same scripts as transaction bytes,
-   plan strings, metadata strings, and standalone blobs.
+2. The wallet plans, signs, validates, and indexes a subsequent action locally
+   only when it belongs to the same transaction graph: an input or
+   `noSendChange` outpoint references a staged output, or `sendWith` references
+   a transaction owned by the workspace. Time adjacency, a shared wallet or
+   originator, and merely being another `noSend` action do not establish
+   membership. Unrelated work continues through the ordinary persistence path.
+   A shared BEEF graph avoids retaining repeated ancestry. The signed
+   transaction is the canonical source for output scripts; format 2 carries
+   script digests for validation rather than duplicating scripts.
 3. If confirmed funding runs low, the wallet extends its reservation pool using
    an EWMA estimate and geometrically increasing runway. Forwarded staged change
    needs no reservation or extension.
-4. `sendWith`, or a normal action created while the workspace is open, validates
-   and atomically persists every staged action. Only the requested transactions
-   are sent; earlier actions retain their `nosend` status.
+4. `sendWith` that names a workspace transaction, or a normal action that
+   explicitly depends on a staged output, validates and atomically persists
+   every member action. An unrelated normal action neither joins nor commits
+   the workspace. Only the requested transactions are sent; earlier actions
+   retain their `nosend` status. If a workspace-owned `noSend` action also
+   requests only unrelated persisted transactions through `sendWith`, the new
+   action remains staged and the explicit broadcasts run through the ordinary
+   persistence path; neither request is silently dropped.
 5. Broadcast occurs after the storage transaction. Delayed mode returns after the
    batch is durably queued; immediate mode uses the existing aggregate broadcaster
    and review results.
@@ -62,17 +93,24 @@ can use unreserved outputs normally. A uniqueness constraint prevents one output
 from belonging to two active batches.
 
 The initial reservation includes at most three extra candidates and never more
-than eight outputs. Its canonical funding target includes the marginal P2PKH
-input fee and enough value to recover an economically viable first change output,
-so a low basket minimum cannot repeatedly select inputs that satisfy the nominal
-deficit but cost too much to use.
-
-Extensions add at most 64 outputs per storage call, but there is no cumulative
-reservation, workspace-size, action-count, or spend-chain limit. Additional
-bounded calls continue for as long as the workspace needs confirmed funding.
-They use the same exact, least-over, then largest-under selection policy as
-normal funding. Retry targets are incremental shortfalls: the planner credits
-the value and count of every unconsumed reserved output before asking for more.
+than eight outputs or the operator's lower cumulative reservation cap. Its
+canonical funding target includes the marginal P2PKH input fee and enough value
+to recover an economically viable first change output, so a low basket minimum
+cannot repeatedly select inputs that satisfy the nominal deficit but cost too
+much to use.
+
+Extensions add at most 64 outputs per storage call. Built-in providers also
+enforce and advertise a cumulative maximum of 256 persisted output reservations
+per workspace, including caller-selected persisted inputs and confirmed inputs
+already consumed by uncommitted member transactions. This is a provider resource
+bound, not a transaction or consensus input limit; staged outputs do not consume
+additional persisted reservations. Set `StorageProviderOptions.actionBatchMaxReservedOutputs`
+(or the matching `SetupWalletKnexArgs` option when using
+`Setup.createStorageKnex`) to another positive integer, or to `-1` for
+operator-selected unlimited operation. The provider advertises the effective value. Extensions use the same
+exact, least-over, then largest-under selection policy as normal funding. Retry
+targets are incremental shortfalls: the planner credits the value and count of
+every unconsumed reserved output before asking for more.
 Confirmed inputs already used by staged transactions remain reserved until
 commit but are not credited as available funding. Proactive EWMA requests
 likewise subtract the unconsumed pool, initialize from the first complete
@@ -80,9 +118,14 @@ sample, and increase geometric runway only when the provider fulfills both the
 requested count and value. Empty or partial extensions therefore cannot
 compound a target against unchanged wallet state.
 Leases last 15 minutes with a 60-minute hard lifetime. Long-running workspaces
-renew near 80% of the lease; commit may atomically reacquire an expired reservation
-when no conflicting spend or reservation occurred. Commit, abort, wallet
-destruction, expiry cleanup, and the one-minute monitor task release unused state.
+renew near 80% of the lease. A client and provider advertising `resume` can
+atomically reacquire only the exact persisted outpoints already held by that
+workspace after soft expiry; a conflicting spend or reservation fails that
+connected workflow without capturing unrelated actions. Lifecycle failures use
+`WERR_ACTION_BATCH_STATE` with a machine-readable state rather than message-text
+matching. Version-1 commit retains its compatible expired-input reacquisition
+path. Commit, abort, wallet destruction, expiry cleanup, and the one-minute
+monitor task release unused state.
 
 ## Atomic commit and payload transport
 
@@ -193,15 +236,15 @@ pnpm --filter @bsv/wallet-toolbox bench:action-batch
 On the same Apple Silicon host with Node.js v25.9.0, a representative cold
 250-action, 1 KiB-script run reduced planning/signing/validation from
 19,117.03 ms in legacy mode to 10,907.93 ms in batch mode (42.9%, or 1.75x).
-Including atomic commit, total local time was 19,163.87 ms versus 11,462.13 ms
-(40.2% lower), while storage calls fell from 501 to 2 and database transactions
-from 252 to 3. At 100 ms storage RTT those calls represent 50,100 ms versus
-200 ms of control-path latency, a 99.6% reduction.
-
-A generic single 4 MiB zero-filled script took 1,258.13 ms through the legacy
-path and 208.60 ms through format 2, including upload and atomic commit: 83.4%
-less local time. Its instrumented requests fell from 13,982,465 bytes to 8,064
-bytes. The one 4,195,234-byte logical pack compressed to 5,233 bytes and was
+Including atomic commit, total local time was 11,131.49 ms versus 5,795.95 ms
+(47.9% lower), while storage calls and database transactions fell from 750 to
+2 and from 750 to 3, respectively. At 100 ms storage RTT those calls represent
+75,000 ms versus 200 ms of control-path latency, a 99.7% reduction.
+
+A generic single 4 MiB zero-filled script took 1,160.86 ms through the legacy
+path and 288.20 ms through format 2, including upload and atomic commit: 75.2%
+less local time. Its instrumented requests fell from 13,982,465 bytes to 8,067
+bytes. The one 4,195,234-byte logical pack compressed to 5,236 bytes and was
 uploaded in one call. This synthetic compression ratio represents highly
 repetitive data; incompressible data falls back to identity encoding without
 expansion. Absolute times remain host- and database-dependent.
@@ -210,8 +253,8 @@ It records planning, signing and validation, storage RPCs, database transactions
 request bytes, commit and broadcast time, CPU, and incremental peak heap. Physical
 SQLite runs compare 1, 10, 50, and 250 action chains at 1 KiB and exercise each
 larger script size with a real action, including the 4 MiB upload path. Its
-complete model covers dependent, independent, explicit-input, and two-step
-signing workloads at every action count; 1 KiB, 64 KiB, 1 MiB, and 4 MiB
+complete model covers dependent, isolated-root fallback, explicit-input, and
+two-step signing workloads at every action count; 1 KiB, 64 KiB, 1 MiB, and 4 MiB
 scripts; and 25, 100, and 250 ms storage RTT. The measured cases deliberately
 include both many-small-action and few-large-action shapes so transport tuning
 is not fitted to one contract or graph. Production rollout should additionally

package/docs/managed-change-liquidity.md

@@ -0,0 +1,251 @@
+# Managed-change liquidity policy
+
+Wallet-managed change is both the wallet's balance and its concurrency pool.
+An output that is technically spendable but too small to carry a useful action
+at the current fee rate does not provide useful liquidity. Conversely, creating
+the entire pool in one transaction makes every child carry a large common BEEF
+ancestor and creates unnecessary linkage.
+
+This policy keeps `createAction` available to existing callers while gradually
+moving new and existing wallets toward useful, parallel funding units.
+
+## Invariants
+
+The implementation treats these as non-negotiable:
+
+1. A policy preference cannot make an action fail if the former planner could
+   fund it. Each parent-status tier retries the compatibility funding shape
+   before the planner widens to less-preferred ancestry.
+2. `completed` parents are preferred, then `unproven`, then `sending`.
+   Pending outputs are never withheld: they remain a last-resort source and
+   are selected when settled liquidity cannot fund the action.
+3. A large settled-input plan may be compared with pending alternatives, but
+   only after the configurable comparison threshold. The comparison uses the
+   actual serialized BEEF bytes plus the planned transaction bytes; input
+   count and satoshi value are not used as BEEF-size proxies.
+4. Pool growth consumes only surplus already present after the requested
+   action and its exact incremental fee are funded. The wallet does not gather
+   another input merely to manufacture change outputs.
+5. An output below the preferred value is permitted when it is the only
+   fundable remainder. The preferred value is not a dust rule and cannot turn
+   a valid payment into `WERR_INSUFFICIENT_FUNDS`.
+6. Legacy fragments migrate only on a caller-authorized `createAction`, only
+   when their value exceeds their marginal input fee, and only within the
+   configured per-action budget.
+7. Action-batch workspaces reserve disjoint outputs and use the same change
+   values and per-action shaping limits as the legacy `createAction` path.
+8. Permission-token persistence retains delayed broadcast so a permission
+   grant does not inherit network-broadcast latency. The funding policy makes
+   queued change available only after preferred alternatives are exhausted.
+
+## Defaults
+
+| Setting                            |        Default | Purpose                                                                                                          |
+| ---------------------------------- | -------------: | ---------------------------------------------------------------------------------------------------------------- |
+| Default-basket target              |    144 outputs | Supports many independently planned actions without requiring one large fanout transaction.                      |
+| Preferred output value             | 5,000 satoshis | Keeps a liquidity unit useful at fee rates materially above the historical 32-satoshi era.                       |
+| New outputs per action             |              8 | Builds the pool progressively and bounds any one transaction's fanout and descendant BEEF footprint.             |
+| Legacy migration inputs per action |              4 | Retires old fragments progressively without recreating 178-input permission transactions.                        |
+| Pending-comparison threshold       |      16 inputs | Keeps the common settled path fast; above this point the planner measures alternatives by exact serialized cost. |
+
+At the Wallet Toolbox default of 100 satoshis/kB, a 148-byte managed input adds
+about 15 satoshis of fee and a minimal one-input/one-output transaction costs
+about 20 satoshis. A 5,000-satoshi preferred unit is therefore roughly 250
+minimal-spend fees at that rate. Even at 1,000 satoshis/kB it remains roughly
+26 minimal-spend fees. The value is intentionally a liquidity target, not a
+consensus or economic-dust boundary.
+
+A completely filled default pool represents 720,000 satoshis. Wallets with a
+smaller balance do not attempt to manufacture that reserve. They retain fewer
+outputs, and a remainder below 5,000 satoshis is kept when that is the only
+available shape.
+
+## Funding and ancestry selection
+
+For each action, storage loads unreserved managed change once and plans in this
+order:
+
+1. completed parents;
+2. completed plus unproven parents;
+3. completed, unproven, and sending parents.
+
+Within each tier, the new surplus-only shape runs first. If that shape reports
+insufficient funds, the same tier is immediately retried with the former
+funding algorithm and the allocator's economic floor for its first remainder.
+This is deliberately at least as permissive as the historical 32-satoshi
+basket. An inability to create a preferred 5,000-satoshi change output is not
+evidence that settled funds cannot pay the requested output.
+
+The first successful plan is accepted immediately when it uses no more than 16
+managed inputs. Above that threshold, later status tiers are also planned and
+the wallet compares:
+
+```text
+serialized cost = planned transaction bytes + exact input BEEF bytes
+```
+
+The smallest measured plan wins. If proof retrieval needed only for comparison
+is unavailable, that alternative receives an infinite comparison cost; the
+already fundable baseline remains available. This optimization can therefore
+improve latency and BEEF size but cannot become a new availability dependency.
+
+Using a `sending` parent necessarily extends the unconfirmed BEEF chain and a
+failed ancestor can invalidate its descendants. That is why it is last in the
+normal order. It remains supported because refusing a fundable user action is
+worse than reluctantly extending the chain after all safer liquidity is
+exhausted.
+
+## Progressive pool shaping
+
+Explicit or fixed inputs can already cover the requested outputs and fee. In
+that case the planner materializes the first change output directly from that
+existing surplus before considering optional fragment migration. It does not
+call the managed-change allocator merely to create pool outputs. This keeps
+consolidations and externally funded actions on the same shaping policy while
+preserving the invariant that pool growth never gathers compulsory inputs.
+When the surplus cannot pay both the marginal output fee and the economic dust
+floor, the bounded remainder stays in the transaction fee instead of causing a
+compatibility retry to gather another input solely to manufacture change.
+
+After compulsory funding succeeds, the planner may consume up to four
+undersized outputs. A fragment is skipped when spending it would cost at least
+its value. Optional migration never supplies a missing satoshi for the caller's
+requested outputs and never runs when the basket is already at its target.
+
+The resulting surplus is split into at most eight outputs and only when every
+new output can meet the preferred value after paying the exact added output
+fee. Otherwise the wallet keeps one output. Excess is distributed through the
+existing randomized change algorithm, and ordinary output randomization still
+applies. The policy therefore preserves the existing privacy intent and
+non-uniform values whenever surplus exists instead of replacing it with a
+fixed deterministic denomination scheme. When the available value is exactly
+the sum of the preferred minima, equal minima are unavoidable; the wallet does
+not create a smaller output merely to force cosmetic variance.
+
+The target is based on healthy outputs (those at or above the basket's
+preferred value), not raw output count. Consuming a legacy fragment and
+creating a useful output moves the pool forward; merely retaining another
+32-satoshi fragment does not make the pool appear healthy.
+
+## Existing-wallet migration
+
+The SQL and IndexedDB providers recognize only the exact historical untouched
+default:
+
+```text
+basket name = default
+target count = 144
+minimum value = 32
+```
+
+Those baskets advance to a 5,000-satoshi preferred value during the normal
+provider migration. Other basket names, custom target counts, and custom
+minimum values are unchanged. The migration does not consolidate, sign, or
+broadcast a transaction. Future `createAction` calls progressively consume at
+most the configured number of fee-positive fragments and create useful change
+only from real surplus.
+
+The SQL data migration is intentionally one-way. Rolling code back does not
+rewrite a migrated preference to 32 or fragment funds. Older code can still
+read and honor the 5,000-satoshi basket value. SQLite writes the migrated
+row's timestamp in UTC ISO form, matching incremental-sync query values and
+keeping that metadata immediately sync-visible. MySQL retains its native
+millisecond timestamp expression.
+
+## Operator configuration
+
+The defaults are suitable for a general wallet. Local Knex and IndexedDB
+operators can tune the work budgets without rebuilding the package:
+
+```ts
+const setup = await Setup.createWalletKnex({
+  ...args,
+  managedChangePolicy: {
+    maxOutputsPerAction: 8,
+    migrationInputsPerAction: 4,
+    pendingComparisonInputs: 16
+  }
+})
+```
+
+The same `managedChangePolicy` option is accepted by `StorageKnex`,
+`StorageIdb`, `Setup.createStorageKnex`, and `SetupClient.createStorageIdb`.
+The basket target and preferred value remain user-wallet settings and can be
+changed through `wallet.setWalletChangeParams(count, satoshis)`.
+
+Each policy limit accepts `-1`, with deliberately different meanings:
+
+- `maxOutputsPerAction: -1` makes the basket target the only fanout bound;
+- `migrationInputsPerAction: -1` permits all fee-positive legacy fragments in
+  one authorized action;
+- `pendingComparisonInputs: -1` disables optional pending-plan comparison, but
+  pending funds remain available when earlier tiers are insufficient.
+
+Unlimited modes can create large transactions or BEEF payloads and should be
+used only by operators that have measured their workload. They do not remove
+the wallet's economic-dust check, transaction validity checks, action-batch
+reservation limit, or available-funding bound.
+
+The official `wallet-infra` image exposes the same settings as validated
+environment values:
+
+```dotenv
+WALLET_STORAGE_MANAGED_CHANGE_MAX_OUTPUTS_PER_ACTION=8
+WALLET_STORAGE_MANAGED_CHANGE_MIGRATION_INPUTS_PER_ACTION=4
+WALLET_STORAGE_MANAGED_CHANGE_PENDING_COMPARISON_INPUTS=16
+```
+
+This lets a hosted Wallet Storage provider choose the policy without rebuilding
+the image. Invalid, unsafe-integer, or out-of-range values fail startup instead
+of silently falling back. The API and singleton Monitor roles must use the same
+values so planning, reservation, and operator reporting describe one policy.
+
+## Action batches and concurrent workspaces
+
+An action-batch begin response carries the effective output and migration
+limits when the provider supports them. Older and third-party providers can
+omit the optional policy; clients then use the same defaults. Initial and
+extended reservation selection prefers completed parents, then unproven, then
+sending, while still reserving enough last-resort liquidity to avoid wedging a
+workspace.
+
+Workspaces remain isolated by explicit transaction-graph membership and their
+reservations remain disjoint. Pool-shaping state is local to each plan; there
+is no global in-memory "current batch" whose change can be consumed by an
+unrelated action.
+
+## Monitoring and rollout
+
+`TaskReviewUtxos.reviewManagedChangeByIdentityKey(identityKey)` is a read-only
+operator report. It returns:
+
+- total and target managed-change counts;
+- healthy and undersized counts;
+- active action-batch reservations;
+- completed, unproven, and sending parent counts;
+- total satoshis and the preferred minimum.
+
+Monitor has no signing authority and does not perform consolidation. This
+keeps migration tied to normal user-authorized actions and makes rollout
+observable without creating surprise transactions. The official Monitor admin
+UI exposes the same report as the **managed-change liquidity (read only)** UTXO
+review mode.
+
+Recommended rollout checks are:
+
+1. record the report before upgrade;
+2. migrate the storage provider and confirm only exact legacy defaults changed;
+3. exercise a small immediate action, a delayed permission action, and two
+   concurrent action-batch workspaces;
+4. confirm undersized count declines gradually and sending-parent use remains
+   exceptional;
+5. watch action input count, serialized BEEF bytes, fee, and broadcast failure
+   rates before changing defaults or selecting an unlimited mode.
+
+## Compatibility surface
+
+No BRC-100 method, Wallet Wire method, Storage Server RPC method, or persisted
+transaction format changes. The action-batch policy field is optional. Existing
+custom basket settings remain authoritative. A same-tier compatibility plan,
+followed by the retained pending-parent fallback, ensures the new preferences
+do not add a refusal where the previous wallet could create an action.

package/out/src/Setup.d.ts

@@ -9,6 +9,7 @@ import { Monitor } from './monitor/Monitor';
 import { Wallet } from './Wallet';
 import { StorageKnex } from './storage/StorageKnex';
 import { WalletStorageProvider } from './sdk/WalletStorage.interfaces';
+import type { ManagedChangePolicyOptions } from './storage/methods/managedChangePolicy';
 /**
  * The 'Setup` class provides static setup functions to construct BRC-100 compatible
  * wallets in a variety of configurations.
@@ -190,6 +191,8 @@ export interface SetupWalletArgs {
      * storage validation. This does not alter the BRC-100 interface.
      */
     scriptVerifier?: SpendVerifierInterface;
+    /** Optional operator tuning for wallet-managed liquidity shaping. */
+    managedChangePolicy?: ManagedChangePolicyOptions;
 }
 /**
  *
@@ -197,6 +200,12 @@ export interface SetupWalletArgs {
 export interface SetupWalletKnexArgs extends SetupWalletArgs {
     knex: Knex<any, any[]>;
     databaseName: string;
+    /**
+     * Maximum persisted outputs one action-batch workspace may reserve.
+     * Defaults to 256. Set to -1 only when the storage operator deliberately
+     * accepts unbounded reservations.
+     */
+    actionBatchMaxReservedOutputs?: number;
 }
 /**
  *