This section is the canonical developer and maintainer hub for Origo.
Read this page first if you need contributor workflows, governance reading order, release and maintenance routes, or the documentation system contract.
Governance authority remains machine-readable in AGENTS.md and contracts/governance/.
Developer docs explain how to work with Origo; they do not replace machine governance authority.
canonical event rows are full-envelope rows with source identity, domain_event_type, schema_version, correlation_id, nullable causation_id, and producer provenance
unreplayed pre-S39 historical rows may keep those added metadata fields null until replay/rewrite completes; new writes must populate them
domain_event_type is canonical domain taxonomy and must not be confused with runtime-audit event_type
canonical storage ordering is per stream key (source_id, stream_id, partition_id) via stream_sequence, allocated at the store boundary against ClickHouse-backed head state
stream-head authority is ClickHouse-only; no second head store or lease service is allowed
authoritative head components are canonical_stream_sequence_heads, canonical_event_log_active_v1, and canonical_partition_reset_boundaries
every authoritative append must target exactly one canonical stream key; same-stream multi-row append is allowed, mixed-stream authoritative append is forbidden
authoritative append requires a lineage-aware expected head consisting of stream identity, reset-boundary lineage, and current-truth last_stream_sequence
unreplayed pre-S42 rows may still keep null stream_sequence until rewrite cutover completes, but any incremental write that would idempotently dedup against those rows must fail closed and requires replay/rewrite first
current-truth active views are read authority, but raw append-only event-log continuity is ordering/gap authority
exact duplicate identity short-circuits to duplicate before stale-head conflict evaluation; stale-head conflict is a fail-fast write conflict, not a duplicate
caller-visible automatic retries on write conflict are forbidden; bounded internal visibility verification without append reissue is allowed
projector fetch, resume, checkpoints, and watermarks must advance by stream_sequence, not by ingested_event_id or derived offset ordering
canonical source authority is frozen in contracts/canonical-source-authority-v1.json; selector-aware ETF and FRED families must pass structured authority claims and non-authoritative writes must fail before append
canonical timestamp semantics are frozen in contracts/canonical-source-timestamp-semantics-v1.json; source_event_time_utc now means the canonical family time reference, and the precision registry is subordinate numeric metadata rather than timing authority
canonical late-arrival and projection-time authority are frozen in contracts/canonical-late-arrival-v1.json; current data-serving projections remain event_time, but that governs bucket/window or record-timestamp semantics only while stream-sequence checkpoints and watermarks remain operational progression state
canonical dedup semantics are frozen in contracts/canonical-dedup-strategy-v1.json; canonical dedup is authoritative only at the write boundary, uses current-truth lineage after reset boundaries, and ETF/FRED identity excludes value fields
canonical payload-schema authority is frozen in contracts/canonical-payload-schema-v1.json; schema identity is (source_id, stream_id, schema_version), domain_event_type is taxonomy only, and both writer-mediated and direct insert paths must validate the final canonical payload_json before append
current-truth canonical event-log reads must use canonical_event_log_active_v1
raw append-only canonical event-log history must use canonical_event_log_history_v1
observability is derived-only and must render authoritative Dagster, ClickHouse, and audit truth rather than invent parallel status
spec/slices.json records slice sequence, status, authority, and explicit structural inconsistencies only.
Historical completed slice records live under spec/slices/*.md.
Repo-resident slice authority ends at Slice 34.
New or replanned slices are authored and tracked in GitHub issues using .github/ISSUE_TEMPLATE/slice.yml.
New or replanned slices from Slice 35 onward are authoritative in GitHub issues created from .github/ISSUE_TEMPLATE/slice.yml.
Historical slice records are historical slice material unless they are explicitly listed above as live runtime contracts.
Version metadata in those records is a slice snapshot, not necessarily the current runtime version.
Any CLI examples, runner names, or controller names in those records are provenance only and must not be treated as live write-entrypoint authority.
When there is any mismatch, follow AGENTS.md plus contracts/governance/*.json for governance and the live runtime contracts above for runtime behavior.