Adds daily sync of Meta payroll deposits from ActualBudget into
payslip_ingest.external_meta_deposits, enabling the dashboard to overlay
bank deposits against payslip net_pay and surface parser drift on net.
- Migration 0007: new table external_meta_deposits, unique on
actualbudget_tx_id, indexed on deposit_date.
- payslip_ingest.sync.actualbudget: narrow client for the
jhonderson/actual-http-api sidecar (list accounts + transactions).
Filters on payee regex (META|FACEBOOK, word-boundary). Idempotent
upsert — ON CONFLICT DO NOTHING on actualbudget_tx_id. Surfaces
clear error if the transactions endpoint is missing so the operator
can switch to a SQLite-mount fallback.
- CLI command: `python -m payslip_ingest sync-meta-deposits` driven by
4 env vars (ACTUALBUDGET_HTTP_API_URL, API_KEY, ENCRYPTION_PASSWORD,
BUDGET_SYNC_ID).
- Tests: 5 — regex positive/negative, full sync insert, idempotency,
404-endpoint failure mode.
Part of: code-860
Phase B of RSU tax spike fix. Vest-month spikes on the dashboard trace to
variant-A slips (2019–mid-2022) where `cash_income_tax` is NULL — the
dashboard's COALESCE fallback returns full PAYE, masquerading as cash tax.
Three changes:
1. Widen variant-A Taxable Pay regex. Original pattern only matched
`Taxable Pay : This Period £...`; add case-insensitive variants that
tolerate missing/different colons, elided "This", and uppercase labels.
Covers older 2019-2020 templates that failed the previous match.
2. New `backfill_cash_income_tax` module — walks every NULL-cash-tax row
with rsu_vest > 0, re-downloads the PDF from Paperless, runs the
widened regex parser, falls back to Claude for taxable_pay extraction
if regex still misses, and derives cash_income_tax pro-rata. Records
provenance in new `cash_income_tax_source` column (regex/claude/
fallback_null). Idempotent — only touches NULL rows.
3. Migration 0006 adds the `cash_income_tax_source` audit column.
CLI: `python -m payslip_ingest backfill-cash-tax [--limit N]`. Meant to
run as a one-shot K8s Job after `alembic upgrade head`.
Part of: code-860
Meta variant-B payslips gross up Taxable Pay for RSU and compute PAYE on
the grossed-up figure, so `income_tax` on the slip is the total PAYE
(cash + RSU-attributed). Dashboards that stacked the raw figure made
vest-month tax look ~2x higher than "cash tax paid". Introduce
`cash_income_tax = income_tax * (gross_pay - pension_sacrifice) /
taxable_pay` as a derived column alongside the raw figure. Dashboards
can now stack cash vs RSU-attributed tax as separate segments.
Also capture YTD column values of `RSU Tax Offset` and `RSU Excs Refund`
from the Payments grid — needed for reconciliation against HMRC annual
figures.
P60 ingest: new parser under `parsers/p60.py` anchoring on statutory
HMRC line labels (`Tax year to 5 April YYYY`, `Employer PAYE reference`,
`In this employment` pay/tax row, NI letter bands). Processor routes
documents carrying the `p60` Paperless tag to `_handle_p60` which
writes to the new `payslip_ingest.p60_reference` table (one row per
tax_year+employer). App lifespan resolves the tag id at startup; missing
tag disables dispatch without breaking payslip ingest. Paperless tag
creation + webhook config are manual follow-ups.
Migrations:
- 0004 — cash_income_tax + ytd_rsu_tax_offset + ytd_rsu_excs_refund on
payslip, all nullable.
- 0005 — p60_reference table with (tax_year, employer) unique +
paperless_doc_id unique for idempotent re-uploads.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A single doc that isn't a real payslip (e.g., an RSU letter wrongly tagged
as payslip in Paperless) makes Claude return pay_date=null, which pydantic
rejects with ValidationError. Previously this killed the whole backfill at
the first bad doc, leaving 60 of 88 docs unprocessed.
Catch + log + continue so the backfill processes every doc. Failed docs
can be re-tagged or fixed individually later.
Extracted from /home/wizard/code monorepo into its own repo so Woodpecker CI
can watch it. Identical content to /home/wizard/code commit e426028.
See README.md for overview, env vars, and Paperless workflow config.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
