Doctrine
ORA-2026-0114: Data Domain Separation v2
ORA-2026-0114: Data Domain Separation v2
Amends CLAUDE.md §2
Original §2:
- heartwood-db → Client data (cards, facts, decisions, rooms, people, phases)
- camber-db → Process data (budget, receipts, cost codes, vendors, spans)
- orbit-db → AI team intelligence
Amended §2:
- heartwood-db → Client-facing truth (client data + financial truth: receipts, vendor registry, cost codes, labor, client invoices, change orders, project financials, photos-as-evidence)
- camber-db → Pipeline + process data (comms decomposition, spans, span_attributions, ai-router, proposals, review queue, conversation pipeline state, contact routing)
- orbit-db → AI team intelligence (unchanged)
Why the change
Receipts, vendor registries, cost code mappings, and labor time entries migrated to heartwood-db because they are FINANCIAL TRUTH — they feed client invoices, project costing, BT reconciliation, and the Monday Brief. They are client-facing artifacts, not pipeline process state.
The brainwave's core insight confirms this: receipts are the skeleton of reality. They belong in the truth database (heartwood), not the pipeline database (camber). The pipeline (camber) READS receipt data via materialized views/cross-DB bridges but does not OWN it.
The boundary rule (updated)
| Data type | Belongs in | Rationale |
|---|---|---|
| Receipts (source PDFs, amounts, vendors, dates) | heartwood | Financial truth, feeds client invoices |
| Vendor registry + dictionary + cost_code_map | heartwood | Financial identity, feeds receipt assignment |
| Labor time entries + periods | heartwood | Feeds job costing + client invoicing |
| Client invoices, change orders | heartwood | Client-facing financial artifacts |
| Photos (BT inventory, classifications) | heartwood | Evidence of physical state, client-facing |
| Contact routing table (contacts.company, phone) | camber | Pipeline routing for attribution |
| Conversation spans + span_attributions | camber | Pipeline DECOMPOSE+WEAVE output |
| Attribution proposals, review queue | camber | Pipeline decision staging |
| Receipt rollup views (materialized) | camber | READ-ONLY bridge from heartwood truth |
Violations to fix
Client PII in camber-db (move to heartwood):
- projects.client_* columns (20 rows)
- bt_client_contact (29 rows)
- bt_job_client (30 rows)
- project_clients (20 rows)
- project_shares (6 rows)
Pipeline data in heartwood-db (move to camber or delete):
- conversation_spans (11,462 rows) — pipeline output, should not be in truth DB
- gmail_financial_receipts (12,636 rows as of 2026-05-01; 12,626 rows in 2026-05-03 readback) — pipeline ingest staging/evidence-index rows with Gmail locators. These are not canonical receipt truth and not source-PDF substitutes; moving them out of heartwood fixes domain ownership, not primary-source coverage.
- call_chains (65 rows) — pipeline routing
- photo_attribution_runs (29 rows) — AI pipeline output
- photo_room_attributions (9 rows) — AI pipeline output
Cross-DB bridge pattern
Camber needs receipt/vendor data for the attribution pipeline. The pattern: 1. Heartwood OWNS the receipt/vendor/labor truth 2. Camber reads via materialized views (v_receipt_vendor_project_rollups_v1, already exists at 349 rows) 3. Views refresh on schedule (cron or trigger) 4. Camber NEVER writes to heartwood receipt/vendor tables 5. Heartwood NEVER writes to camber span/attribution tables
Cross-Stamps
- 2026-05-03 - HWD-0926: Heartwood lane boot files (
AGENTS.md,CLAUDE.md,GEMINI.md) now cite this doctrine as the data-domain boundary for receipts, vendors, cost codes, labor, invoices, change orders, project financials, and photos-as-evidence. - 2026-05-03 - FLT-1366: Clarified
gmail_financial_receiptsas staging/evidence-index rows with Gmail locators, distinct from canonical receipt truth and distinct from fabricated source-PDF substitutes.