@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.14.6

package/docs/identity-verification.md

@@ -0,0 +1,218 @@
+# Identity overlay verification
+
+This page records the current C01, C02, and C03 source contract for identity
+results returned by Wallet Toolbox. The implementation and its tests remain
+under review; this page is not a claim that the wider verification plan or
+release gates have completed.
+
+## Evidence boundary
+
+An overlay result is a host-supplied `LookupAnswer`. A host TXID hint and
+`context` are metadata, never chain authority. [`queryOverlayEvidence`](../src/utility/identityUtils.ts)
+copies the BEEF and context bytes received through the additive resolver
+`onEvidence` callback. Resolver callback intake defaults to 512 outputs and
+16 MiB per query and accepts `evidenceLimits: { maxOutputs?, maxBytes? }` as
+configurable local policy. It uses a 300 ms identity grace window. Older or
+custom resolvers that do not invoke the callback remain usable through the
+legacy output-list fallback.
+
+Direct `queryOverlayEvidence` callers can configure
+`{ candidateBytes?, retainedBytes?, outputs? }`. To admit larger valid
+evidence, pass matching byte limits to both this intake option and the third
+`IdentityEvidenceVerifier` constructor argument (`TransactionEvidenceLimits`).
+The resolver and verifier limits are separate admission boundaries and are not
+consensus limits.
+
+[`TransactionEvidenceCoordinator`](../../../sdk/src/transaction/TransactionEvidenceCoordinator.ts)
+parses the owned bytes, derives the selected transaction ID, compares any
+supplied hint, checks the selected output, validates the complete unconfirmed
+graph, and performs fresh canonical-root checks through the caller's
+`ChainTracker`. It checks source transaction/value/script bindings, source TXID
+consistency, duplicate spent outpoints, input/script limits, and rejects an
+unconfirmed zero-input leaf. A successful result identifies a transaction
+output and locking script; it does not establish service relevance, current
+unspentness, ownership, or freshness.
+
+The coordinator's `chainNamespace` and `policyId` are explicit caller-owned
+trust context. An optional synchronous
+`ChainTracker.getVerificationContext(): string | number` is a provider,
+policy, or recovery-generation marker. The optional
+`getVerificationContextToken(signal?)` obtains a fresh trusted tip/context
+token and brackets canonical-root and height checks. Chaintracks and local
+adapters include monotonic reorganization/reset epochs and fence reset entry
+and failure paths. `LocalChainTracker` tokens cover only the providers
+participating in the current attempt: remote-only uses fallback identity,
+local-primary uses local identity. An unused provider cannot stand in, and a
+missing participating identity fails closed. Built-in remote ChainTracks
+clients advertise reorg-event capability explicitly; method presence is not
+capability. `Services.getChainTracker()` publishes one coalesced wrapper
+before yielding. `BHServiceClient` always re-reads the canonical header for
+`isValidRootForHeight` and never treats a previously queried root as a reusable
+positive. A remote tip equality read cannot detect an unobserved ABA
+transition, and a token over multiple sources is not an atomic multi-source
+snapshot. Canonical roots and observed heights remain dependencies that are
+rechecked on each use, including positive-cache reuse. Existing trackers may
+omit either optional method and may ignore optional abort signals.
+
+`EvidenceScriptWork` in the SDK now shares bounded script work by a binding that
+covers the actual transaction, all input source-output bytes and values, and
+script policy/backend parameters. The binding is transaction-wide rather than
+an input-index-only key. A cache hit can skip cryptographic script execution
+only. It still performs source/value binding, complete graph traversal,
+canonical chain calls, and policy/context checks. Non-batch individual
+executions preserve each entry's fulfilled or rejected result so a failed
+sibling cannot reject a successful shared ancestor. Only a backend batch-level
+failure rejects the whole batch. Non-abortable backend work remains counted
+until its actual promise settles, and in-flight owners are isolated. A normal
+block arrival before the next reuse does not erase exact cryptographic script
+work when its transaction/source/policy binding remains valid; canonical roots
+and fresh context are still checked.
+
+## Identity envelope
+
+The interoperable identity output is the standard subject-signed PushDrop
+created by [`IdentityClient.publiclyRevealAttributes`](../../../sdk/src/identity/IdentityClient.ts):
+protocol ID `[1, 'identity']`, key ID `'1'`, token amount `1`, and output index
+`0`. [`IdentityTopicManager`](../../../../packages/overlays/topics/src/identity/IdentityTopicManager.ts)
+checks the same protocol and key, then certificate validity and nonempty
+attributes. `IdentityClientOptions` exposes custom protocol and key values, but
+the current server topic does not accept arbitrary values; custom values remain
+a compatibility characterization item and C01 does not widen server
+acceptance.
+
+The parser checks the subject signature, requires `VerifiableCertificate.verify()`
+to return `true`, decrypts the fields, and requires nonempty decrypted fields.
+`ProtoWallet.verifySignature` throws on a cryptographic failure today; the
+parser catches and rejects that candidate. C01 does not claim an invalid
+certificate can bypass this throw. There is no existing topic contract for an
+arbitrary `lockingPublicKey` equality rule, so none is added.
+
+## Search binding
+
+SDK 2.8.7 and Toolbox 2.14.2 interpret the `any` key as a search across public
+fields other than `profilePhoto` and `icon`. Two-character searches retain the
+overlay's fuzzy behavior. Longer searches compare complete English tokens,
+ignore the default English stopwords, require each quoted phrase and at least
+one positive indexed term, and exclude requested words or phrases. Punctuation
+separates tokens; ASCII apostrophes remain part of English names. Text matching
+is case- and diacritic-insensitive. Named attributes retain ordered literal
+matching on one line, and `userName` remains exact after query whitespace
+normalization. Empty optional named fields are ignored.
+
+This follows the ordinary word/phrase behavior documented for
+[MongoDB text queries](https://www.mongodb.com/docs/manual/reference/operator/query/text/),
+with explicit limits: language-specific suffix stemming and custom index
+languages are not implemented in this client-side binding. A stem-only overlay
+match can still be omitted. Use a complete public name/username token or the
+named-field search when that distinction matters. This is not a claim of full
+MongoDB linguistic equivalence, and the release does not change the server's
+index or lookup protocol. Local MongoDB 8.2.6 characterization covers the
+ordinary complete-word, punctuation, phrase, exclusion and stopword cases.
+
+## Cache and contact boundaries
+
+The wallet keeps three distinct boundaries:
+
+- Transaction evidence is revalidated through the current chain tracker on
+  every use. Coordinator positive results are bounded by configurable generic
+  SDK limits, including 128 entries, 16 MiB retained bytes, and 60 seconds.
+- Decrypted certificate JSON is wallet-owned and copied on return. Its cache is
+  bounded at 2 MiB, 128 entries, and 60 seconds.
+- Raw overlay lookup receipts are copied into a wallet cache bounded at 32
+  queries, 16 MiB, and 120 seconds. A rejected or incomplete parse evicts that
+  query entry so a later call can fetch again.
+
+The wallet obtains the tracker from `getServices().getChainTracker()` and
+reuses the configured instance. Direct [`queryOverlay`](../src/utility/identityUtils.ts),
+`parseResults`, and `parseResults$` calls fail closed when no tracker is
+provided. [`verifyOverlayOutput`](../src/utility/verifyOverlayOutput.ts)
+requires an explicit tracker. Local contacts remain a separate wallet-owned
+source and retain their existing short-circuit and trust behavior; contact
+results must retain local provenance and are not overlay SPV results. Invalid
+candidate evidence is dropped, while typed `limit` and `timeout` outcomes
+propagate to the wallet caller instead of becoming a definitive empty result.
+
+## Compatibility characterization
+
+C01, C02, and C03 preserve existing Promise and `parseResults$` async-iterable
+shapes. The resolver's `onEvidence` callback is optional and additive. Legacy
+resolver answers continue to aggregate by TXID/output index with first-wins
+suppression; a host hint is only a resolver fast path and must be re-derived
+and checked by security-sensitive consumers. The callback is the bounded path
+for consumers that need each host receipt before that suppression. Existing
+2-second lookup and 5-second tracker-wait defaults remain unchanged.
+
+Permission negotiation and pagination are unchanged. The interface
+characterization still records that documentation says `seekPermission`
+defaults to true while the validator currently applies false. Identity lookup
+also retains the existing limit/offset validation and forwarding
+characterization; this evidence work does not silently change either contract.
+
+The standard topic envelope characterization and custom `IdentityClientOptions`
+behavior above remain required for interoperability. No arbitrary locking-key
+equality rule is implied. Chaintracks and local adapters now expose monotonic
+reorganization/reset epochs and fence reset lifecycle races, including reset
+ownership checks after disposal and before a destructive hook. Remote tip
+equality still cannot detect an unobserved ABA transition, and no adapter token
+provides an atomic multi-source snapshot. C03 therefore makes no general
+reorganization-safety claim.
+
+## Usage
+
+Wallet callers use the existing Services configuration:
+
+```ts
+const tracker = await wallet.getServices().getChainTracker()
+const certificates = await parseResults(answer, tracker)
+```
+
+Omitting the utility tracker remains source-compatible but returns no verified
+overlay identities. There is no bypass toggle. Wallet RPC shapes, stored data,
+permission defaults, and pagination behavior require no migration from this
+source work.
+
+On browser and React Native runtimes, `parseResults$` cooperatively yields
+between certificates. This is a current-runtime scheduling behavior, with no
+worker, throughput, latency, resource-isolation, or deployment guarantee.
+C04/C05 work and any whole-plan completion claim remain future scope.
+
+## Requirement and verification mapping
+
+The scoped source supports V1 (independent transaction evidence), the
+byte-binding portion of V2 (BEEF-derived TXID versus any hint), and V5
+(certificate success and trust policy). T04, T07, T09, T10, and T13 remain the
+relevant characterization cases for false hints, graph and anchor checks,
+envelope/certificate validity, permissions/cache/contacts, and Promise/
+pagination compatibility. The synthetic shared-ancestor fixture is 556 BEEF
+bytes with three reachable transactions, three inputs, and 314 serialized
+script bytes; two child graphs produce three actual script executions. Current
+tests are evidence for these slices only; validation is not final until the
+required package and consumer checks pass.
+
+## Historical C01 bundle measurements
+
+The following measurements are retained as historical C01 evidence for the
+2.11.1 artifacts. They are measurements only, not passing platform gates and
+not a release decision. C02/C03 source changes require fresh package and
+consumer validation.
+
+Measurements used Node 24.15.0 and pnpm 10.33.2 on the same macOS host, with
+base commit `2bc799a8d8e535242e6de2d305f426ce3975ea7b` extracted into a temporary
+source tree and the same SDK/dependency graph. A temporary copy of the
+platform checker printed each size instead of evaluating budgets. The original
+checker was not modified.
+
+Each cell lists raw / gzip / Brotli bytes:
+
+| Consumer |                              Base |                               C01 |                  Reviewed maximum |
+| -------- | --------------------------------: | --------------------------------: | --------------------------------: |
+| Vite     |     1,692,309 / 399,380 / 312,207 |     1,694,805 / 400,062 / 312,426 |     1,696,000 / 401,000 / 314,000 |
+| esbuild  |     1,320,184 / 363,792 / 291,500 |     1,322,211 / 364,400 / 291,926 |     1,324,000 / 365,000 / 293,000 |
+| Metro    |     1,747,262 / 443,100 / 343,780 |     1,749,640 / 443,811 / 343,927 |     1,751,000 / 455,000 / 360,000 |
+| Hermes   | 3,544,570 / 1,440,174 / 1,117,759 | 3,550,004 / 1,442,134 / 1,120,813 | 3,553,000 / 1,443,000 / 1,123,000 |
+
+The historical C01 result measured raw growth of 2,496 / 2,027 / 2,378 /
+5,434 bytes for Vite, esbuild, Metro, and Hermes respectively. The C01
+composition retained the same dependencies and did not add a platform-only
+import. The original `test:browser` and `test:mobile` commands remain the
+executable gates for any current release evidence.

package/docs/local-first-chaintracks.md

@@ -0,0 +1,129 @@
+# Local-first ChainTracks
+
+Wallet applications can keep and validate their own header chain instead of
+making a remote service the normal validation boundary. The browser package
+exports IndexedDB ChainTracks. Browser and mobile packages both export the
+portable checkpoint cache contract, bounded fetching, local ChainTracks
+components, and `LocalChainTracker`; the full package additionally exports a
+filesystem checkpoint cache.
+
+## Trust and data flow
+
+1. The release pipeline embeds a checkpoint manifest and immutable 80-byte
+   header files in the application artifact. Each manifest entry includes its
+   chain, height range, SHA-256 digest, previous hash, last hash, and cumulative
+   chain work.
+2. A `BulkFileDataCacheApi` implementation reads an embedded object first and
+   mutable application storage second. A downloaded replacement is written to
+   mutable storage atomically where the platform permits it.
+3. `createIdbChaintracks` or another local factory consumes that cache through
+   the final `ChaintracksSourceOptions` argument. The manager validates object
+   length, digest, genesis, header linkage, declared chain work, and every
+   header's proof of work before the object can answer a query.
+4. Live ingestion follows bounded binary batches and a reconnecting tip stream
+   in the background. IndexedDB in browsers, or the application's durable
+   mobile storage adapter, retains the current height and recent headers across
+   application restarts.
+5. `LocalChainTracker` is supplied to wallet services as the SDK
+   `ChainTracker`. A definitive local `false` result is never changed to
+   `true` by a remote source.
+
+The embedded checkpoint is a bootstrap optimization, not a bypass. Its bytes
+are revalidated locally before use. Release builds should fail when an asset is
+missing, its digest differs from the manifest, the manifest is not contiguous,
+or the checkpoint age exceeds the application's release policy.
+
+## Portable checkpoint cache
+
+Applications implement the small portable contract below. Packaged assets are
+immutable; mutable objects belong in an application-private database or file
+area, not a shared HTTP cache.
+
+```ts
+import type { BulkFileDataCacheApi, BulkHeaderFileInfo } from '@bsv/wallet-toolbox-client'
+
+class ApplicationHeaderCache implements BulkFileDataCacheApi {
+  async get(file: Readonly<BulkHeaderFileInfo>): Promise<Uint8Array | undefined> {
+    return (await readPackagedAsset(file.fileName)) ?? readApplicationData(file.fileName)
+  }
+
+  async set(file: Readonly<BulkHeaderFileInfo>, data: Uint8Array): Promise<void> {
+    await writeApplicationDataAtomically(file.fileName, data)
+  }
+
+  async delete(file: Readonly<BulkHeaderFileInfo>): Promise<void> {
+    await deleteApplicationData(file.fileName)
+  }
+}
+```
+
+Pass the instance as `sources.bulkFileCache` in the final ChainTracks factory
+argument. `sources.bulkFileDownloadBudget` can reserve remote bytes before a
+bulk request begins. The manager coalesces concurrent requests for the same
+immutable object, bounds each response, retries from one layer only, and never
+persists bytes until all validation succeeds.
+
+## Local-primary tracker
+
+Wrap the resulting local client with `LocalChainTracker`. Use at least two
+independently operated reference clients when automatic recovery or fallback
+validation can affect an acceptance decision.
+
+```ts
+import { LocalChainTracker } from '@bsv/wallet-toolbox-client'
+
+const tracker = new LocalChainTracker({
+  local: localChaintracks,
+  fallbacks: independentReferences,
+  mode: 'local-primary',
+  requiredFallbackAgreement: 2,
+  requiredConsistencyAgreement: 2,
+  maxHeightLag: 6,
+  autoRecover: true,
+  recoverLocal: rebuildLocalFromCheckpoint,
+  clearLocal: clearAndRebuildLocal
+})
+
+await tracker.synchronize()
+const walletServices = new Services({
+  ...Services.createDefaultOptions(chain),
+  chainTracker: tracker
+})
+```
+
+`checkConsistency()` compares all available views at a common height and derives
+the reference height reached by the configured quorum. A single stale or
+inflated reference cannot declare divergence or lag when the configured
+agreement is two. Automatic recovery receives the reason, local and reference
+heights, lag, comparison height, expected hash, and agreement count; it should
+quarantine the old database, rebuild from a verified checkpoint, synchronize,
+and return the replacement local client. If the references do not agree, retain
+local state and surface diagnostics instead of resetting it.
+
+Remote fallback is exceptional. It is used only in `remote-only` mode or after
+the local client throws, and it must reach the configured agreement. A local
+proof rejection remains authoritative.
+
+## Application lifecycle and controls
+
+Start synchronization after durable storage is available. Keep it alive while
+the platform grants background execution, checkpoint progress on suspension,
+and resume immediately on connectivity restoration. Use exponential reconnect
+backoff and avoid overlapping synchronization jobs.
+
+An application's advanced chain-management surface should expose:
+
+- local-primary and remote-only modes, with local-primary as the default;
+- local height, tip hash, last sync, consistency state, active source, last
+  fallback, last recovery, and bounded diagnostic error;
+- a manual synchronize action and a quorum consistency check;
+- local header storage size and a destructive clear/rebuild action with an
+  explicit confirmation;
+- checkpoint version/height and the configured independent references.
+
+For migration, preserve the existing remote endpoint as a fallback, create the
+local database without blocking the rest of the wallet, and switch the saved
+default to local-primary only after initial synchronization succeeds. A user
+who explicitly selected remote-only remains remote-only across upgrades.
+Clearing local data must not clear keys, transactions, proofs, or other wallet
+state.

package/docs/managed-change-liquidity.md

@@ -0,0 +1,258 @@
+# 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
+
+Wallet Storage can optionally prepare the exact verified BEEF closure for a
+managed-change source after the foreground action finishes. This COOK
+(Create Once, Output Kept) optimization does not alter funding selection,
+transaction state, or the canonical fallback. See
+[Prepared BEEF (COOK)](./prepared-beef.md) for the asynchronous timing
+contract, storage controls, proof-reorganization handling, and staged 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/docs/managed-change-policy.md

@@ -43,7 +43,7 @@ without allowing them into balance or automatic funding.
 | Request | New output | Existing custom output | Existing managed change |
 | --- | --- | --- | --- |
 | `wallet payment` | Store as managed change in `default` | Promote to managed change after BRC-29 script verification | Idempotent when already in `default` |
-| `basket insertion` to a non-default basket | Store as custom | Move/update as custom; no wallet-balance adjustment | Reject; managed change cannot be reclassified |
+| `basket insertion` to a non-default basket | Store as custom | Move/update as custom; no wallet-balance adjustment\* | Reject; managed change cannot be reclassified |
 | `basket insertion` to `default` | Reject | Reject | Reject |
 
 The wallet signer verifies that `paymentRemittance` derives the transaction
@@ -51,6 +51,19 @@ output's locking script before storage can promote it. This is the supported
 way to repair a genuine BRC-29 payment that was previously classified as
 custom. Merely recognizing a P2PKH locking script is not enough.
 
+\* Only when the existing custom output is currently unbasketed, already in
+the target basket (idempotent re-internalization), or in `default` (see
+[Sweeping and recovery](#sweeping-and-recovery)). A `basket insertion` cannot
+reclassify an existing custom output that already belongs to a *different*
+real, named basket; that request is rejected with `WERR_INVALID_PARAMETER`
+even though the caller holds insertion permission for the requested basket.
+Storage does not know which application "owns" a basket — permission checks
+for the requested basket happen at the `WalletPermissionsManager` layer, not
+here — so without this check an app with insertion permission on basket X
+could internalize an already-known transaction and move another app's output
+out of basket Y into X, then spend it. The requested basket is resolved with a
+read-only lookup, so a rejected request never creates it.
+
 ## Sweeping and recovery
 
 "Sweep" means moving an incompatible custom row out of the default basket with