`means.bank_sync`: Read-Only Bank Synchronization#

The bank_sync subpackage treats the remote provider, reconciliation journal, and Ledger projection as distinct layers. Provider observations first enter an owner-only SQLite journal with a compare-and-swap cursor. A deterministic plan then binds posted transactions to known Ledger accounts, keeps categorization visibly under Unknown, and records every safety blocker. Only the local applier may replace the generated sidecar, after exact preview, hash, parser, and ledger-cli validation.

The journal separates its append-only provider audit revision from plan-affecting transaction truth and explicit binding decisions. A checkpoint-only refetch updates freshness without changing the plan identity or generated bytes, while any transaction or binding change stales the reviewed plan before apply.

The package intentionally exposes provider-neutral models and boundaries. The current Plaid adapter is an implementation detail behind that contract; access tokens remain injected secrets rather than model fields or command arguments.

Read-Only Bank Synchronization.

The bank_sync subpackage preserves provider source truth in an owner-only journal, plans a deterministic Ledger projection, and applies only an explicitly reviewed generated sidecar. Network access is confined to authorization and fetch; planning, validation, apply, and recovery remain local.

class means.bank_sync.AccountBinding(*, source: AccountKey, ledger_account: str, bound_at: datetime)#: Explicit mapping from a provider account to a Ledger account.

class means.bank_sync.AccountKey(*, provider: str, connection_id: str, account_id: str)#

Stable provider account identity.

opaque() → str#: Return a non-reversible local display key.

class means.bank_sync.ApplyPhase(*values)#: Durable apply-journal phase.

class means.bank_sync.ApplyResult(*, run_id: str, plan_id: str, phase: ApplyPhase, changed: bool)#: Public outcome of apply or recovery.

class means.bank_sync.ApplyRun(*, run_id: str, plan_id: str, old_hash: str, new_hash: str, phase: ApplyPhase, created_at: datetime)#: Durable intent record around one sidecar replacement.

class means.bank_sync.BankSyncStore(path: Path)#

Small durable journal for source changes, plans, and apply recovery.

initialize() → None#: Create or migrate the database schema.

transaction() → Generator[Connection]#: Yield one immediate SQLite transaction.

save_connection(config: ConnectionConfig) → None#: Persist non-secret connection configuration without silent Item replacement.

connections() → list[ConnectionConfig]#: Return configured provider connections.

checkpoint(provider: str, connection_uid: str) → str | None#: Return the last completely committed provider checkpoint.

commit_revision(revision: FetchRevision) → int#: Commit source changes and checkpoint as one compare-and-swap revision.

source_revision() → int#: Return the current append-only provider audit revision.

transaction_revision() → int#: Return the revision of plan-affecting transaction truth.

decision_revision() → int#: Return the revision of explicit provider-to-Ledger bindings.

active_transactions() → list[RemoteTransaction]#: Return current non-removed normalized transactions.

remote_accounts() → list[RemoteAccount]#: Return provider account metadata for explicit local binding.

accounts() → list[AccountKey]#: Return provider accounts observed in committed revisions.

sync_statuses() → list[ConnectionSyncStatus]#: Return counts-only connection freshness records.

bind(binding: AccountBinding) → None#: Persist one explicit mapping and revision only when ownership changes.

bindings() → list[AccountBinding]#: Return all explicit account bindings.

save_plan(plan: ReconciliationPlan) → None#: Persist an immutable reconciliation plan.

load_plan(plan_id: str) → ReconciliationPlan#: Load an immutable reconciliation plan.

prepare_apply(run: ApplyRun) → None#: Durably record sidecar replacement intent.

finish_apply(run_id: str, recovered: bool = False) → ApplyRun#: Mark a prepared run committed or recovered.

abort_apply(run_id: str) → ApplyRun#: Mark a prepared intent aborted before replacement.

prepared_runs() → list[ApplyRun]#: Return interrupted apply runs needing recovery.

close() → None#: Close the SQLite journal.

class means.bank_sync.ChangeKind(*values)#: Provider transaction lifecycle change.

class means.bank_sync.ConnectionConfig(*, uid: str, provider: str, access_token_env: str, provider_connection_id: str | None = None)#: Non-secret local configuration for one provider connection.

class means.bank_sync.ConnectionSyncStatus(*, provider: str, connection_uid: str, fetched_at: datetime, provider_updated_at: datetime | None = None, update_status: TransactionsUpdateStatus, account_count: int, balance_count: int)#: Counts-only freshness record for one provider connection.

class means.bank_sync.FetchRevision(*, provider: str, connection_uid: str, connection_id: str, checkpoint: str, fetched_at: datetime, provider_updated_at: datetime | None = None, update_status: TransactionsUpdateStatus = TransactionsUpdateStatus.HISTORICAL_COMPLETE, accounts: list[RemoteAccount] = <factory>, balances: list[RemoteBalance] = <factory>, changes: list[SourceChange] = <factory>, starting_checkpoint: str | None = None, page_count: Annotated[int, ~annotated_types.Gt(gt=0)] = 1, complete: bool = True)#: One complete provider page set and its resulting checkpoint.

