Skip to content

feat: wallet-by-wallet basis engine with Form 8949 and Schedule D output - #1

Merged
ralyodio merged 1 commit into
mainfrom
worktree-basis-engine-core
Sep 6, 2026
Merged

ralyodio merged 1 commit into
mainfrom
worktree-basis-engine-core

Conversation

@ralyodio

@ralyodio ralyodio commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Phase 0 of the AI tax filing plan: the computation everything else is downstream of. Pure, deterministic, dependency-free — and with no model in the path, it carries no IRC §7216 disclosure surface.

What it encodes

  • Wallet-scoped lot pools. A disposal may only consume lots sitting in its own wallet. Rev. Proc. 2024-28 ended universal basis pooling, and this is the rule the library exists to enforce.
  • Covered-security determination. Covered only when all three hold: acquired at a broker wallet, on or after 2026-01-01, and never transferred. Moving a lot out of a broker clears the flag, because no broker knows its basis afterwards.
  • Form 8949 box selection (A–F) from term × 1099 expectation × covered status, with per-box totals carried onto the matching Schedule D lines (1b, 2, 3 / 8b, 9, 10).
  • Holding period. Long-term needs more than one year — bought 1 Jan, sellable long-term from 2 Jan the next year.
  • Transfers are not dispositions. Basis and acquisition date survive the move; a network fee paid in the asset is its own disposal.
  • Missing basis is surfaced, not invented. A shortfall becomes a flagged zero-basis short-term lot with UNKNOWN in the date-acquired column, plus a warning. strict: true throws instead.

Correctness

Money and quantities are scaled bigints (6 and 18 decimals), never floats. A fully consumed lot hands over every remaining micro-dollar, so lot splits cannot create or destroy basis. Rows round to cents individually and totals sum the rounded rows, so a printed page always reconciles.

37 tests, all passing, covering the holding-period boundary, wallet isolation, basis conservation across repeated partial disposals, proceeds allocation with no drift, and all six box combinations.

Toolchain note

Tests run on node:test using Node's native TypeScript type stripping. That drops vitest and esbuild entirely, which also sidesteps pnpm 11 refusing to run build scripts without approval — pnpm run <script> was failing on ERR_PNPM_IGNORED_BUILDS before this change.

Not included, deliberately

Wash sales (§1091 covers stock and securities), income recognition for staking/mining/airdrops, and price lookup. Each would change reported numbers on a judgment call that belongs upstream.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R8AUW9tvZThwikBRgqVHLg

Phase 0 of the AI tax filing plan: the computation the whole thing is
downstream of. No LLM in the path, so no section 7216 disclosure surface.

Encodes the rules that are easy to get wrong:

- Wallet-scoped lot pools. A disposal may only consume lots in its own
  wallet (Rev. Proc. 2024-28 ended universal pooling).
- Covered-security determination: broker wallet AND acquired on or after
  2026-01-01 AND never transferred. Moving a lot out of a broker clears
  it, because no broker knows its basis afterwards.
- Form 8949 box selection (A-F) from term, 1099 expectation and covered
  status; totals carried onto the matching Schedule D lines.
- Long-term needs MORE than one year, not exactly one year.
- Transfers preserve basis and acquisition date and are not dispositions,
  but a network fee paid in the asset is.
- Missing basis is surfaced as a flagged zero-basis lot, never invented.

Money and quantities are scaled bigints, never floats. A fully consumed
lot hands over its remaining micro-dollars, so lot splits cannot create
or destroy basis. Rows round to cents individually and totals sum the
rounded rows, so a printed page reconciles.

Tests run on node:test via native type stripping: no vitest, no esbuild,
and therefore no pnpm build-script approval needed in CI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8AUW9tvZThwikBRgqVHLg
@ralyodio
ralyodio merged commit 82d5feb into main Sep 6, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant