From dcd5885fcc11e88e8b3e611762c4e1eebd13b69b Mon Sep 17 00:00:00 2001 From: Emil Lerch Date: Sat, 25 Jul 2026 11:04:23 -0700 Subject: [PATCH] document in-kind transfer implementation --- AGENTS.md | 2 +- docs/guides/track-contributions.md | 17 +++++- docs/reference/config/transaction-log-srf.md | 58 +++++++++++++++++--- 3 files changed, 66 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 35eea4d..c683a10 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -777,7 +777,7 @@ command. - **Portfolio auto-detection.** Both CLI and TUI resolve `portfolio*.srf` the same way, and it is ZFIN_HOME-exclusive when set: if `$ZFIN_HOME` is set, only that directory is searched (cwd is NOT a fallback - a project directory that incidentally ships a `portfolio.srf` must not shadow the user's canonical data); if `$ZFIN_HOME` is unset, cwd is searched. An explicit `-p` path resolves the same exclusive way. `watchlist.srf` and the `.env` file follow the same rule (`.env` adds process environment variables as a higher-priority tier on top). `metadata.srf` and `accounts.srf` are loaded from the same directory as the resolved portfolio file. -- **`transaction_log.srf` is a sibling file.** Optional. Lives next to `portfolio.srf` / `accounts.srf`. Holds user-declared `transfer::` records so the contributions pipeline can tell internal account-to-account movement apart from real external contributions. Only `type::cash` is wired in v1 - `type::in_kind` parses but is rejected downstream. Missing file -> matcher is a no-op. See `REPORT.md` section 5 "Transfer log" for the user-facing guide. +- **`transaction_log.srf` is a sibling file.** Optional. Lives next to `portfolio.srf` / `accounts.srf`. Holds user-declared `transfer::` records so the contributions pipeline can tell internal account-to-account movement apart from real external contributions. Both `type::cash` (verified against the destination's dollar value, $1 tolerance) and `type::in_kind` (verified against share counts, 1%/0.01-share tolerance) are wired into the classifier. Missing file -> matcher is a no-op. See `docs/reference/config/transaction-log-srf.md` for the user-facing guide. - **Server sync is optional.** The `ZFIN_SERVER` env var enables parallel cache syncing from a remote zfin-server instance. All server sync code silently no-ops when the URL is null. diff --git a/docs/guides/track-contributions.md b/docs/guides/track-contributions.md index 025ce14..f929feb 100644 --- a/docs/guides/track-contributions.md +++ b/docs/guides/track-contributions.md @@ -89,8 +89,21 @@ transfer::2026-05-02,type::cash,amount:num:50000,from::Joint taxable,to::Pat Rot ``` zfin matches the transfer against the diff and removes it from the -attribution total. Only `type::cash` is wired up today; `in_kind` -parses but isn't yet supported. +attribution total. + +If the **securities** moved rather than cash -- an ACAT transfer or an +in-kind rollover -- use `type::in_kind` and point `dest_lot` at the lot +that arrived: + +```srf +transfer::2026-05-02,type::in_kind,amount:num:87000,from::Old 401k,to::Pat Roth,dest_lot::VTI@2024-01-15 +``` + +In-kind records are verified by share count rather than by `amount` +(which is informational there), so the shares that left have to match +the shares that arrived. See the +[reference](../reference/config/transaction-log-srf.md#typecash-vs-typein_kind) +for the exact tolerances and what happens when they don't line up. ## Cash that *is* a contribution diff --git a/docs/reference/config/transaction-log-srf.md b/docs/reference/config/transaction-log-srf.md index f151efb..3f85a2a 100644 --- a/docs/reference/config/transaction-log-srf.md +++ b/docs/reference/config/transaction-log-srf.md @@ -2,8 +2,8 @@ `transaction_log.srf` is an optional sibling of `portfolio.srf` that declares real-world transactions which change how zfin interprets the -portfolio diff. In v1 it holds exactly one kind of record: -**transfers** -- money you moved between accounts you own. +portfolio diff. It holds exactly one kind of record: **transfers** -- +money or securities you moved between accounts you own. ## Why it exists @@ -42,21 +42,63 @@ transfer::2026-05-02,type::cash,amount:num:4700,from::Sample IRA,to::Sample Brok | Field | Type | Required | Description | |------------|--------|----------|---------------------------------------------------------------------| | `transfer` | date | Yes | Transfer date (`YYYY-MM-DD`); the record key. | -| `type` | string | Yes | `cash` or `in_kind` (see v1 scope below). | +| `type` | string | Yes | `cash` (money moved) or `in_kind` (securities moved). See below. | | `amount` | num | Yes | Dollar amount transferred to this destination. | | `from` | string | Yes | Source account name (matches an `account::` in your portfolio). | | `to` | string | Yes | Destination account name. | | `dest_lot` | string | Yes | Where it landed: `cash`, or `SYMBOL@YYYY-MM-DD` for a specific lot. | -## v1 scope and limits +## `type::cash` vs `type::in_kind` + +Both are matched by the contributions classifier; they differ in what +moved and therefore in how the record is verified. + +**`type::cash`** -- dollars left one account and arrived at another, +possibly getting invested on arrival. The `amount` is load-bearing: it's +matched against the destination's value, and the three outcomes are + +- **within $1** -- fully a transfer; contributes $0 to attribution. +- **destination worth more than `amount`** -- a *partial* transfer. Only + `amount` is cancelled out; the excess is still counted as new money. + That's the "I moved $5k in and also added $2k of my own" case. +- **`amount` exceeds the destination's value by more than $1** -- + rejected, and reported under **Flagged for review**. You can't have + moved more into a lot than the lot is worth, so the record is + presumed wrong rather than trusted. + +**`type::in_kind`** -- the securities themselves moved (an ACAT +transfer, an in-kind rollover); no cash changed hands. Requires +`dest_lot::SYMBOL@YYYY-MM-DD` -- `dest_lot::cash` is rejected, since +nothing can land as cash in a transfer where no cash moved. + +```srf +#!srfv1 +# 300 shares of VTI moved from one account to the other, no cash involved +transfer::2026-05-02,type::in_kind,amount:num:87000,from::Sample IRA,to::Sample Brokerage,dest_lot::VTI@2024-01-15 +``` + +Here `amount` is informational only. The moved value comes from the +destination lot itself, and verification is by **share count**: the +shares that left `from` must match the shares that arrived at `to`, +within 1% or 0.01 shares (whichever is larger). A mismatch is reported +under **Flagged for review** rather than silently absorbing what might +be a real contribution. + +A missing source side is not an error for either type -- the sending +account may be untracked (an external rollover origin, a 401k you don't +model). Only the destination is required. + +Because no cash funded an in-kind move, there is no partial outcome: a +destination is either fully a transfer or not one at all. + +## Scope and limits - Only `transfer::` records. Buys, sells, and dividends stay inferred from the portfolio diff. -- Only `type::cash` is wired into the contributions classifier. - `type::in_kind` parses (the format is forward-compatible) but the - matcher rejects it with an "in-kind transfers not yet supported" - message. - Forward-looking only -- there is no historical reconstruction. +- Account names are matched byte-exactly, so a + [renamed account](../../guides/set-up-accounts.md#renaming-an-account) + breaks records that reference the old name. ## See also