class means.bank_sync.PlanAction(*, kind: PlanActionKind, source: SourceKey, projection: ProjectedTransaction | None = None)#: One projection action in an inspectable plan.

class means.bank_sync.PlanActionKind(*values)#: Ledger projection change proposed by reconciliation.

class means.bank_sync.PlanBlocker(*, code: str, count: Annotated[int, Gt(gt=0)])#: Counts-only reason a plan cannot be applied.

class means.bank_sync.ProjectedTransaction(*, source: SourceKey, provenance_key: str, date: date, memo: str, amount: Decimal, source_account: str, contra_account: str)#: One provider-owned balanced Ledger transaction.

class means.bank_sync.Provider(*args, **kwargs)#

Fetch complete, normalized revisions from one read-only provider.

async fetch(connection_uid: str, access_token: str, checkpoint: str | None) → FetchRevision#

Fetch accounts, balances, and transaction changes.

Parameters:

connection_uid – Stable local label for the provider connection.
access_token – Injected provider access token; never retained by the implementation.
checkpoint – Last completely committed provider checkpoint, if any.

Returns:

One complete revision whose checkpoint may be committed atomically.

class means.bank_sync.LedgerSnapshot(*, path: Path, transactions: tuple[Transaction, ...])#: Immutable snapshot of one manually maintained Ledger.

class means.bank_sync.ReadOnlyLedgerView(*, manual: ~means.bank_sync.view.LedgerSnapshot, sidecars: tuple[~pathlib.Path, ...], transactions: tuple[~means.types.Transaction.Transaction, ...] = <factory>)#

Composite transaction view with no merge or write authority.

classmethod load(user: User, sidecars: tuple[Path, ...]) → Self#: Load a manual Ledger plus declared generated sidecars.

class means.bank_sync.ReconciliationPlan(*, plan_id: str, source_revision: int, decision_revision: int = 0, created_at: datetime, since: date, manual_hash: str, sidecar_hash: str, actions: list[PlanAction] = <factory>, projections: list[ProjectedTransaction] = <factory>, blockers: list[PlanBlocker] = <factory>, digest: str)#

Hash-bound deterministic projection plan.

property applicable: bool#: Whether the plan has no blocking conditions.

class means.bank_sync.Reconciler(store: BankSyncStore, category_policy: Callable[[RemoteTransaction, AccountBinding], str])#

Build deterministic, blocker-aware plans from committed source truth.

plan(*, since: date, manual_ledger: Path, sidecar: Path) → ReconciliationPlan#: Build and persist a deterministic local reconciliation plan.

class means.bank_sync.RemoteAccount(*, key: AccountKey, name: str, official_name: str | None = None, mask: str | None = None, type: str, subtype: str | None = None, currency: str = 'USD', persistent_account_id: str | None = None)#: Normalized provider account metadata.

class means.bank_sync.RemoteBalance(*, account: AccountKey, current: Decimal | None = None, available: Decimal | None = None, limit: Decimal | None = None, currency: str = 'USD', observed_at: datetime)#: Exact provider balance observation.

class means.bank_sync.RemoteTransaction(*, key: SourceKey, date: date, authorized_date: date | None = None, name: str, amount: Decimal, currency: str = 'USD', status: TransactionStatus, pending_transaction_id: str | None = None)#: Normalized provider transaction observation.

class means.bank_sync.SidecarApplier(store: BankSyncStore, *, manual_ledger: Path, root_ledger: Path, sidecar: Path)#

Validate and atomically replace one generated Ledger sidecar.

apply(plan_id: str) → ApplyResult#: Apply one immutable plan without network access.

recover() → list[ApplyResult]#: Resolve any prepared runs from their target hashes.

class means.bank_sync.SourceChange(*, kind: ChangeKind, key: SourceKey, transaction: RemoteTransaction | None = None, authoritative: bool = True)#: One normalized provider lifecycle change.

class means.bank_sync.SourceKey(*, provider: str, connection_id: str, account_id: str, transaction_id: str)#

Stable provider transaction identity.

opaque() → str#: Return a non-reversible local provenance key.

class means.bank_sync.TransactionStatus(*values)#: Provider transaction settlement status.

class means.bank_sync.TransactionsUpdateStatus(*values)#: Plaid transaction-history readiness state.

means.bank_sync.render_sidecar(plan: ReconciliationPlan) → str#: Render a deterministic, balanced, provider-owned Ledger sidecar.

means.bank_sync.sidecar_body_hash(text: str) → str#: Return the canonical digest of rendered sidecar bytes.

means.bank_sync: Read-Only Bank Synchronization#

`means.bank_sync`: Read-Only Bank Synchronization#