0007 — Portable Canonical Data Model
- Status: Accepted (design intent; no persistence engine chosen or deployed)
- Date: 2026-09-11
Context
Phase 2 (Read-Only Commons) will eventually require a real database, and the project intentionally has not chosen one yet (see OQ-ARCH-FRAMEWORK (repository reference) equivalent framework question and the data-model open questions). Without an explicit portability constraint, early schema decisions risk locking Hummingbird's institutional meaning into the quirks of whichever database is picked first.
Decision
Hummingbird's canonical records use versioned, portable objects/events/relationships whose institutional meaning is independent of the eventual persistence engine. Concretely (documented in DATA_MODEL.md (repository reference)):
- A small canonical core shape (
id,type,schema_version,created_at,state,content,relationships) rather than an unstructured blob. - Meaningful changes are recorded as minimal events rather than full duplicate snapshots.
- Cross-object relationships are typed (e.g.
responds_to,supersedes) and designed to be graph-projectable without requiring a graph database. - Large artifacts are referenced, not copied.
- Search indexes, caches, and other derived projections are explicitly non-canonical and must remain rebuildable.
- Three retention classes (EPHEMERAL, OPERATIONAL, DURABLE) govern how long data lives, separate from the existing visibility classification in SECURITY.md (repository reference).
- A "data budget" checklist (purpose, canonical-or-derived, retention class, expected size, reconstructability, privacy classification) must be answerable before any new persistent field or dataset is added.
Rationale
Designing around documents, events, and typed relationships keeps Hummingbird compatible with document databases, JSON-in-SQL, PostgreSQL JSONB, D1/SQLite JSON, MongoDB, Firestore, or future object/event storage, so the eventual engine choice becomes an implementation detail rather than a constitutional one. Separating canonical data from derived projections and imposing a data budget up front prevents flexible document storage from becoming uncontrolled accumulation just because storage is cheap.
Alternatives considered
- Pick a database now and design the schema around it — rejected as premature; Phase 2 is not yet underway and locking in an engine before real usage patterns exist risks a costly migration later.
- Schema-less/unstructured blob storage — rejected in favor of schema-flexible but explicitly versioned and typed documents, so institutional meaning does not depend on out-of-band tribal knowledge of what a blob contains.
- Defer any data-architecture documentation until Phase 2 begins — rejected; recording the constraints now gives future schema design (still an open question per-entity) a stable frame to work within.
Consequences
- No schemas, tables, or migrations were created by this decision.
OQ-DATA-CONTRIBUTION-MODEL,OQ-DATA-PROPOSAL-MODEL,OQ-DATA-NEED-MODEL,OQ-DATA-AUDIT-EVENT-MODEL, andOQ-DATA-WORKFLOW-STATESremain open and still block entry into Phase 2. - Any future Phase 2 implementation proposal should explain how its concrete schema satisfies the portability principle and data budget, or explicitly justify a deviation.
- The interim Base support wallet's on-chain activity is treated as an example of "reference external authoritative facts, don't duplicate them": the chain itself is authoritative, and Hummingbird avoids building a shadow transaction ledger.