Skip to main content

Developer Failure Semantics Reference

Metadata​

  • Owner: Origo Engineering
  • Last updated: 2026-04-14
  • Slice/version reference: S38, S43, S47, S48, S49

Purpose​

  • Developer reference for the unified failure and success contract across Dagster, proof, runtime, and historical-serving surfaces.
  • This document explains the live surfaces and code anchors; governance authority remains in contracts/governance/*.json.

Machine contracts​

  • contracts/governance/failure-semantics.json
  • contracts/governance/dagster-authority.json
  • contracts/governance/historical-surface.json
  • contracts/governance/runtime-recovery.json
  • contracts/governance/event-sourcing.json
  • contracts/governance/integrity-durability.json
  • contracts/adapter-expected-contract-v1.json

Runtime/code anchors​

  • Partition completion and blocking state truth:
    • origo/events/backfill_state.py
  • Write-run status vocabulary:
    • origo/events/ingest_state.py
  • Runtime error class taxonomy:
    • origo/events/errors.py
  • Adapter-boundary declaration and evidence typing:
    • origo/events/adapter_boundary.py
  • Stream quarantine runtime gate:
    • origo/events/quarantine.py
  • Writer quarantine enforcement:
    • origo/events/writer.py
  • Stream-head authority and expected-head enforcement:
    • origo/events/stream_sequence_state.py
  • Runtime-audit conflict evidence:
    • origo/events/runtime_audit.py

Key rules​

  • Dagster green is not success unless terminal proof for the same partition exists.
  • Dagster/proof disagreement is a hard failure, not an operator nuance.
  • gap_detected is a write-run failure even when the surrounding run path appears otherwise healthy.
  • Partition-level quarantine truth in ClickHouse is the authoritative failure-hold surface for this slice.
  • Stream-level quarantine remains a required runtime write gate.
  • NoopStreamQuarantineRegistry is proof-only and must not be used in runtime ingest paths.
  • strict=true warning escalation is part of the unified failure contract and must resolve to 409.
  • Runtime bootstrap success requires both green quality gates and healthy runtime dependencies.
  • Canonical write conflict is a first-class hard failure for non-present append intent when expected-head lineage is stale.
  • Exact duplicate source-event identity still resolves to duplicate before stale-head conflict evaluation.
  • Authoritative stream-head control is ClickHouse-only; no second head store or external lease service is allowed.
  • Caller-visible automatic retries on write conflict are forbidden.
  • Adapter-boundary deterministic invariant failure is a hard-stop pre-append failure.
  • Adapter-boundary evidence must stay stage-aware:
    • pre_artifact_failure
    • artifact_backed_rejection
  • Adapter-boundary drift is operator-visible runtime truth, but alert-only by default unless a future source-local contract explicitly tightens it.
  • Payload-schema rejection is a hard-stop pre-append failure and must emit canonical_payload_schema_rejection through runtime-audit.
  • Payload-schema authority is stream-scoped by (source_id, stream_id, schema_version) and must stay separate from domain_event_type taxonomy.
  • Late-arrival rejection is an authoritative runtime truth surface through late_arrival_rejection.
  • In-window aligned late-arrival supersession is an authoritative runtime truth surface through late_arrival_supersession, even though the aligned bucket replacement mechanism is not yet runtime-enabled.