Skip to main content

Adapter Boundary Reference

Metadata​

  • Owner: Origo Engineering
  • Last updated: 2026-04-14
  • Slice/version reference: S47

Purpose and scope​

  • Runtime and operator reference for the defensive adapter boundary Origo applies before canonical write.
  • Scope covers the central machine-readable adapter expected-contract registry, the three-part runtime boundary model, and the stage-aware rejection and drift evidence surfaces.
  • This is a runtime reference. The authoritative machine contract is contracts/adapter-expected-contract-v1.json.

Authoritative surfaces​

  • Machine-readable registry:
    • contracts/adapter-expected-contract-v1.json
  • Runtime declaration/typing helpers:
    • origo/events/adapter_boundary.py
  • Runtime error taxonomy:
    • origo/events/errors.py
  • Operator-visible derived truth:
    • runtime-audit event types adapter_boundary_rejection and adapter_boundary_drift
    • Slice 40 dashboards rendered from authoritative truth surfaces

Runtime boundary model​

  • deterministic_invariants
    • hard-stop and fail-loud
    • rejected input must not proceed to canonical write
  • consumed_adjacent_policy_gates
    • declared explicitly, but not redefined here
    • examples include partition-window gates, archive availability boundaries, and mempool capture-boundary availability
  • statistical_drift_monitoring
    • alert-only by default
    • current Origo drift baselines are greenfield declaration work, not a claim that every live baseline already exists

Rejection evidence stages​

  • pre_artifact_failure
    • use when failure happens before any durable artifact exists
    • required fields:
      • diagnostic_context
      • optional attempted_locator
      • optional adapter_name
  • artifact_backed_rejection
    • use when a durable artifact exists and the adapter rejects after acquisition
    • required fields:
      • artifact reference (artifact_kind, artifact_locator)
      • optional artifact_sha256
      • optional artifact_format
      • diagnostic_context
      • optional adapter_name
  • Artifact reference is required when a durable artifact exists.
  • Origo does not flatten all failures into a fake artifact-free evidence model.

Family and overlay model​

  • Registry keys are (source_id, stream_id).
  • One base declaration exists for every live external source family.
  • Families with materially different source-boundary law inside the family use overlays:
    • ETF overlays are per issuer source key
    • FRED overlays are per series source key
  • Exchange and Bitcoin families stay single-base-family declarations today.

Operator reading rules​

  • adapter_boundary_rejection means input was rejected before canonical write.
  • adapter_boundary_drift means a declared drift signal was observed; it is not a hard stop unless a future source-local contract says otherwise.
  • Runtime audit is authoritative derived runtime truth for these outcomes.
  • Grafana may render the outcomes, but Grafana does not define them.