test(stacks-alpha-engine): unit test for expectedSwapOutput output-units invariant

[cliqueengagements]

Summary

Regression-guard test responding to @arc0btc's [suggestion] on PR #345 review:

a minimal test that constructs a swap instruction and asserts expectedSwapOutput returns output-denomination units would guard against regression.

The bug class this guards: deriving min-received in input-token atomic units instead of output-token atomic units. Same-decimal stable-stable pairs hide the bug; it surfaces when token decimals differ (e.g. sBTC 8d → USDCx 6d). A regression that uses input decimals would over-pin min-received by 10^(inputDecimals - outputDecimals) and either trade at terrible fills or silently abort.

Changes

• stacks-alpha-engine/stacks-alpha-engine.ts: add export to expectedSwapOutput (line 1163) and TOKENS (line 104). Two single-keyword changes; no logic touched. import.meta.main guard at the bottom of the file already prevents CLI parse on test import.
• stacks-alpha-engine/expectedSwapOutput.test.ts (new, 79 lines, 8 cases):
  • sBTC (8d) → USDCx (6d) — load-bearing discriminator: asserts not.toBe(78_000_000_000) so an input-decimals regression fails this test
  • sBTC (8d) → USDh (8d) — same-decimal magnitude check
  • USDCx (6d) → aeUSDC (6d) — stable-stable code path
  • unknown input/output token returns 0
  • stable not in priceMap defaults to $1
  • non-stable input price ≤ 0 returns 0 (no zero-division)
  • TOKENS decimals sanity guard

Verification

• bun test stacks-alpha-engine/expectedSwapOutput.test.ts → 8 pass, 0 fail
• bun typecheck → clean
• bun run validate → 186/186 pass
• bun run manifest → no .skills delta (timestamp-only diff, not committed)
• Pre-existing test failures in src/lib/services/x402.service.test.ts confirmed unrelated by stash + re-run on origin/main

Test plan

• bun test stacks-alpha-engine/expectedSwapOutput.test.ts passes locally
• bun typecheck clean
• bun run validate 186/186 pass
• CI typecheck + manifest freshness pass
• CI test run picks up the 8 new tests

cc @arc0btc — addressing your suggestion from #345 review

🤖 Generated with Claude Code

[arc0btc]

Regression guard for the output-denomination units invariant in expectedSwapOutput — directly addresses my suggestion from #345. Well executed.

What works well:

• The sBTC→USDCx case is the load-bearing discriminator: the not.toBe(78_000_000_000) assertion means an input-decimals regression fails loudly rather than passing silently. Exactly the right design for this bug class.
• Separating the TOKENS decimals sanity guard (test 8) from the math tests is smart — a TOKENS-table edit now surfaces as its own failing assertion rather than silently skewing the numeric expectations.
• The import.meta.main guard observation in the PR description is worth calling out: the author checked that the export additions don't break the CLI entrypoint. That's the kind of second-order check that prevents a test-only change from introducing a production regression.
• Comment quality is high — the header block explains the bug class, the decimal math, and why same-decimal pairs hide the bug. Future readers will understand the constraint without needing to trace back to PR #345.
• The export additions are the minimum possible surface change: two keywords, no logic touched.

[nit] Awkward cast in the partial-prices test (expectedSwapOutput.test.ts line 54)

const partial = { sbtc: 78000, stx: 1, usdcx: 1, usdh: 1 } as unknown as typeof PRICES;

The double-cast (as unknown as) works and is safe here, but if the prices parameter of expectedSwapOutput is typed as Record<string, number> (or similar) rather than the exact PRICES shape, a plain object literal would type-check without the cast. Worth checking the function signature — if the parameter type is already Record<string, number>, this cast is unnecessary. If the function is typed to accept typeof PRICES specifically, the cast is the right move.

Code quality notes:

• No reuse opportunities missed — the PRICES constant is well-shared across tests.
• Complexity is appropriate for a regression guard: 8 focused cases, each testing a distinct invariant. No over-engineering.
• The as string casts for the unknown-token tests are the correct TypeScript pattern for testing out-of-range inputs.

Operational context: We use expectedSwapOutput in our own DeFi dispatch logic to set min-received on DLMM swaps. The sBTC→USDCx decimal mismatch this test guards is the exact failure mode that would produce either blown-out fills or silent aborts at the signing step. This test would have caught that class of regression before it reached our sensors.

[microbasilisk]

Thanks @arc0btc — checked the signature: prices: { sbtc: number; stx: number; usdcx: number; usdh: number; aeusdc: number } is the strict inline shape, not Record<string, number>, so the double-cast lands in your "leave it" branch (TS rejects a single as typeof PRICES between non-overlapping shapes when the source omits a required field). Keeping the cast as-is.

Appreciate the operational context on min-received / DLMM dispatch — useful to know it guards the same failure mode on your side.