@plan-fi/imports 0.6.0

package/docs/ADAPTER_GUIDE.md

@@ -0,0 +1,244 @@
+# ADAPTER_GUIDE.md — how to write a planfi-import adapter
+
+This guide is written to be followed **step by step by an AI coding agent** (it works for humans
+too). Every requirement stated here is enforced by an executable test — the generic contract
+harness `test/adapter-contract.test.mjs` IS this guide's checklist. If the harness passes, you
+followed the guide; if you change one, change the other.
+
+Read `AGENTS.md` first for the invariants. Short version: adapters translate ONE provider's
+vocabulary into the Canonical Financial Profile (CFP); all planfi domain logic lives once in
+`src/to-planfi.mjs`; never fabricate values; zero runtime dependencies.
+
+```
+provider raw ──your normalize()──► CFP ──toPlanfiPlan() (shared, DON'T touch)──► wire body
+```
+
+## 1. The canonical model (what you must emit)
+
+Source of truth: `src/canonical.ts` (types only). Your `normalize(raw)` returns a
+`CanonicalFinancialProfile`:
+
+| Field | Type | Meaning | Who sets it |
+|---|---|---|---|
+| `source` | `string` | Your adapter id (must equal the `ADAPTERS` key and `adapter.source`) | adapter |
+| `asOf` | ISO string | Snapshot timestamp. Use `raw.asOf \|\| defaultAsOf()` — NEVER a hardcoded epoch | adapter |
+| `owner` | `OwnerContext` | Ages/goals/salary/state from onboarding. Pass through `{ ...(raw.owner ?? {}) }` untouched | caller (via adapter passthrough) |
+| `accounts` | `CanonicalAccount[]` | One entry per provider account (see below) | adapter |
+| `meta.warnings` | `ImportWarning[]` | Structured judgment calls — build with `warning()` from `src/util.mjs` | adapter (mapper appends its own) |
+| `meta.unmapped` | `unknown[]` | Raw entities you could NOT map. Push them here; never drop silently | adapter |
+
+`CanonicalAccount`:
+
+| Field | Type | Meaning | Who sets it |
+|---|---|---|---|
+| `id` | `string` (required, non-empty) | Stable provider account id — `String()`-coerce it | adapter |
+| `institution` | `string?` | Institution name/id when the provider carries one | adapter |
+| `name` | `string?` | Human account name | adapter |
+| `class` | `'depository' \| 'investment' \| 'loan' \| 'credit' \| 'property'` | From `classify()` | adapter (via `classify()`) |
+| `subtype` | `string?` | Provider subtype, lowercased (`'401k'`, `'roth ira'`, `'mortgage'`) | adapter |
+| `taxTreatment` | `'taxable' \| 'traditional' \| 'roth' \| 'hsa' \| '529' \| 'na'` | From `classify()` | adapter (via `classify()`) |
+| `balance` | `number` (required, finite) | Asset value, or outstanding principal for a liability — **positive for debts**: take `Math.abs()` on loan/credit balances | adapter |
+| `currency` | `string?` | ISO code, default `'USD'` | adapter |
+| `holdings` | `CanonicalHolding[]?` | Investment accounts only: `{ ticker?, name?, quantity?, value?, costBasis?, assetType }`. `costBasis` missing → leave `undefined` + `NO_COST_BASIS` info warning. `assetType` via `classifyAsset()` | adapter |
+| `liability` | `LiabilityDetail?` | Loan/credit only: `{ rate?, minPayment?, monthsRemaining?, originationPrincipal?, assetName?, assetValue? }`. `rate` is a **FRACTION** (use `pct()`: `6.25` → `0.0625`). `monthsRemaining` via `monthsBetween(raw.asOf, maturityDate)` | adapter |
+| `ownerIndex` | `number?` (0-based int) | Which earner owns the account in a joint household; default `0` | adapter (caller-supplied field) |
+| `estMonthlyContribution` | `number?` (>= 0) | Inferred monthly savings into this account, from `contributionsByAccount()` | adapter |
+
+Everything downstream — tax buckets, the stocks total, 80%-LTV home estimates, IRS-limit clamps,
+`needsInput` asks, the wire body — is `toPlanfiPlan()`'s job. **Do not** duplicate any of it.
+
+## 2. The adapter contract
+
+```ts
+export const <source>Adapter = {
+  source: '<source>',                    // adapter id, lowercase, matches file name
+  normalize(raw): CanonicalFinancialProfile,
+};
+```
+
+`normalize` MUST be:
+
+- **Total** — any input (`null`, `undefined`, primitives, arrays with `null` members, truncated
+  garbage) returns a valid CFP; never throws. Start with
+  `raw = raw && typeof raw === 'object' ? raw : {};` and use `objs()` (from `src/util.mjs`) at
+  every provider-array boundary — it drops non-object members that would otherwise crash property
+  access.
+- **Deterministic** — same input, same output. The only allowed nondeterminism is
+  `defaultAsOf()` (= now) when the payload carries no `asOf`.
+- **Honest** — a guessed classification always emits `CLASSIFICATION_GUESSED`; unmappable raw
+  entities go to `meta.unmapped`; nothing is invented.
+
+## 3. Start from the template
+
+Copy `src/adapters/_template.mjs` → `src/adapters/<source>.mjs`. It is a fully commented skeleton
+that returns an empty-but-structurally-valid CFP; the TODO comments walk you through transactions
+→ contribution inference → account mapping. As shipped it would fail the harness's fixture-content
+floor (≥ 3 accounts) — that failure is your to-do list. The template itself is **not registered**
+in `ADAPTERS` and must stay that way (a harness test asserts it).
+
+Model implementations, most useful first: `src/adapters/fdx.mjs` (wrapped entities, container
+fallbacks), `finicity.mjs` (flat entities, epoch dates), `mx.mjs` (property accounts),
+`csv.mjs`/`ofx.mjs` (keyless file parsing).
+
+## 4. Classification cheat sheet
+
+Call `classify(type, subtype)` with a generic `type` of `'depository' | 'investment' | 'loan' |
+'credit'` (also accepts `'brokerage'` as investment) and a lowercase `subtype`. Build a lookup
+table from YOUR provider's vocabulary to these words (see `FDX_TYPE` in `fdx.mjs`). Words
+`classify()` understands inside `subtype`:
+
+| You want | Subtype words that get there | Confidence |
+|---|---|---|
+| depository (cash) | any subtype under type `depository` (`checking`, `savings`, `cd`, `money market`) | high |
+| investment / hsa | `hsa` (under `depository` OR `investment`) | high |
+| investment / 529 | `529`, `education savings` | high |
+| investment / roth | anything containing `roth` (`roth ira`, `roth 401k`) | high |
+| investment / traditional | `401k`, `403b`, `457b`, `401a`, `ira` (word), `sep`, `simple`, `keogh`, `thrift`, `tsp`, `retirement` | high |
+| investment / traditional (guess) | `tax-deferred`, `pension` | **low → warn** |
+| investment / taxable | `brokerage`, `mutual fund`, `cash management`, `stock plan`, `crypto`, `ugma`, `utma`, `other` | high |
+| investment / taxable (guess) | `non-taxable brokerage`, any unknown subtype, any unknown top-level type | **low → warn** |
+| loan / credit | type `loan` / `credit` (any subtype; use `mortgage`, `home equity`, `student`, `auto` — the mapper routes `mortgage\|home equity` to real estate, everything else to debts) | high |
+
+Whenever `classify()` returns `confidence: 'low'` — or your provider's type wasn't in your lookup
+table at all — emit `CLASSIFICATION_GUESSED` (severity `warn`) naming the account and the guess.
+
+For holdings, `classifyAsset(securityType)` understands: `etf`, `mutual fund`, `equity`/`stock`/
+`common stock`, `fixed income`/`bond`, `cash`/`cash equivalent`, `crypto*`, `derivative` →
+otherwise `'other'`. Translate your provider's holding-type enum into those words first (see
+`FDX_HOLDING_TYPE`).
+
+## 5. Warning-code catalog (when to emit each)
+
+Codes live in the append-only `WarningCode` union in `src/canonical.ts` (mirrored in
+`planfi-import.d.ts` — a harness test compares the two). Codes an **adapter** emits:
+
+| Code | Severity | Emit when |
+|---|---|---|
+| `CLASSIFICATION_GUESSED` | warn | `classify()` returned low confidence, or the provider type wasn't in your lookup table, or you typed an account from its NAME |
+| `NO_COST_BASIS` | info | A holding has no cost basis in the source. One per holding (API adapters) or one per account (structural to the format, e.g. OFX) |
+| `COARSE_INFERENCE` | warn | Contribution inference counted deposits that carried NO category/description/type label. Emit ONCE per import, not per transaction |
+| `CSV_UNMAPPED_COLUMNS` | warn | (csv adapter) columns matched no dialect mapping; name them in the message |
+| `CSV_TRANSACTIONS_ONLY` | warn | (csv adapter) the file's TOOL structurally exports no balances (e.g. a YNAB register) — the user must pair it with a balances source |
+
+Codes the **shared mapper** emits (never emit these from an adapter — they fire automatically
+when your CFP is right): `CONTRIBUTION_CLAMPED`, `CONTRIBUTION_IMPLAUSIBLE`,
+`HSA_FOLDED_INTO_PORTFOLIO`, `HSA_COVERAGE_ASSUMED`, `IRA_SPLIT_ASSUMED`, `HOME_VALUE_ESTIMATED`,
+`MORTGAGE_SKIPPED`, `NEGATIVE_BALANCE_CLAMPED`, `DEBT_RATE_MISSING`.
+
+Need a genuinely new code? Append it to BOTH `src/canonical.ts` and `planfi-import.d.ts`, document
+it in the README catalog, and never change the meaning of an existing code.
+
+`needsInput` is emitted by the mapper only, from the `NeedsInputField` enum:
+`age | retirement_age | annual_salary | desired_annual_spend | home_value | debt_rate`. Your job
+is merely to NOT fill gaps that trigger them (e.g. leave `liability.rate` undefined when the
+provider has no APR — the mapper then models 0% AND asks).
+
+## 6. Contribution inference (if your provider has transactions)
+
+Normalize provider transactions to `{ account_id, subtype: 'contribution', amount: -|x|, date }`
+and run `contributionsByAccount()` — copy the pattern from `fdx.mjs`. Rules (identical in every
+adapter):
+
+1. Only money flowing INTO **investment** accounts counts.
+2. Dividends/interest/capital gains/reinvestments are GROWTH → exclude (already modeled by
+   `annual_return`).
+3. A labeled deposit that is neither growth nor a recognized inflow word → exclude.
+4. An UNLABELED deposit → include, and emit `COARSE_INFERENCE` once.
+5. Money out (debits/withdrawals) never counts.
+
+## 7. Fixture requirements (enforced by the harness)
+
+Create `fixtures/<source>-sandbox.mjs` exporting **`<source>Raw`** (exact name — the CLI `demo`
+command imports it by convention). The fixture MUST:
+
+- carry an explicit ISO `asOf` (determinism: without it, `normalize()` stamps "now"),
+- carry `owner` with at least one named earner (age, retirementAge, annualSalary) — the demo must
+  print a full plan,
+- produce **≥ 3 accounts**, at least one of class `investment`,
+- exercise **at least one warning path** end-to-end (a no-cost-basis holding, an unknown-type
+  account, a mortgage without a property value, a debt without an APR — pick several; the shipped
+  fixtures each exercise most of them),
+- be synthetic (no real customer data), shaped like the provider's REAL response fields.
+
+## 8. Registration checklist
+
+Wire the adapter everywhere (the harness fails with a pointed message for most omissions):
+
+1. `src/adapters/<source>.mjs` — the adapter.
+2. `src/index.mjs` — named export + entry in `ADAPTERS` (key === `adapter.source`).
+3. `planfi-import.d.ts` — `export declare const <source>Adapter: SourceAdapter<object>;` and add
+   the id to the `importToPlan` source union.
+4. `bin/planfi-import.mjs` — add the id to the USAGE source lists.
+5. `fixtures/<source>-sandbox.mjs` — the fixture (section 7).
+6. `test/helpers/fixture-registry.mjs` — register the fixture (this feeds BOTH wire-conformance
+   and the contract harness).
+7. `test/<source>.test.mjs` — source-specific tests: vocabulary mapping, sign conventions, date
+   handling, contribution inference, and one `importToPlan('<source>', fixture)` smoke test.
+8. `test/fuzz.test.mjs` — a `<source>Payload()` generator + a row in the adapter loop.
+9. `README.md` — a row in the Adapters table.
+10. `CHANGELOG.md` — an entry under the next version.
+
+## 9. SELF-VERIFICATION CHECKLIST (run these; expected outputs given)
+
+Run from the `planfi-import/` directory.
+
+```bash
+# 1. Install test-only dev deps (runtime stays zero-dependency)
+npm ci
+# expected: exits 0
+
+# 2. The generic contract harness — YOUR adapter appears in its output
+node --test test/adapter-contract.test.mjs
+# expected: "# fail 0", and for your <source> these subtests all "ok":
+#   [contract:<source>] adapter identity + registration shape
+#   [contract:<source>] (e) a sandbox fixture is registered for wire-conformance
+#   [contract:<source>] (a) normalize(fixture) → structurally valid CFP + content floor
+#   [contract:<source>] (b) toPlanfiPlan(fixture CFP) succeeds; diagnostics use the catalog
+#   [contract:<source>] (c) hostile inputs never throw and still yield clean plans
+#   [contract:<source>] (d) determinism: identical runs → deep-equal output
+
+# 3. The whole suite (per-adapter tests, fuzz, CLI spawns, wire-conformance)
+node --test
+# expected: "# fail 0" (150+ tests). In the standalone repo, wire-conformance
+# prints a loud SKIP about the monorepo mapper — that is expected, not a failure.
+
+# 4. The CLI demo runs your fixture offline and emits valid JSON
+node bin/planfi-import.mjs demo --source <source> --json | node -e \
+  "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const r=JSON.parse(s);
+   if(r.cfp.source!=='<source>'||!r.plan.earners.length) process.exit(1);
+   console.log('demo OK:', r.plan.stocks.current_value)})"
+# expected: "demo OK: <a positive number>", exit 0
+
+# 5. The default demo still works (regression guard for the package script)
+npm run demo > /dev/null
+# expected: exits 0
+```
+
+If any step fails, the failure message names the file to fix — the harness messages are written
+to be actionable. Do not weaken a harness assertion to get green; fix the adapter.
+
+---
+
+## Appendix: extending the CSV dialect table (vs writing an adapter)
+
+Field feedback from the first dialect build (2026-07-03). Dialect work is NOT full adapter work —
+only this subset of the checklist applies: the dialect entry in `src/adapters/csv.mjs`, a fixture
+FILE added to `fixtures/csv-sandbox.mjs` (the registry is one-entry-per-adapter — extend the CSV
+fixture, don't add a new registry entry), tests in `test/csv.test.mjs`, README dialect table,
+CHANGELOG. Sections 5 and 9 of this guide apply as written; sections 7–8 mostly do not.
+
+Rules the table's comments encode (now stated here):
+- **Ordering is first-match-wins.** Put SPECIFIC fingerprints (a column name unique to the tool,
+  e.g. Copilot's `parent category`, Empower's `ticker`) ABOVE the generic dialects, and run a
+  collision check against `generic-accounts`/`generic-holdings` before shipping — a name+value
+  file will happily match generic.
+- **Transactions-only tools** (YNAB-style) must set `transactionsOnly` and yield ZERO accounts —
+  emit `CSV_TRANSACTIONS_ONLY`, never fabricate balances from a register.
+- **Balance-history exports** (Monarch-style) collapse to the newest row per account — never sum.
+- **Property-class rows** ('Real Estate', 'Vehicle') route AROUND `classify()` to the `property`
+  class (see the pattern in `mx.mjs` and `csv.mjs` — the classification cheat sheet covers
+  investment/depository/loan/credit only).
+- **Unknown sign conventions**: prefer the mapping whose failure mode excludes inflows
+  (conservative) over one that could fabricate contributions.
+- New warning codes go in `src/canonical.ts` + `planfi-import.d.ts` + the README catalog **and
+  this guide's warning table**.

package/fixtures/csv-sandbox.mjs

@@ -0,0 +1,112 @@
+// CSV-shaped payload for the keyless adapter, exercising SEVEN dialects at once:
+//   files[0] — a Fidelity "Positions" export (Account Number/Account Name/
+//              Symbol/Description/Quantity/Last Price/Current Value/Cost Basis
+//              Total), complete with the real-world noise: a preamble line
+//              before the header, quoted money cells with commas, a "--" cost
+//              basis, a Pending Activity row, and a trailing disclaimer line.
+//              Two accounts live in one file (Fidelity groups by Account
+//              Number): a taxable brokerage and an "Employer 401(k)" whose
+//              type must be guessed from its NAME (positions exports carry no
+//              type column → CLASSIFICATION_GUESSED, always).
+//   files[1] — a generic accounts CSV (Account Name/Type/Balance + optional
+//              Interest Rate/Minimum Payment), with a currency-symbol balance,
+//              a parenthesized-negative card balance, a mortgage with no
+//              property value (→ 80%-LTV estimate), and a stray "Notes"
+//              column that must surface in CSV_UNMAPPED_COLUMNS.
+//   files[2] — a Monarch Money balances download: balance HISTORY (two dated
+//              rows for the Vanguard account — only the newest may survive;
+//              summing history would fabricate a balance) with explicit
+//              Account Type values (no classification guessing).
+//   files[3] — a Monarch Money transactions export: Mint-style signs (money-in
+//              positive), monthly transfers into the Vanguard brokerage, a
+//              "Dividends & Capital Gains" row that must be excluded as
+//              growth, and a negative (sell/withdrawal) row that never counts.
+//   files[4] — a YNAB register export: Outflow/Inflow column PAIR, transfers
+//              into the Roth IRA (matched to files[1] by account name), a
+//              balance-adjustment row (market growth — excluded), and the
+//              structural CSV_TRANSACTIONS_ONLY warning (YNAB carries no
+//              balances).
+//   files[5] — an Empower (Personal Capital) holdings export: Account column
+//              groups rows, no Cost Basis column → NO_COST_BASIS per holding,
+//              account typed from its NAME ("Rollover IRA" → traditional).
+//   files[6] — a Copilot Money transactions export (community-documented,
+//              low-confidence dialect): INVERTED signs (spending positive,
+//              money-in negative), transfers into the Schwab account from
+//              files[2], a dividend row excluded as growth.
+
+const fidelityPositions = [
+  'Positions for account(s) as of Jul-02-2026',
+  'Account Number,Account Name,Symbol,Description,Quantity,Last Price,Current Value,Cost Basis Total,Type',
+  'Z12345678,Individual Brokerage,VTI,VANGUARD TOTAL STOCK MARKET ETF,420,$305.12,"$128,150.40","$95,000.00",Cash',
+  'Z12345678,Individual Brokerage,SPAXX**,FIDELITY GOVERNMENT MONEY MARKET,5200,$1.00,"$5,200.00",--,Cash',
+  'Z12345678,Individual Brokerage,Pending Activity,,,,"$250.00",,',
+  'X98765432,Employer 401(k),FXAIX,FIDELITY 500 INDEX FUND,850,$211.76,"$179,996.00","$140,000.00",Cash',
+  '',
+  '"The data and information in this spreadsheet is provided to you solely for your use."',
+].join('\r\n');
+
+const genericAccounts = [
+  'Account Name,Type,Balance,Interest Rate,Minimum Payment,Notes',
+  'Everyday Checking,Checking,"$8,450.25",,,primary household account',
+  'High-Yield Savings,Savings,"$32,000.00",,,',
+  'Roth IRA,Roth IRA,"$54,000.00",,,',
+  'College Fund,529,"$21,500.00",,,for Sam',
+  'Home Mortgage,Mortgage,"$310,000.00",5.25%,"$1,980.00",30yr fixed',
+  'Rewards Visa,Credit Card,"($1,850.00)",21.99%,$50.00,carries a balance',
+].join('\n');
+
+const monarchBalances = [
+  'Date,Account,Account Type,Institution,Balance',
+  '2026-06-30,Vanguard Brokerage,Brokerage,Vanguard,"$61,000.00"', // stale history row — must lose
+  '2026-07-01,Vanguard Brokerage,Brokerage,Vanguard,"$62,400.00"',
+  '2026-07-01,Schwab Taxable,Brokerage,Charles Schwab,"$18,000.00"',
+  '2026-07-01,Ally Savings,Savings,Ally Bank,"$12,000.00"',
+].join('\n');
+
+const monarchTransactions = [
+  'Date,Merchant,Category,Account,Original Statement,Notes,Amount,Tags',
+  ...['2026-01-05', '2026-02-05', '2026-03-05', '2026-04-05', '2026-05-05', '2026-06-05']
+    .map((d) => `${d},Vanguard,Transfer,Vanguard Brokerage,VANGUARD BUY INVESTMENT,,"$1,250.00",`),
+  '2026-03-12,Vanguard,Dividends & Capital Gains,Vanguard Brokerage,VANGUARD DIV PAYMENT,,$180.00,', // growth → excluded
+  '2026-04-20,Vanguard,Transfer,Vanguard Brokerage,VANGUARD SELL,,"-$400.00",',                      // money out → excluded
+].join('\n');
+
+const ynabRegister = [
+  '"Account","Flag","Date","Payee","Category Group/Category","Category Group","Category","Memo","Outflow","Inflow","Cleared"',
+  ...['01/12/2026', '02/12/2026', '03/12/2026', '04/12/2026', '05/12/2026', '06/12/2026']
+    .map((d) => `"Roth IRA",,"${d}","Transfer : Everyday Checking",,,,"monthly Roth transfer","$0.00","$450.00","Cleared"`),
+  '"Roth IRA",,"03/28/2026","Reconciliation Balance Adjustment",,,,"market growth","$0.00","$1,200.00","Reconciled"', // adjustment ≠ contribution
+  '"Everyday Checking",,"02/03/2026","Grocery Store","Everyday Expenses: Groceries","Everyday Expenses","Groceries",,"$142.19","$0.00","Cleared"',
+].join('\n');
+
+const empowerHoldings = [
+  'Account,Ticker,Name,Shares,Price,Change,1 Day %,1 Day $,Value',
+  'Empower Rollover IRA,VTI,Vanguard Total Stock Market ETF,100,"$305.12","$1.20","0.39%","$120.00","$30,512.00"',
+  'Empower Rollover IRA,VBTLX,Vanguard Total Bond Market Index,500,"$10.50","-$0.02","-0.19%","-$10.00","$5,250.00"',
+].join('\n');
+
+const copilotTransactions = [
+  'date,name,amount,status,category,parent category,excluded,tags,type,account,account mask,note,recurring',
+  ...['2026-02-10', '2026-03-10', '2026-04-10', '2026-05-10']
+    .map((d) => `${d},Schwab Transfer,-500.00,posted,Transfers,Transfers,false,,internal transfer,Schwab Taxable,1234,,monthly`),
+  '2026-04-15,Schwab Dividend,-75.00,posted,Dividends,Investment,false,,income,Schwab Taxable,1234,,',    // growth → excluded
+  '2026-03-22,Chipotle,18.40,posted,Restaurants,Food,false,,regular,Everyday Checking,5678,,',            // spending (positive) → excluded
+].join('\n');
+
+export const csvRaw = {
+  asOf: '2026-07-02T00:00:00.000Z',
+  owner: {
+    desiredAnnualSpend: 80000,
+    filingState: 'WA',
+    earners: [{ name: 'Jordan', age: 39, retirementAge: 60, annualSalary: 165000 }],
+  },
+  files: [
+    { name: 'fidelity-positions.csv', content: '\uFEFF' + fidelityPositions }, // BOM, the Excel way
+    { name: 'accounts.csv', kind: 'accounts', content: genericAccounts },
+    { name: 'monarch-balances.csv', content: monarchBalances },
+    { name: 'monarch-transactions.csv', content: monarchTransactions },
+    { name: 'ynab-register.csv', content: ynabRegister },
+    { name: 'empower-holdings.csv', content: empowerHoldings },
+    { name: 'copilot-transactions.csv', content: copilotTransactions },
+  ],
+};

package/fixtures/fdx-sandbox.mjs

@@ -0,0 +1,67 @@
+// FDX (Financial Data Exchange)-shaped payload, trimmed to the fields the
+// adapter reads. Mirrors the FDX API conventions:
+//   accounts     — GET /accounts: each account WRAPPED in its shape key
+//                  ({ depositAccount }, { investmentAccount }, { loanAccount },
+//                  { locAccount }), accountType UPPERCASE, currentValue /
+//                  currentBalance / principalBalance per shape, ISO dates
+//   holdings     — flattened InvestmentHolding[] from the account-details
+//                  calls, each tagged with its accountId (holdingType,
+//                  symbol, units, marketValue, costBasis)
+//   transactions — wrapped { investmentTransaction } records with
+//                  debitCreditMemo + ISO postedTimestamp
+//
+// Two-earner household with one of each interesting account: HSA, 529,
+// mortgage (FDX has no property entity → exercises the 80%-LTV estimate),
+// student loan, a credit card with NO APR on record, a no-cost-basis
+// DIGITALASSET holding, and an unknown-accountType account.
+
+export const fdxRaw = {
+  asOf: '2026-07-02T00:00:00.000Z',
+  owner: {
+    desiredAnnualSpend: 92000, filingState: 'NY',
+    earners: [
+      { name: 'Avery', age: 44, retirementAge: 63, annualSalary: 200000 },
+      { name: 'Morgan', age: 42, retirementAge: 63, annualSalary: 118000 },
+    ],
+  },
+  accounts: [
+    { depositAccount: { accountId: 'fdx-chk', accountType: 'CHECKING', nickname: 'Everyday Checking', currentBalance: 16800, currency: { currencyCode: 'USD' } } },
+    // interestRate on a depositAccount is a savings YIELD — must NOT become a debt APR.
+    { depositAccount: { accountId: 'fdx-sav', accountType: 'SAVINGS', nickname: 'Emergency Savings', currentBalance: 54000, interestRate: 4.2 } },
+    { investmentAccount: { accountId: 'fdx-brk', accountType: 'BROKERAGE', nickname: 'Joint Brokerage', currentValue: 295000, ownerIndex: 0 } },
+    { investmentAccount: { accountId: 'fdx-401k', accountType: '401K', nickname: 'Acme 401(k)', currentValue: 380000, ownerIndex: 0 } },
+    { investmentAccount: { accountId: 'fdx-roth', accountType: 'ROTH', nickname: 'Roth IRA', currentValue: 81000, ownerIndex: 1 } },
+    { investmentAccount: { accountId: 'fdx-hsa', accountType: 'HSA', nickname: 'Health Savings', currentValue: 24000 } },
+    { investmentAccount: { accountId: 'fdx-529', accountType: '529', nickname: 'College 529', currentValue: 36000 } },
+    // Unknown accountType → the investmentAccount container is the fallback
+    // class signal; taxable at LOW confidence + CLASSIFICATION_GUESSED.
+    { investmentAccount: { accountId: 'fdx-mystery', accountType: 'DIGITALWALLET', nickname: 'Mystery Wallet', currentValue: 9000 } },
+    // FDX has no property entity → the mapper estimates the home value (80% LTV).
+    { loanAccount: { accountId: 'fdx-mtg', accountType: 'MORTGAGE', nickname: 'Home Mortgage', principalBalance: 405000, interestRate: 5.25, nextPaymentAmount: 2750, originalPrincipal: 480000, maturityDate: '2049-04-01' } },
+    { loanAccount: { accountId: 'fdx-stu', accountType: 'STUDENTLOAN', nickname: 'Grad Student Loan', principalBalance: 27000, interestRate: 4.6, nextPaymentAmount: 320 } },
+    // Card with NO APR on record → DEBT_RATE_MISSING + a debt_rate ask.
+    { locAccount: { accountId: 'fdx-card', accountType: 'CREDITCARD', nickname: 'Travel Card', currentBalance: 3400, minimumPaymentAmount: 85 } },
+  ],
+  holdings: [
+    { accountId: 'fdx-brk', holdingId: 'h1', symbol: 'VTI', securityName: 'Vanguard Total Stock Market ETF', holdingType: 'ETF', units: 780, marketValue: 238000, costBasis: 170000 },
+    // No cost basis reported → NO_COST_BASIS warning; DIGITALASSET → speculative.
+    { accountId: 'fdx-brk', holdingId: 'h2', symbol: 'ETH', securityName: 'Ether', holdingType: 'DIGITALASSET', units: 12, marketValue: 57000, costBasis: null },
+    { accountId: 'fdx-401k', holdingId: 'h3', symbol: 'FXAIX', securityName: 'Fidelity 500 Index Fund', holdingType: 'MUTUALFUND', units: 1795, marketValue: 380000, costBasis: 290000 },
+  ],
+  transactions: [
+    // Monthly credits Jan–Jun 2026 (ISO timestamps — the FDX way).
+    ...credits('fdx-brk', 2200, { description: 'ACH TRANSFER IN' }),
+    ...credits('fdx-401k', 1650, { transactionType: 'CONTRIBUTION' }),
+    ...credits('fdx-roth', 500, { transactionType: 'CONTRIBUTION' }),
+    // A dividend credit that must be EXCLUDED from contribution inference.
+    { investmentTransaction: { transactionId: 'fdx-div-1', accountId: 'fdx-brk', transactionType: 'DIVIDEND', totalAmount: 700, debitCreditMemo: 'CREDIT', postedTimestamp: '2026-03-20T00:00:00.000Z', description: 'VTI dividend' } },
+  ],
+};
+
+function credits(accountId, amount, extra) {
+  return ['2026-01-15', '2026-02-15', '2026-03-15', '2026-04-15', '2026-05-15', '2026-06-15']
+    .map((d, i) => ({ investmentTransaction: {
+      transactionId: `${accountId}-t${i + 1}`, accountId, totalAmount: amount,
+      debitCreditMemo: 'CREDIT', postedTimestamp: `${d}T00:00:00.000Z`, ...extra,
+    } }));
+}

package/fixtures/finicity-sandbox.mjs

@@ -0,0 +1,62 @@
+// Finicity (Mastercard Open Banking)-shaped payload, trimmed to the fields the
+// adapter reads. Mirrors documented Finicity response shapes:
+//   accounts     — GET /aggregation/v1/customers/{id}/accounts (type, balance,
+//                  detail{} for loans/cards)
+//   positions    — flattened investment position[] from the account-details
+//                  calls, each tagged with its accountId
+//   transactions — GET /aggregation/v3/customers/{id}/transactions
+//                  (amounts positive = deposit; dates are EPOCH SECONDS)
+//
+// Two-earner household with one of each interesting account: HSA, 529,
+// mortgage (no property record — Finicity has none, exercises the 80%-LTV
+// estimate), student loan, a negative-reported credit card with no APR, a
+// no-cost-basis crypto holding, and a low-confidence investmentTaxDeferred
+// wrapper.
+
+const epoch = (iso) => Math.floor(Date.parse(iso) / 1000);
+
+export const finicityRaw = {
+  asOf: '2026-07-02T00:00:00.000Z',
+  owner: {
+    desiredAnnualSpend: 88000, filingState: 'CO',
+    earners: [
+      { name: 'Riley', age: 43, retirementAge: 62, annualSalary: 190000 },
+      { name: 'Casey', age: 41, retirementAge: 62, annualSalary: 105000 },
+    ],
+  },
+  accounts: [
+    { id: 5001, name: 'Everyday Checking', type: 'checking', balance: 14200, currency: 'USD', institutionId: 101732 },
+    { id: 5002, name: 'Online Savings', type: 'savings', balance: 48000 },
+    { id: 5003, name: 'Taxable Brokerage', type: 'brokerageAccount', balance: 268000, ownerIndex: 0 },
+    { id: 5004, name: 'Employer 401(k)', type: '401k', balance: 350000, ownerIndex: 0 },
+    { id: 5005, name: 'Roth IRA', type: 'roth', balance: 74000, ownerIndex: 1 },
+    { id: 5006, name: 'Health Savings', type: 'hsa', balance: 26000 },
+    { id: 5007, name: 'College 529', type: '529plan', balance: 38000 },
+    // Pre-tax wrapper of unknown flavor → traditional at LOW confidence (warned).
+    { id: 5008, name: 'Old Variable Annuity', type: 'investmentTaxDeferred', balance: 45000, ownerIndex: 0 },
+    // Finicity has no property account type → the mapper estimates home value.
+    { id: 5009, name: 'Home Mortgage', type: 'mortgage', balance: 420000, detail: { interestRate: 5.5, payment: 2900, maturityDate: epoch('2048-05-01') } },
+    { id: 5010, name: 'Student Loan', type: 'studentLoan', balance: 31000, detail: { interestRate: 4.8, paymentMinAmount: 340 } },
+    // Negative-reported card balance (institution quirk) and NO APR on record.
+    { id: 5011, name: 'Cashback Card', type: 'creditCard', balance: -2600, detail: {} },
+  ],
+  positions: [
+    { accountId: 5003, id: 9001, symbol: 'VTI', description: 'Vanguard Total Market ETF', units: 900, marketValue: 210000, costBasis: 150000, securityType: 'ETF' },
+    // No cost basis reported → NO_COST_BASIS warning; crypto → speculative.
+    { accountId: 5003, id: 9002, symbol: 'BTC', description: 'Bitcoin', units: 0.55, marketValue: 58000, costBasis: null, securityType: 'Cryptocurrency' },
+    { accountId: 5004, id: 9003, symbol: 'FXAIX', description: 'Fidelity 500 Index', units: 1750, marketValue: 350000, costBasis: 280000, securityType: 'Mutual Fund' },
+  ],
+  transactions: [
+    // Monthly deposits Jan–Jun 2026 (epoch-second dates — the Finicity way).
+    ...deposits(5003, 2100, { categorization: { category: 'Transfer' } }),
+    ...deposits(5004, 1700, { investmentTransactionType: 'contribution' }),
+    ...deposits(5005, 450, { investmentTransactionType: 'contribution' }),
+    // A dividend credit that must be EXCLUDED from contribution inference.
+    { id: 8000, accountId: 5003, amount: 800, transactedDate: epoch('2026-03-20'), categorization: { category: 'Dividends & Interest Income' }, description: 'VTI dividend' },
+  ],
+};
+
+function deposits(accountId, amount, extra) {
+  return ['2026-01-15', '2026-02-15', '2026-03-15', '2026-04-15', '2026-05-15', '2026-06-15']
+    .map((d, i) => ({ id: accountId * 10 + i, accountId, amount, transactedDate: epoch(d), ...extra }));
+}

package/fixtures/mx-sandbox.mjs

@@ -0,0 +1,37 @@
+// MX-Platform-shaped payload (accounts + holdings + transactions), trimmed to
+// the fields the adapter reads. Includes a PROPERTY account (MX gives the home's
+// market value) and an HSA + 529 to exercise the same paths as the Plaid fixture.
+
+export const mxRaw = {
+  asOf: '2026-07-02T00:00:00.000Z',
+  owner: {
+    desiredAnnualSpend: 84000, filingState: 'TX',
+    earners: [{ name: 'Jordan', age: 45, retirementAge: 60, annualSalary: 210000 }],
+  },
+  accounts: [
+    { guid: 'ACT-chk', name: 'Checking', type: 'CHECKING', balance: 21000, currency_code: 'USD' },
+    { guid: 'ACT-sav', name: 'High-Yield Savings', type: 'SAVINGS', balance: 65000 },
+    { guid: 'ACT-brk', name: 'Individual Brokerage', type: 'INVESTMENT', subtype: 'BROKERAGE', balance: 305000 },
+    { guid: 'ACT-401k', name: 'Workplace 401(k)', type: 'INVESTMENT', subtype: '401K', balance: 420000 },
+    { guid: 'ACT-roth', name: 'Roth IRA', type: 'INVESTMENT', subtype: 'ROTH_IRA', balance: 96000 },
+    { guid: 'ACT-hsa', name: 'HSA', type: 'INVESTMENT', subtype: 'HSA', balance: 30000 },
+    { guid: 'ACT-529', name: '529 College', type: 'INVESTMENT', subtype: '529', balance: 52000 },
+    { guid: 'ACT-home', name: 'Primary Home', type: 'PROPERTY', market_value: 1450000 },
+    { guid: 'ACT-mtg', name: 'Primary Home Mortgage', type: 'MORTGAGE', balance: 610000, interest_rate: 5.75, minimum_payment: 3800, original_balance: 700000, maturity_date: '2049-03-01' },
+    { guid: 'ACT-auto', name: 'Auto Loan', type: 'LOAN', balance: 24000, interest_rate: 6.9, minimum_payment: 455 },
+    { guid: 'ACT-cc', name: 'Rewards Card', type: 'CREDIT_CARD', balance: 3100, apr: 22.9, minimum_payment: 75 },
+  ],
+  holdings: [
+    { account_guid: 'ACT-brk', symbol: 'VOO', description: 'Vanguard S&P 500', shares: 500, market_value: 260000, cost_basis: 180000, holding_type: 'ETF' },
+    { account_guid: 'ACT-brk', symbol: 'GBTC', description: 'Grayscale Bitcoin', shares: 100, market_value: 45000, cost_basis: null, holding_type: 'Cryptocurrency' },
+    { account_guid: 'ACT-401k', symbol: 'FXAIX', description: 'Fidelity 500 Index', shares: 2100, market_value: 420000, cost_basis: 300000, holding_type: 'Mutual Fund' },
+  ],
+  transactions: [
+    ...credits('ACT-brk', 2500), ...credits('ACT-401k', 1800),
+  ],
+};
+
+function credits(account_guid, amount) {
+  return ['2026-01-10', '2026-02-10', '2026-03-10', '2026-04-10', '2026-05-10', '2026-06-10']
+    .map((date) => ({ account_guid, type: 'CREDIT', amount, category: 'Transfer', date }));
+}