Skip to content

Reference Contracts¶

The reference section is the place to verify what physically exists.

Architecture explains ownership. Finance explains economic meaning. Developer documentation explains how to change the system safely. Reference documentation answers the lower-level question that eventually arrives in every serious debugging session:

What exactly is the contract?

This catalog is generated and verified against the current warehouse registry, declarative DDL, Control Plane DDL, and deterministic identity implementation. It is intentionally less conversational than the narrative specifications. A schema reference that develops a personality disorder halfway through a foreign-key lookup is not helping anyone.

The contract ladder¶

flowchart LR
    B["Bronze
source-shaped evidence"] --> S["Silver
canonical financial state"]
    S --> G["Gold
decision-ready presentation"]
    S --> M["Meta
current analytical context"]
    CP["Control Plane
operational history"] -. provenance .-> B
    CP -. run context .-> M
    I["Identity + grain
continuity rules"] -. constrains .-> S
    I -. constrains .-> G

The layers intentionally answer different questions:

Layer	Reference question
Bronze	What source-shaped evidence was synchronized into DuckDB?
Silver	What canonical financial datasets exist, at what grain?
Gold	What analytical presentation datasets are published?
Meta	What current analytical context is mirrored for convenience?
Control Plane	What operational evidence and history are durable in SQLite?
Identity & Grain	What makes a row/entity the same financial thing across rebuilds?

Current catalog¶

Surface	Count	Authority
Bronze contracts	20	`infrastructure/warehouse/registry.py`
Silver contracts	24	registry + `schema/silver.py`
Gold contracts	22	registry + `schema/gold.py`
Meta tables	6	`schema/meta.py`
Control Plane tables	10	`infrastructure/control_plane/schema.py`
Explicit identity namespaces	8	`domain/common/identity.py`

Read in this order¶

The order follows evidence as it becomes canonical state, analytical presentation, operational provenance, and finally identity vocabulary.

Source authorities¶

src/personal_finance_etl/infrastructure/warehouse/registry.py
src/personal_finance_etl/infrastructure/warehouse/schema/bronze.py
src/personal_finance_etl/infrastructure/warehouse/schema/silver.py
src/personal_finance_etl/infrastructure/warehouse/schema/gold.py
src/personal_finance_etl/infrastructure/warehouse/schema/meta.py
src/personal_finance_etl/infrastructure/control_plane/schema.py
src/personal_finance_etl/domain/common/identity.py