Merge pull request #463 from sgbett/feat/455-align-status-taxonomy

feat!: align action status taxonomy with reference SDK; fail loudly on broadcast misconfiguration

Author: sgbett

.claude/plans/20260416-455-align-status-taxonomy.md

@@ -0,0 +1,159 @@
+# Plan: HLR #455 — Align action status with reference SDK; fail loudly on broadcast misconfiguration
+
+## Context
+
+`bsv-wallet`'s `create_action` and `internalize_action` collapse distinct states into `'completed'`, leading consumers to believe transactions are on-chain when they may not be. This caused phantom-payment bugs in x402-rack (#148, #158) and x402-doom (#196).
+
+The TS reference SDK (wallet-toolbox) distinguishes `'nosend'`, `'unsent'`, `'sending'`, `'unmined'`, `'unproven'`, `'completed'`, `'failed'`. `'completed'` means a merkle proof is on file. Ruby currently uses `'completed'` for "broadcast succeeded" (wrong) and "no broadcaster, nothing on chain" (also wrong, silently).
+
+## Current status-setting sites
+
+| Site | Current | Fix |
+|------|---------|-----|
+| `auto_fund_and_create` `no_send: true` (wallet_client.rb:814) | `'nosend'` | ✓ keep |
+| `auto_fund_and_create` default (wallet_client.rb:834) | `'pending'` (pre-queue) | ✓ keep |
+| `finalize_action` (wallet_client.rb:1441-1448) | `'nosend'` or `'pending'` | ✓ keep |
+| `InlineQueue#broadcast_and_promote` success (inline_queue.rb:100) | `'completed'` | → `'unproven'` |
+| `InlineQueue#broadcast_and_promote` failure (inline_queue.rb:89) | `'failed'` | ✓ keep |
+| `InlineQueue#promote_without_broadcast` default (inline_queue.rb:127) | `'completed'` silently | → **raise `WalletError`** (no broadcaster + sync broadcast requested) |
+| `InlineQueue#promote_without_broadcast` delayed (inline_queue.rb:127) | `'unproven'` | → `'unproven'` (sync fallback path per #380) |
+| `SolidQueueAdapter#process_job` success (solid_queue_adapter.rb:~292) | `'completed'` | → `'unproven'` |
+| `SolidQueueAdapter#process_job` failure | `'failed'` | ✓ keep |
+| `promote_no_send` success (wallet_client.rb:1416) | `'unproven'` | ✓ keep |
+| `internalize_action` via `store_action` (wallet_client.rb:306) | `'completed'` unconditional | → `'completed'` if BEEF has merkle proof for subject tx, else `'unproven'` |
+| `store_action` default (wallet_client.rb:1484) | `'completed'` | ✓ keep (tests only use default) |
+
+## Tasks
+
+### Task 1: Add validation in `create_action`
+
+**Modify** `gem/bsv-wallet/lib/bsv/wallet_interface/wallet_client.rb`.
+
+Add a new private method `validate_broadcast_configuration!(args)` called at the top of `create_action` (after `validate_create_action!`):
+
+```ruby
+def validate_broadcast_configuration!(args)
+  no_send = args.dig(:options, :no_send)
+  return if no_send
+  return if @broadcaster
+
+  raise WalletError,
+        'create_action requires a broadcaster for on-chain broadcast. ' \
+        'Pass broadcaster: BSV::Network::ARC.default to WalletClient.new, ' \
+        'or options: { no_send: true } to build a transaction without broadcasting.'
+end
+```
+
+This fails loudly at the call site — not after state has been written to storage.
+
+### Task 2: Fix `InlineQueue` success status
+
+**Modify** `gem/bsv-wallet/lib/bsv/wallet_interface/inline_queue.rb`.
+
+- `broadcast_and_promote` success: change `promote(..., txid)` default from `'completed'` to `'unproven'`. Pass explicit `status: 'unproven'`.
+- `promote_without_broadcast`: remove the silent-`'completed'` branch. This method is now reached only via the `accept_delayed_broadcast: true` + no-broadcaster fallback (per #380 design). Status stays `'unproven'`. If somehow called without `accept_delayed_broadcast`, raise `WalletError` — a defensive guard since Task 1 should catch this upstream.
+- Update docstrings: `'completed'` → `'unproven'` (on-chain but unproven); `'completed'` only after proof monitoring promotes it (future work).
+
+### Task 3: Fix `SolidQueueAdapter` success status
+
+**Modify** `gem/bsv-wallet-postgres/lib/bsv/wallet_postgres/solid_queue_adapter.rb`.
+
+- `process_job` success path: `promote(..., txid)` should use `status: 'unproven'` instead of `'completed'`.
+- Update docstring.
+
+### Task 4: Fix `internalize_action` to check merkle proof
+
+**Modify** `gem/bsv-wallet/lib/bsv/wallet_interface/wallet_client.rb` `internalize_action` (line ~267) and/or `store_proofs_from_beef` / `extract_subject_transaction` / `find_by_subject_txid`.
+
+- Determine whether the BEEF contains a merkle proof (BUMP) for the subject transaction.
+- If yes → status = `'completed'`
+- If no → status = `'unproven'`
+- Pass explicit status to `store_action`
+
+Mirrors TS `storage/methods/internalizeAction.ts:301`:
+```typescript
+const status: TransactionStatus = provenTx ? 'completed' : 'unproven'
+```
+
+### Task 5: Update specs
+
+**Modify** existing specs to reflect the new status values. Files identified:
+- `gem/bsv-wallet/spec/bsv/wallet_interface/wallet_client_spec.rb` (2 sites)
+- `gem/bsv-wallet/spec/bsv/wallet_interface/wallet_client_auto_fund_spec.rb` (4 sites)
+- `gem/bsv-wallet/spec/bsv/wallet_interface/inline_queue_spec.rb` (5 sites)
+- `gem/bsv-wallet/spec/bsv/wallet_interface/broadcast_rollback_spec.rb`
+- `gem/bsv-wallet/spec/bsv/wallet_interface/auto_funding_spec.rb`
+- `gem/bsv-wallet/spec/bsv/wallet_interface/wire/serializer_spec.rb`
+- `gem/bsv-wallet-postgres/spec/bsv/wallet_postgres/solid_queue_adapter_spec.rb`
+
+Strategy: global search-and-replace of `'completed'` → `'unproven'` in test expectations where the asserted state is post-broadcast, then review each hit manually to catch exceptions (e.g. `internalize_action` tests with proven BEEFs should stay `'completed'`).
+
+**Add** new specs:
+- `create_action` raises `WalletError` when no broadcaster AND `no_send: false` (default)
+- `create_action` succeeds with `no_send: true` and no broadcaster → status `'nosend'`
+- `create_action` with broadcaster → status `'unproven'` on success
+- `internalize_action` with proven BEEF → `'completed'`
+- `internalize_action` with unproven BEEF → `'unproven'`
+- `SolidQueueAdapter` worker success → status `'unproven'`
+
+### Task 6: Documentation
+
+- **CHANGELOG.md** for `bsv-wallet`: document as breaking change for 0.8.0 with migration notes
+- **gem/bsv-wallet/README.md**: update status meanings table
+- **docs/gems/wallet.md**: add "Status values" section
+- **CLAUDE.md**: no changes needed (general development guidance is already correct)
+
+### Task 7: Downstream coordination
+
+- **bsv-attest**: verify `Attest.publish` callers don't assert `'completed'` — confirmed no assertions, no change needed.
+- **bsv-wallet-postgres**: no schema change (status is TEXT). Bump dependency floor to match new wallet version.
+- **x402-rack, x402-doom**: will need guidance — `'unproven'` is the new "success" state for fresh broadcasts. Document this in the bsv-wallet 0.8.0 release notes.
+
+## Critical files
+
+| File | Action |
+|------|--------|
+| `gem/bsv-wallet/lib/bsv/wallet_interface/wallet_client.rb` | Modify — add `validate_broadcast_configuration!`, fix internalize status logic |
+| `gem/bsv-wallet/lib/bsv/wallet_interface/inline_queue.rb` | Modify — success status + remove silent fallback |
+| `gem/bsv-wallet-postgres/lib/bsv/wallet_postgres/solid_queue_adapter.rb` | Modify — success status |
+| `gem/bsv-wallet/CHANGELOG.md` | Update for breaking change |
+| `gem/bsv-wallet/README.md` | Update status table |
+| `docs/gems/wallet.md` | Add status values section |
+
+## Reference files (read-only)
+
+| File | Why |
+|------|-----|
+| `wallet-toolbox/src/storage/methods/processAction.ts` | Status state machine reference |
+| `wallet-toolbox/src/storage/methods/internalizeAction.ts:301` | Proven vs unproven decision |
+| `wallet-toolbox/src/signer/methods/processAction.ts:147-155` | SendWithResult status mapping |
+
+## Verification
+
+```bash
+cd /opt/ruby/bsv-ruby-sdk
+bundle exec rake spec:wallet           # wallet specs
+bundle exec rake spec:wallet_postgres  # postgres specs (SolidQueueAdapter)
+bundle exec rake                       # full suite
+bundle exec rubocop                    # lint
+```
+
+Manual verification:
+1. Construct `WalletClient.new(key)` (no broadcaster) and call `create_action` with default options → expect `WalletError`
+2. Same + `options: { no_send: true }` → expect success with status `'nosend'`
+3. Construct `WalletClient.new(key, broadcaster: ARC.default)` and call `create_action` → expect status `'unproven'` on success
+4. Internalize a BEEF with merkle proof → action status `'completed'`
+5. Internalize a BEEF without merkle proof → action status `'unproven'`
+
+## Sequencing
+
+```
+Task 1 (create_action guard) ──→ Task 5 (specs update)
+Task 2 (InlineQueue)          ──→ Task 5
+Task 3 (SolidQueueAdapter)    ──→ Task 5
+Task 4 (internalize_action)   ──→ Task 5
+Task 6 (docs)                 ── independent
+Task 7 (downstream floor)     ── last, requires wallet version bump
+```
+
+Tasks 1-4 can be done in parallel (touch different code paths). Task 5 must wait for all of them. Tasks 6-7 are independent bookkeeping.

docs/gems/wallet.md

@@ -148,6 +148,30 @@ wallet.internalize_action({
 })
 ```
 
+## Status meanings
+
+Each action stored by the wallet carries a `status` field that reflects its
+current lifecycle state:
+
+| Status | Meaning |
+|--------|---------|
+| `'nosend'` | Transaction built but not broadcast (caller opted into `options: { no_send: true }`) |
+| `'sending'` | Broadcast queued for background processing (async adapter); worker has not yet attempted broadcast |
+| `'unproven'` | Broadcast succeeded; awaiting merkle proof |
+| `'completed'` | Merkle proof received and stored |
+| `'failed'` | Broadcast attempted and rejected by the network |
+
+> **Note for consumers:** Querying `list_actions(status: 'completed')` returns
+> fewer results under the current taxonomy until a proof-watcher is implemented
+> (out of scope for the current release). Most fresh broadcasts will be in
+> `'unproven'` state until their merkle proof arrives. This aligns with the TS
+> reference SDK's semantics. To find all successfully-broadcast actions, query
+> for both `'unproven'` and `'completed'`, or rely on `'failed'` to detect
+> broadcast rejection.
+
+This taxonomy matches the [wallet-toolbox](https://github.com/bitcoin-sv/wallet-toolbox)
+reference implementation (BRC-100).
+
 ## Balance and UTXOs
 
 ```ruby

gem/bsv-wallet-postgres/lib/bsv/wallet_postgres/solid_queue_adapter.rb

@@ -82,6 +82,15 @@ def async?
         true
       end
 
+      # Returns +true+ — +SolidQueueAdapter+ requires a broadcaster at
+      # construction time (+ArgumentError+ is raised if +nil+ is passed), so
+      # broadcast is always available.
+      #
+      # @return [Boolean]
+      def broadcast_enabled?
+        !@broadcaster.nil?
+      end
+
       # Persists a transaction to the broadcast job queue and returns immediately.
       #
       # Inserts a row into +wallet_broadcast_jobs+ with status +unsent+. If a row
@@ -280,16 +289,18 @@ def process_job(job)
       # Promotes UTXO state after a successful broadcast.
       #
       # Marks inputs as +:spent+, change as +:spendable+, and updates the action
-      # status to +completed+. When outpoints are +nil+ (finalize path), UTXO
-      # transitions are skipped.
+      # status to +unproven+. The transaction has been accepted by the network but
+      # is not yet proven on-chain — status advances to +completed+ once a merkle
+      # proof arrives. When outpoints are +nil+ (finalize path), UTXO transitions
+      # are skipped.
       #
       # @param input_outpoints [Array<String>, nil]
       # @param change_outpoints [Array<String>, nil]
       # @param txid [String, nil]
       def promote(input_outpoints, change_outpoints, txid)
         Array(input_outpoints).each { |op| @storage.update_output_state(op, :spent) }
         Array(change_outpoints).each { |op| @storage.update_output_state(op, :spendable) }
-        @storage.update_action_status(txid, 'completed') if txid
+        @storage.update_action_status(txid, 'unproven') if txid
       end
 
       # Rolls back wallet state after a failed broadcast.

gem/bsv-wallet-postgres/spec/bsv/wallet_postgres/solid_queue_adapter_spec.rb

@@ -259,8 +259,9 @@ def action_status(txid)
       expect(output_state('chg:0').to_s).to eq('spendable')
     end
 
-    it 'updates action status to completed' do
-      expect(action_status(txid_a)).to eq('completed')
+    # Post-HLR #455: 'unproven' until a merkle proof lands via internalize_action
+    it 'updates action status to unproven' do
+      expect(action_status(txid_a)).to eq('unproven')
     end
   end
 
@@ -329,8 +330,9 @@ def action_status(txid)
       adapter.drain
     end
 
-    it 'updates action status to completed' do
-      expect(action_status(txid_a)).to eq('completed')
+    # Post-HLR #455: 'unproven' until a merkle proof lands via internalize_action
+    it 'updates action status to unproven' do
+      expect(action_status(txid_a)).to eq('unproven')
     end
 
     it 'marks job as completed' do

gem/bsv-wallet/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to the `bsv-wallet` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.9.0 (unreleased)
+
+### Changed — **Breaking**
+
+#### Action status taxonomy aligned with BRC-100 reference SDK (HLR #455)
+
+This release realigns the action status values with the wallet-toolbox reference
+implementation. The meaning of `'completed'` has changed — **consumers must
+update any code that checks for `'completed'` as the post-broadcast success
+state**.
+
+| Status | Old meaning | New meaning |
+|--------|-------------|-------------|
+| `'nosend'` | No change | Transaction built but not broadcast (`no_send: true`) |
+| `'sending'` | No change | Async queue accepted; worker has not yet attempted broadcast |
+| `'unproven'` | *(new)* | Broadcast succeeded; awaiting merkle proof |
+| `'completed'` | Broadcast succeeded | **Merkle proof received and stored** |
+| `'failed'` | No change | Broadcast rejected or transaction invalid |
+
+**Migration:**
+
+- Code querying `list_actions(status: 'completed')` will return fewer results
+  until a proof-watcher is implemented (out of scope for this release). To find
+  successfully-broadcast actions that have not yet received a proof, query
+  `status: 'unproven'` instead.
+- `create_action` and `sign_action` now raise `BSV::Wallet::WalletError` when
+  no broadcaster is configured and `options: { no_send: true }` is not set.
+  Previously these calls succeeded silently. To resolve: pass
+  `broadcaster: BSV::Network::ARC.default` to `WalletClient.new`, or pass
+  `options: { no_send: true }` to `create_action` to build without
+  broadcasting.
+- `internalize_action` now sets status to `'completed'` only when the supplied
+  BEEF contains a merkle proof for the subject transaction. Plain BEEF (raw
+  transaction, no BUMP) results in status `'unproven'`.
+- Wallets configured with a `SolidQueueAdapter` satisfy the broadcaster
+  requirement if the adapter carries an embedded `broadcaster:` — the
+  `WalletClient` itself does not need one.
+
+**Related upstream incidents:** x402-rack #148, x402-rack #158, x402-doom #196.
+**Tracking issue:** #455.
+
 ## 0.8.0 — 2026-04-15
 
 ### Added

gem/bsv-wallet/README.md

@@ -55,6 +55,39 @@ broadcasting, and state promotion/rollback automatically.
 | `FileStore` | bsv-wallet | Development (default) |
 | `PostgresStore` | [bsv-wallet-postgres](https://rubygems.org/gems/bsv-wallet-postgres) | Production |
 
+## Status values
+
+Each action stored by the wallet carries one of the following status values:
+
+| Status | Meaning |
+|--------|---------|
+| `'nosend'` | Transaction built but not broadcast (caller opted into `options: { no_send: true }`) |
+| `'sending'` | Broadcast queued for background processing (async adapter); worker has not yet attempted broadcast |
+| `'unproven'` | Broadcast succeeded; awaiting merkle proof |
+| `'completed'` | Merkle proof received and stored |
+| `'failed'` | Broadcast attempted and rejected by the network |
+
+## Broadcaster requirement
+
+A broadcaster is required for `create_action` to succeed unless
+`options: { no_send: true }` is passed per call. Three ways to satisfy this:
+
+1. Pass `broadcaster:` to `WalletClient.new`:
+   ```ruby
+   wallet = BSV::Wallet::WalletClient.new(key, broadcaster: BSV::Network::ARC.default)
+   ```
+2. Pass a `broadcast_queue:` whose adapter has an embedded `broadcaster:`:
+   ```ruby
+   adapter = BSV::Wallet::SolidQueueAdapter.new(db: db, storage: store, broadcaster: arc)
+   wallet = BSV::Wallet::WalletClient.new(key, storage: store, broadcast_queue: adapter)
+   ```
+3. Pass `options: { no_send: true }` to skip broadcast for a specific call:
+   ```ruby
+   wallet.create_action({ description: '...', outputs: [...], options: { no_send: true } })
+   ```
+
+Without one of these, `create_action` raises `BSV::Wallet::WalletError`.
+
 ## Documentation
 
 - [Full documentation](https://sgbett.github.io/bsv-ruby-sdk/)

gem/bsv-wallet/lib/bsv/wallet_interface/broadcast_queue.rb

@@ -68,6 +68,21 @@ def async?
         false
       end
 
+      # Returns +false+ by default — adapters without a broadcaster cannot
+      # broadcast on-chain.
+      #
+      # Override in adapters that hold a broadcaster reference so that
+      # +WalletClient+ can determine broadcast availability from the queue
+      # alone. This is the correct delegation point because users may pass a
+      # broadcaster-equipped queue (e.g.
+      # +SolidQueueAdapter.new(broadcaster: arc)+) without also passing
+      # +broadcaster:+ directly to +WalletClient+.
+      #
+      # @return [Boolean]
+      def broadcast_enabled?
+        false
+      end
+
       # Returns the broadcast status for a previously enqueued transaction.
       #
       # @param _txid [String] hex transaction identifier