Skip to main content

Status And Readiness Contract

Purpose​

Define a single, enforceable status model for operator-facing proof clarity while preserving Evalium invariants:

  • execution truth is ledger-bound and immutable
  • projections are derived from ledger + snapshots
  • mutable triage state stays outside WORM execution records

This contract governs:

  • proof readiness semantics
  • KOE status interpretation blocks
  • exceptions queue behavior
  • cross-lens consistency (submission, engagement, programme, glass box)

Non-Negotiables​

  1. Do not store editable proof_readiness or koeStatus fields on execution records.
  2. Derive readiness/status from ledger facts, snapshots, and policy references.
  3. Make derivation explainable (reasons, asOf, computation refs, logic version).
  4. Keep triage workflow state in scaffolding/derived tables, not execution tables.

Dual-Time Readiness Semantics​

Readiness must expose two distinct interpretations:

  1. defensibleAtExecution
  • Computed against policy/config effective at execution time.
  • Uses snapshot/policy refs associated to the executed record.
  • Must not change due to later policy tightening.
  1. readyNow
  • Computed against current active policy/config.
  • Used for operational remediation and backlog triage.

Both views are required to avoid retroactive truth drift.

KOE Status Block (Derived)​

Expose a first-class derived block in relevant responses:

{
  "koeStatus": {
    "knowledge": { "state": "pass|provisional|fail|not_applicable", "reasons": [] },
    "observation": { "state": "complete|needs_attention|not_applicable", "reasons": [] },
    "evidence": { "state": "complete|pending_verification|missing|not_applicable", "reasons": [] }
  },
  "proofReadiness": {
    "defensibleAtExecution": { "state": "ready|needs_review|blocked", "reasons": [] },
    "readyNow": { "state": "ready|needs_review|blocked", "reasons": [] },
    "asOf": "RFC3339",
    "logicVersion": "string",
    "computedAgainst": {
      "snapshotRef": "uuid-or-hash",
      "policyRefExecution": "id/version",
      "policyRefCurrent": "id/version"
    }
  }
}

Reason codes must be canonical and stable.

Lens-Aware Interpretation​

Status must remain lens-aware:

  1. Submission lens
  • fine-grained reasons for a single execution record.
  1. Engagement lens
  • aggregate readiness across linked submissions/assignments with explicit rollup semantics.
  1. Programme lens
  • requirement-level readiness and completion blockers.
  1. Glass Box lens
  • scope-safe derived view for external stakeholders.

Capability-Based Redaction​

koeStatus and readiness reasons must be redacted by capability on external/read-only surfaces.

  • Internal capabilities can see full reason sets.
  • External/link-principal views receive only allowed reason classes.
  • Redaction must be deterministic and test-covered.

Defensibility Exceptions Queue​

Implement a derived queue for records requiring action. Minimum contract:

  • id
  • subjectType (submission|engagement|programme_requirement|...)
  • subjectId
  • lens
  • readinessState (needs_review|blocked)
  • reasonCodes[]
  • state (open|acknowledged|resolved)
  • owner
  • firstSeenAt
  • lastSeenAt
  • suppressedUntil

This queue is operational scaffolding and must not mutate execution truth.

Packs Lineage Completeness​

Expose full provenance chain end-to-end:

content_pack -> pack_revision -> pack_item -> source_evaluation_version -> installed_evaluation/version -> submission_snapshot

Lineage is considered incomplete unless every link is reconstructable.

Skills Explainability Gate​

Do not expose user-facing skills explainability until deterministic provenance facts are persisted per submission:

  • mapping_set_version_id
  • mapping_rule_id
  • source taxonomy term IDs

Explanations must be replayable from persisted facts, not recomputed ad hoc from current mappings.

Normalized Status Taxonomy​

Maintain explicit separation across four status planes:

  1. executionState (ledger lifecycle, e.g. submitted/voided)
  2. reviewState (approval workflow)
  3. integrityState (evidence verification state)
  4. derivedReadiness (operator lens state + reasons)

No plane should overload another plane's semantics.

Enforceability Requirements​

This contract is not complete until all are present:

  1. ADR capturing normative decisions and invariants.
  2. Shared OpenAPI schemas for readiness/KOE blocks.
  3. Endpoint contract tests for shape + reason code stability.
  4. Redaction tests for Glass Box capability boundaries.
  5. Smoke coverage for dual-time readiness and exceptions queue lifecycle.
  6. Versioned derivation logic (logicVersion) with backward-compatible evolution policy.