Routes preserveUntil, freeze, unfreeze, reassign, setConflicting,
setLocked, incrementSpentExtraRecs (×2), spendMulti, and unspend
through the s.teranodeBatchRecord / s.executeTeranodeOp helpers
added in the previous commit. Each call site shrinks because the
aerospike.NewValue / aerospike.BoolValue wrappers are absorbed by
the helper.

Behavior is unchanged when aerospike_use_native_teranode_ops is
false (the default) or when the cluster's capability probe rejects
the new opcode — both result in the helper producing the same
NewBatchUDF / client.Execute call as before.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The BSV fork of aerospike-client-go-v8 is now published at
github.com/bsv-blockchain/aerospike-client-go/v8 v8.7.1-bsv1 — adds
TeranodeModifyOp / TeranodeReadOp wire opcodes 200/201 alongside
the upstream API.

Mechanical sed across 55 files renaming all imports from
github.com/aerospike/aerospike-client-go/v8 to
github.com/bsv-blockchain/aerospike-client-go/v8. Build, vet, and
the package test suite all green.

Drops the local-filesystem replace directive — the require directive
now resolves directly via the Go module proxy. The previously-pinned
upstream github.com/aerospike/aerospike-client-go/v8 v8.4.2 remains
as an indirect dependency of unrelated transitive imports.

The fork is functionally a strict superset of upstream: when
aerospike_use_native_teranode_ops is false (default) and/or the
cluster's capability probe rejects the new opcode, Teranode's calls
go through unchanged NewBatchUDF / client.Execute paths, behaving
identically to upstream.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Picks up 15d73f5 on the BSV go-client fork which fixes routing
classification for TeranodeReadOp. The original v8.7.1-bsv1 had
TeranodeReadOp falling into the operate_args.go default branch and
being routed via PartitionForWrite because the client uses explicit
op-type switches that didn't include _TERANODE_READ. Caught on PR
review of bsv-blockchain/aerospike-client-go#1.

No source changes here — only the version pin moves and go.sum
updates with the new tarball hash. Build, vet, mod-tidy all green.

Adds aerospike_enable_client_metrics (default true, preserving prior behavior).
When disabled, util/aerospike.go skips client.EnableMetrics(nil) and the stats
polling goroutine entirely.

Motivation: under sustained heavy batch load we have observed thousands of
goroutines blocked on a single sync.RWMutex.Lock() inside aerospike-client-go's
per-node nodeStats updateOrInsert path, called from writeCommand.parseResult
on every batch result. EnableMetrics is what wires that tracking up; turning
it off bypasses the contention point entirely at the cost of losing the
per-cluster Prometheus stats this Go process exposes.

Operational guidance:
- Keep enabled in normal production where observability matters.
- Flip to false on clusters where nodeStats mutex contention is observed
  (goroutine profile shows many waiters on the same mutex address inside
  aerospike-client-go internals) until a client-side fix lands upstream.

…ines

Production observation on dev-scale-2: subtree-validator's "Tx Meta read
from Kafka /second" Grafana panel oscillates between 0 and 2.4M tx/s
with mean ~1.5M, repeatedly dropping to zero. One month ago the same
metric was a steady ~900K/s with no zero-drops. Cache hit rate sits
at ~50% even for new (not-yet-mined) transactions, and subtree
validation takes 30-49s per subtree (target: ~2s).

Root cause is in services/subtreevalidation/txmetaHandler.go:

- Each Kafka message spawns a goroutine via `go func()` (unbounded
  fan-out, since 9f4f1e5 in Dec 2025).
- Each Kafka message carries a binary BATCH of N entries (since
  4dcf264 in Dec 2025), but the handler loops calling
  SetCacheFromBytes once per entry sequentially.
- Each SetCacheFromBytes call takes a per-bucket write lock in
  improved_cache.bucket.Set (improved_cache.go:799).

Under burst load the cumulative effect is thousands of goroutines
serializing through the cache's bucket locks. The cache's own
sharded-bucket parallelism (8192 buckets in SetMulti) is wasted
because each goroutine takes locks one at a time. Throughput
collapses to single-writer speed, recovers when contention drains,
collapses again — the visible 0/2.4M oscillation pattern.

The franz Kafka library switch in #611 (2026-03-27) is the most
likely trigger for the recent regression, but the underlying design
flaw predates that.

Fix:

- New txmetaCacheJob struct: parsed Kafka batch (deep-copied keys/
  values, separated ADD/DELETE).
- Bounded worker pool consumes parsed jobs from a buffered channel.
  Workers call SetCacheMulti ONCE per batch — letting the cache's
  bucket fan-out parallelize internally, taking each touched bucket
  lock once per Kafka message instead of once per entry.
