Demo¶

A working walkthrough of Coframe Core on a tiny retail Analytics Collection. Every artifact on this page is real code that runs against real data.

What this demo does¶

Loads a small AC from YAML, validates it against the framework's structural integrity conditions, binds a Polars backend, reads three CSV files, and runs per-DNA-edge value attestation (I10) — verifying that the pre-aggregated customer_monthly.revenue agrees with the orders.revenue it claims to summarize, on shared anchor keys, within tolerance.

The headline outputs are three reports showing the AC at:

Level A — structural well-formedness only (no backend bound).
Level AAA — structural integrity + I10 fully grounded; clean cross-schema metric coherence.
Level AA — same AC + same data, but with a deliberate value drift injected into the pre-aggregation. I10 catches it with a specific diagnostic; level drops from AAA to AA.

The AC¶

tiny_retail is three schemas: customers, orders, customer_monthly. The same family-name revenue appears in two schemas — once in orders at order grain (the family-root), once in customer_monthly at (customer, month) grain via SUM. The two are siblings: same family-name, same family-root, navigable via the family's identity-preserving reducer.

tiny_retail.yaml

name: tiny_retail

name_map:
  customer: customer_id
  order: order_id
  month: month
  customer_state: state
  revenue: revenue_amount

schemas:

  - name: customers
    source: data/tiny_retail/customers.csv
    grain: [customer]
    columns:
      - {name: customer,       data_type: string, E: [customer], M: {signature: MNAR, determinants: [self]}, op: IDENTITY}
      - {name: customer_state, data_type: string, E: [customer], M: {signature: MCAR},                       op: IDENTITY}

  - name: orders
    source: data/tiny_retail/orders.csv
    grain: [order]
    columns:
      - {name: order,    data_type: string, E: [order], M: {signature: MNAR, determinants: [self]},  op: IDENTITY}
      - {name: customer, data_type: string, E: [order], M: {signature: MCAR},                         op: IDENTITY}
      - {name: revenue,  data_type: float,  E: [order], M: {signature: MAR, determinants: [order]},  op: IDENTITY}
        # Self-referential DNA — this column is the family-root for revenue.

  - name: customer_monthly
    source: data/tiny_retail/customer_monthly.csv
    grain: [customer, month]
    columns:
      - {name: customer, data_type: string, E: [customer, month], M: {signature: MCAR},                       op: IDENTITY}
      - {name: month,    data_type: date,   E: [month],           M: {signature: MNAR, determinants: [self]}, op: IDENTITY}
      - name: revenue
        data_type: float
        E: [customer, month]
        M: {signature: MAR, determinants: [customer]}
        op: SUM
        dna: {name: revenue, E: [order], op: IDENTITY}   # ← points back to the root

And the data (CSVs, six rows of orders, five rows of monthly summary):

orders.csv

order_id,customer_id,month,revenue_amount
O1,C1,2026-01,100.00
O2,C1,2026-01,50.00
O3,C2,2026-01,75.00
O4,C1,2026-02,200.00
O5,C3,2026-02,30.00
O6,C2,2026-02,80.00

customer_monthly.csv

customer_id,month,revenue_amount
C1,2026-01,150.00
C2,2026-01,75.00
C1,2026-02,200.00
C2,2026-02,80.00
C3,2026-02,30.00

(The monthly numbers are exactly the order-grain numbers aggregated up. That's the structural commitment Coframe's I10 verifies.)

Run 1 — Structural integrity only¶

from coframe.ac import AC

ac = AC.load("tiny_retail.yaml")
status = ac.validate()
print(ac.verification_report())

AC 'tiny_retail' — Verification Report
================================================================
  Level:               A
  Coherence posture:   structural_only
  Backend:             — (unbound)
  Schemas:             3
  ColumnSpecs:         8
  name_map entries:    5
  Selves registered:   3

Integrity conditions:
  [OK  ] I0
  [OK  ] I1
  [OK  ] I2
  [OK  ] I7
  [OK  ] I9

Notes:
  · Level A — structural well-formedness. No data has been examined.

Level A — every data-free integrity condition passes. The data-dependent checks (dimensional and metric-coherence) didn't run because no backend is bound; AC stays at A.

Run 2 — Bind Polars, run I10, reach Level AAA¶

ac = AC.load("tiny_retail.yaml").with_backend("polars")
status = ac.validate()
print(ac.verification_report())

AC 'tiny_retail' — Verification Report
================================================================
  Level:               AAA
  Coherence posture:   unconditional_within_scope
  Backend:             polars
  Schemas:             3
  ColumnSpecs:         8
  name_map entries:    5
  Selves registered:   3

