integrations-sync

name	integrations-sync
description	Idempotent refresh patterns for Atlas's financial data sources — Kraken, brokerage CSVs, QuickBooks, FRED, payroll. Codifies safe sync flow with audit log so agents stop reinventing dedupe/dry-run logic per source.
tags	["skill","integrations","data","sync","idempotent","cfo"]
triggers	["sync integrations","refresh kraken","sync brokerage","refresh quickbooks","pull latest financials","integrations sync"]
owner	atlas
tier	T2
risk	medium
canonical_pattern	../../../Business-Empire-Agent/skills/integrations-sync/SKILL.md

Integrations Sync — Atlas Refresh Patterns

Overview

Every external financial source needs a refresh path. Without a codified pattern, agents reinvent dedupe + dry-run + audit logic, and stale data quietly corrupts ACB / tax position / cfo_pulse downstream.

For Atlas, this is regulatory discipline — wrong dedupe = wrong tax filing. Always idempotent. Always logs. Always dry-run available.

When to invoke:

• CC says "refresh Kraken" / "sync brokerage" / "pull QB data"
• A Prep Table snapshot has stale upstream financial data
• Before generating a CFO briefing if cfo_pulse.json > 24h old
• Quarterly reconciliation

Trigger: sync integrations, /integrations-sync, "refresh "

Core Principles

1. Idempotent or dry-run. Every sync supports re-running without duplicating data OR has --dry-run.
2. Audit log. Every sync writes a JSONL entry to state/integrations_sync.log (regulatory trail).
3. Pull only the delta. Use --since <iso> or trade-ID watermark.
4. TZ-aware. Crypto in UTC, fiat in America/Toronto for tax.
5. Downstream rebuild. After Pantry sync, rebuild the affected Prep Table snapshot + emit fresh cfo_pulse.json.

Source-by-Source Playbook

Kraken → trades + balances

python atlas_tools.py kraken sync-trades --since "<iso>" --json
python atlas_tools.py kraken balances --json

• Idempotent: trade ID is unique. Re-running same window = no-op.
• Verify: python -m finance.crypto_acb status --json shows ACB consistent with new trades.
• Downstream: rebuild latest_acb.json snapshot, then emit cfo_pulse.json.

Brokerage CSV import

# Drop CSV in data/imports/brokerage/
python -m finance.wealth_tracker import --file data/imports/brokerage/<file> --dry-run
python -m finance.wealth_tracker import --file data/imports/brokerage/<file> --json

• Idempotent: upsert on (account, trade_date, symbol, qty, price).
• Verify: holdings totals match brokerage statement.

QuickBooks → invoices + expenses

# (when wrapper exists)
python atlas_tools.py qb sync --since "<iso>" --json

• Idempotent: QB transaction IDs are unique.
• Verify: bookkeeping balance matches QB dashboard.

FRED → macro rates

python -m finance.cashflow refresh-macro --json

• Idempotent: FRED series returns same values for same dates.
• Cheap, can run hourly.

CRA filings ingest

# Drop PDFs in data/tax/<year>/
python -m finance.tax import-noa --year <YYYY> --json

• Idempotent: NOA per year is unique.
• Verify: tax position snapshot reflects new NOA.

Cross-agent pulse refresh

python cfo/pulse.py emit --json

• After ANY Atlas sync above, emit a fresh pulse. Bravo + Maven read this for CFO state.
• This is the load-bearing Plate-tier emission. Skip = empire sees stale CFO.

Audit Log Format

state/integrations_sync.log JSONL:

{"ts":"2026-05-14T22:00:00Z","source":"kraken","action":"sync-trades","mode":"incremental","since":"2026-05-13T21:00:00Z","rows":12,"errors":0}

If errors > 0, append to state/integrations_sync.errors.log.

Execution Protocol

1. Identify the source from CC's request.
2. Dry-run first for anything that touches ACB or tax (finance/crypto_acb.py recompute, finance/tax.py adjust).
3. Sync the delta — --since last-success-ts; --full requires explicit CC approval.
4. Verify with per-source verification command.
5. Rebuild downstream — affected snapshot + cfo_pulse.json.
6. Log to audit JSONL.
7. Confirm in chat — source, mode, row delta, downstream rebuilt, audit log path.

Anti-Patterns

• ❌ finance.crypto_acb.py recompute without dry-run first. Wrong superficial-loss windowing = wrong tax filing.
• ❌ Brokerage CSV re-import on a SECOND copy of the same file. Always check whether the file was already imported.
• ❌ Sync-ing without refreshing cfo_pulse.json. Bravo + Maven now see stale CFO state — Maven might authorize ad spend against an outdated runway.
• ❌ Burying errors. Always log + surface.
• ❌ Full re-sync as default. Always delta.
• ❌ Skipping the JSONL audit. CFO domain MUST have audit trail.

Integration

• brain/DATA_TAXONOMY.md — Pantry source registry
• atlas_tools.py / finance/*.py — underlying CLI wrappers
• cfo/pulse.py — emits cross-agent visibility
• state/integrations_sync.log — regulatory audit trail
• brain/CFO_GATE_CONTRACT.md — what the pulse Plate must contain after refresh

Obsidian Links

• [[brain/DATA_TAXONOMY]] | [[brain/CFO_GATE_CONTRACT]] | [[brain/INTENTS]]
• [[skills/silver-platter/SKILL]] | [[skills/memory-journaling/SKILL]]