- Handler now does cheap parsing on the Kafka consumer goroutine,
  then enqueues onto the work channel. Channel-full enqueue BLOCKS,
  applying backpressure to Kafka rather than letting goroutines
  pile up unboundedly.
- Shutdown is driven by closing the work channel (not ctx cancel)
  so workers drain queued items before exiting. sync.Once on the
  close keeps Stop() idempotent for tests with deferred cleanup.

Settings:
- subtreevalidation_txmetaCacheKafkaWorkers (default 8)
- subtreevalidation_txmetaCacheKafkaQueueSize (default 256)

Interface:
- SetCacheMulti added to txMetaCacheOps. TxMetaCache already has it.

Tests:
- Existing TestServer_txmetaHandler covers nil/short/ADD/DELETE
  paths; updated to assert SetCacheMulti (not SetCacheFromBytes)
  on ADD and run against the worker pool.
- New TestServer_txmetaHandler_BatchesIntoSingleSetCacheMulti
  guards the regression: 50 entries -> ONE SetCacheMulti call.
- New TestParseTxmetaBatch covers empty/zero-entry/multi-entry/
  truncated batches and verifies keys/values are deep-copied so
  later mutation of the source buffer doesn't corrupt parsed jobs.
- Race detector clean.

Note: this fix does NOT remove the cache writeback in
TxMetaCache.BatchDecorate (cache-aside on store fetches) — that
path is needed for nodes whose Kafka publishers don't carry every
transaction.

Verified: go build, go vet, go test -race for the changed packages
all green; pre-commit hooks pass.

CI on PR #828 caught three e2e tests panicking with "send on closed
channel" originating from txmetaHandler.go:148:

    legacy-sync       TestBIP68_TimeBased_Accept
    smoketest         TestBIP68_HeightBased_Accept
    prunertest        TestPrunerUnminedParentRetention

All three use the in-memory Kafka consumer which delivers a final
message AFTER Server.Stop() has returned from txmetaConsumerClient.
Close(). The handler running on that delivery race-loses with
stopTxmetaCacheWorkers's close(txmetaCacheJobCh) and panics.

Fix: a sync.RWMutex (txmetaCacheCloseMu) plus a closed flag
(txmetaCacheClosed) coordinate the two paths:

- Senders (txmetaHandler) take the read lock, check closed, send.
- Closer (stopTxmetaCacheWorkers) takes the write lock, flips the
  flag, closes the channel — all under the write lock.

Read-lock-then-check-then-send is atomic from the closer's POV: a
sender either sees closed=false and completes its send before the
write lock is granted, or sees closed=true and bails. No path can
land on close(ch) followed by send(ch).

Read locks are uncontended on the steady-state hot path and the
close runs once per Server lifetime, so overhead is negligible.

Test: TestServer_txmetaHandler_ShutdownRace stresses 16 sender
goroutines against a concurrent stop(); 10× -race iterations clean.

Verified:
- go build / go vet — clean
- go test -count=10 -race -run "TestServer_txmetaHandler|
  TestParseTxmetaBatch" ./services/subtreevalidation/ — pass
- Pre-commit hooks — pass

buildOOBFixture and buildInRangeFixture created their SyncedMap with
limit=2 and then inserted exactly 2 entries. The _NilParentTx tests
subsequently Set on an existing key; once len == limit, go-tx-map's
setUnlocked evicts a random item from the map before writing — which
~50% of the time drops the child the SUT is about to look up, leaving
the test failing with "tx <hash> not found in txMap". Reproduced
locally with -count=20 under -race.

Use an unbounded SyncedMap in the fixtures (the production path sizes
by block tx count, not 2) and leave a comment explaining the eviction
trap so future fixtures don't fall into the same hole.

Duplicates the fix in PR #931 so this PR's CI is unblocked
independently; will fold into theirs if #931 lands first.

# Conflicts:
#	go.mod
#	services/legacy/netsync/handle_block_test.go
#	stores/txmetacache/improved_cache_test.go

PR #957 landed on main using the stock aerospike-client-go/v8 import
path. pr-828's whole utxo/aerospike package uses the BSV fork
(github.com/bsv-blockchain/aerospike-client-go/v8), which adds the
TeranodeModifyOp wire opcode that the native-ops path needs. Mixing
stock and fork in the same package would break type compatibility
across files.

Same surgical edit as was applied to spend_expressions.go during the
prior conflict resolution. The BSV fork is API-superset of stock for
everything circuit_breaker.go touches, so the change is import-path-only.

# Conflicts:
#	go.mod
#	go.sum

)