Integrity conditions:
  [OK  ] I0
  [OK  ] I1
  [OK  ] I2
  [OK  ] I7
  [OK  ] I9

Dimensional integrity (I3/I4/I5/I6):
  [VAC ] I3
         · No data-attestable FD-DAG edges declared in the AC. I3 is vacuously grounded.
  [VAC ] I4
         · No explicit schema scope declarations in the AC. I4 is vacuously grounded.
  [OK  ] I5
  [VAC ] I6
         · No cross-schema attribute appearances in the AC. I6 is vacuously grounded.

Per-DNA-edge attestation (I10):
  [OK  ] revenue: orders → customer_monthly  (5/5 keys agree)

Notes:
  · Level AAA — full cross-schema metric coherence verified.
  · Dimensional integrity: all 4 conditions grounded (1 substantively, 3 vacuously).
  · Attested 1 DNA edge(s): 1 passed, 0 failed, 0 skipped.

Three tiers of verification all passed:

Structural (I0/I1/I2/I7/I9): the AC is well-formed.
Dimensional (I3/I4/I5/I6): every dimensional commitment is grounded — either substantively verified against data or vacuously grounded (nothing declared/observed to check). On tiny_retail, I5 substantively verifies that every customer value referenced in orders and customer_monthly exists in the grain-role customers schema. The other three are vacuous because the YAML doesn't yet declare FD edges (I3) or explicit scopes (I4), and customer_state only appears in one schema (I6).
Per-DNA-edge attestation (I10): the framework planned one attestable edge from the AC's metric genealogy (revenue: orders → customer_monthly), asked Polars to aggregate the predecessor at the successor's anchor via the family's ip_reducer (SUM), and compared 5 shared anchor-keys within tolerance. All 5 agreed.

→ Level AAA. That's Multi-Table Invariance verified per-edge: the framework guarantees that a SUM(revenue) BY (customer, month) query will return the same answer whether it resolves through orders or through customer_monthly. It guarantees it because it just checked — across all three tiers.

Run 3 — Inject drift, watch I10 catch it¶

The most common silent-correctness failure in real warehouses is pre-aggregation drift: late-arriving rows in the source, partial ETL failures, manual corrections that didn't propagate. Coframe's I10 is designed to catch exactly this class of problem.

Suppose customer_monthly's row for (C1, 2026-01) got updated to 153.50 while the underlying orders stayed at 100.00 + 50.00 = 150.00:

# Hypothetical: customer_monthly's first row says revenue=153.50
# instead of the correct 150.00. The orders table is unchanged.

ac = AC.load("tiny_retail.yaml").with_backend("polars")
status = ac.validate()
print(ac.verification_report())

AC 'tiny_retail' — Verification Report
================================================================
  Level:               AA
  Coherence posture:   conditional_within_scope
  Backend:             polars
  Schemas:             3
  ColumnSpecs:         8
  name_map entries:    5
  Selves registered:   3

Integrity conditions:
  [OK  ] I0
  [OK  ] I1
  [OK  ] I2
  [OK  ] I7
  [OK  ] I9

Per-DNA-edge attestation (I10):
  [FAIL] revenue: orders → customer_monthly  (4/5 keys agree)
         · key=('C1', '2026-01')  predecessor=150.0  successor=153.5  |Δ|=3.5

Notes:
  · Level AA — dimensional structural integrity verified.
  · Attested 1 DNA edge(s): 0 passed, 1 failed, 0 skipped.

The diagnostic names the family, the predecessor schema, the successor schema, the exact key where they disagree, both values, and the absolute difference. The level drops from AAA to AA — dimensional structure still holds, but metric coherence is no longer fully grounded. A consumer reading the AC sees the level and decides accordingly.

This is the architectural alignment Coframe is built for: the structural commitment is verifiable at the framework level; the diagnostic when it fails is specific enough to fix.

What's next¶

This demo exercises the structural integrity slice (I0/I1/I2/I7/I9) and per-DNA-edge attestation (I10). The dimensional data-attested conditions — I3 (FD-DAG attestation), I4 (schema scope match), I5 / I6 (cross-schema dimension and attribute mapping) — land in the next slice. They're what tightens the gap between Level A and Level AA in cases where the AC has data-attested FD edges to verify.

After that, Frame-QL parsing and resolution land, and the demo gets queries.

For the conceptual argument behind the structural commitments demonstrated here, see Coframe in 30 minutes and the Article.