Skip to main content

Evalium — KOE Operational Proof Model

Knowledge • Observation • Evidence (Canonical Edition)

This document defines Evalium’s canonical domain model for capturing defensible operational proof using three universal pillars:

  • Knowledge (K) — what must be known or acknowledged
  • Observation (O) — what was seen, done, or measured
  • Evidence (E) — what artefacts substantiate the record

KOE is intentionally industry-agnostic.
It describes how proof is captured, not what industry the proof belongs to.

Evalium’s mechanics remain deliberately simple:

Definitions → Tasks → Execution → Ledger Entries

What has changed is intent:
Evalium is no longer framed as “assessment for learning”, but as an Execution Ledger that records what happened, by whom, when, and under what conditions — and can prove it later.

Engineering invariants (WORM ledger, amendments/voids, contextual binding, verification level enforcement) are defined in: docs/architecture/FOUNDATION.md

System structure (Engagement/Project thread, Client Portal, hashing/ratification) is defined in: docs/architecture/architecture

Terminology note: Knowledge, Observation, and Evidence (K/O/E) are intentionally broad primitives. Some industries may refer to these concepts using different language, but Evalium treats K/O/E as stable, cross-domain proof types.

1. Why KOE (and why it stays)​

KOE is the stable ontology of Evalium.

  • It is easy to understand across industries
  • It maps cleanly to how humans reason about proof
  • It matches your backend architecture exactly
  • It does not age with market language or regulation cycles

KOE is not marketing vocabulary.
It is the conceptual substrate of the platform.

Industry-specific terms (e.g. “inspection”, “licence to operate”, “audit evidence”) are interpretations, not replacements.

2. The Three Worlds (KOE in context)​

Evalium is easiest to reason about as three worlds with strict rules between them.

2.1 Definition World (Templates & Policies)​

What is defined before work happens:

  • Protocol templates (what must be captured)
  • Required verification level (L1–L4)
  • Required context metadata (if any)
  • Disclosure rules (what operators, admins, or clients can see)
  • Scoring / outcomes (where applicable)

Invariant:
Published definition versions are immutable.

KOE lives here as intent:

  • “This is a Knowledge protocol”
  • “This is an Observation protocol”
  • “This is an Evidence protocol”

2.2 Execution World (The Ledger)​

What happens in the real world:

  • Tasks are issued
  • Operators execute work
  • Knowledge, observations, and evidence are captured as ledger events
  • Errors are corrected via amendments, not edits
  • Records are voided, never deleted

Invariant:
Execution records are WORM (Write Once, Read Many).

KOE lives here as behaviour:

  • Knowledge entered
  • Observations recorded
  • Evidence captured

2.3 Projection World (Views & Exports)​

Derived representations:

  • Internal reporting
  • Analytics
  • Client “Glass Box” portal
  • CSV / PDF exports
  • (Future) milestone hashes and ratification events

Invariant:
Projections are derived from ledger + snapshots, never live definitions.

3. Core Entities (Same Mechanics, Clearer Intent)​

Evalium keeps a deliberately small set of core entities.

3.1 Definition entities​

  • Evaluation
    A protocol template (definition-time blueprint)

  • Evaluation Version
    An immutable version of that protocol once published

  • Item / Question
    A single capture unit (check, prompt, rubric row, upload request)

Internally, you may retain “Evaluation” terminology for continuity. Externally and conceptually, these are Protocols.

3.2 Execution entities​

  • Engagement / Project
    A long-running “Golden Thread” container for real-world work

  • Assignment
    A task issue: who may execute which protocol version, under which policy

  • Session
    An execution window (runtime context)

  • Submission
    A Ledger Entry: the immutable record of execution, snapshot-backed

3.3 People (roles, not personas)​

  • Operator / Practitioner — performs the work
  • Verifier / Supervisor — reviews or signs off (Level 2/3)
  • Client / Stakeholder — read-only visibility + optional ratification
  • Author — maintains protocol definitions

(Full role/capability semantics live in docs/security/roles-and-access-control.md.)

4. Knowledge (K) — Cognitive Proof​

Knowledge protocols capture proof that a person knows or understands something, not merely that they have acknowledged it.

Knowledge is not limited to passive acknowledgement. It encompasses high-rigor, scored assessments, timed examinations, and cognitive validations. Whether a simple declaration or a complex exam, the execution is captured with the same forensic immutability.

Knowledge can be demonstrated through:

  • evaluated questions (single choice, multiple choice, scenario-based, short answer)
  • calculations or rule application
  • system-verified correctness and scoring
  • pass/fail or graded outcomes

Declarative acknowledgements (“I confirm…”) are a valid but minimal form of Knowledge. Demonstrated correctness is an equally first-class form.

In all cases, the outcome is recorded as an immutable execution event, with scoring and rules frozen via snapshot at submission time.

5. Observation (O)​

5.1 What Observation means (canonically)​

Observation protocols capture what was seen, done, or measured.

They are the work log.

Observation answers:

  • “What happened?”
  • “What was checked?”
  • “What condition was observed?”
  • “What measurement was taken?”

5.2 Observation capture modes​

A) Self-recorded​

An operator records their own work.

B) Supervisor-led​

A verifier records observations while watching the operator perform the work.

C) Crew / Gang logs​

One supervisor records for multiple operators:

  • One session
  • Multiple subjects
  • Grid-style capture (subjects × criteria)

Backend requirement:
Even if the UI groups capture, storage must preserve per-subject attribution.

5.3 Observation item types​

  • Yes / No / N/A checks
  • Rubric ratings
  • Numeric readings with constraints
  • Structured notes
  • Context-required observations (time / location / device)

Verification levels (L1–L4) are defined by protocol policy, not UI choice.

5.4 Industry interpretations (non-canonical)​

Examples only:

  • “Inspection”
  • “Audit”
  • “Site Walkthrough”
  • “Field Execution Log”

All of these are Observation protocols.

6. Evidence (E)​

6.1 What Evidence means (canonically)​

Evidence is a substantiating ledger event, not a file.

Evidence is not just files. It is chain-of-custody capture recorded as append-only ledger events.

Evidence answers:

  • “What artefact supports this record?”
  • “Who captured it, when, and under what conditions?”

6.2 Evidence is cross-cutting by design​

Evidence is not a separate world.

It can appear:

  • Inside Knowledge protocols
    (e.g. upload certificate to prove acknowledgement)

  • Inside Observation protocols
    (e.g. photo of installed unit)

  • As standalone Evidence-heavy protocols
    (where the artefact is the work product)

This is intentional and aligned with your architecture.

6.3 Evidence entry points (same core, different association)​

All entry points converge into the same Evidence Core + ledger events:

  • Standalone Evidence (submission with zero items)
  • Inline Evidence (linked to a submission item)
  • Mixed Evidence (answer + artefact together)

6.4 Evidence lifecycle​

Evidence capture follows the same lifecycle:

Assignment → Session → Ledger Entry

Review, approval, rejection, or resubmission are:

  • additional ledger events
  • never overwrites

6.5 What makes Evidence “forensic”​

An evidence ledger event records:

  • who captured it
  • when
  • which task/session/engagement it belongs to
  • required context metadata (if policy demands)
  • optional content hash or future signing metadata

The ledger, not the file store, is the source of truth.

6.6 Industry interpretations (non-canonical)​

Examples only:

  • “Compliance Evidence”
  • “Inspection Photos”
  • “Certificates”
  • “Supporting Artefacts”

All remain Evidence (E).

7. Verification Levels (KOE-wide)​

Verification levels apply across K, O, and E.

  • L1 — Self-verified
  • L2 — Peer / Supervisor verified
  • L3 — System verified
  • L4 — Context-verified (time/device/location + optional step-up auth)

The required level is part of the protocol version policy and enforced server-side.

Trust level is designed in, not retrofitted.

8. Engagement / Project (“Golden Thread”)​

An Engagement is the long-running wrapper that connects multiple K/O/E executions.

It enables:

  • timeline reconstruction
  • milestone reporting
  • client glass-box visibility
  • future state hashing and ratification

KOE executions are linked, not flattened.

9. Client Glass Box (Projection, not mutation)​

Clients and stakeholders may be granted:

  • read-only visibility into ledger history
  • curated disclosure (policy-driven)
  • optional milestone ratification

They never:

  • edit execution records
  • mutate definitions
  • bypass verification policy

10. Guardrails (What KOE explicitly avoids)​

To preserve clarity and defensibility:

  • No destructive deletion of execution records
  • No generic file dumping unrelated to a task
  • No project-management sprawl
  • No HR appraisal / LMS creep
  • No “editable history” semantics

11. Summary​

Evalium’s KOE model is:

  • Canonical
  • Industry-agnostic
  • Ledger-aligned
  • Future-proof

Industry language may change. Regulation may change. Markets may change.

KOE remains correct.

Evalium captures:

What was known, what was observed, and what evidence exists —
recorded immutably, with context, and defensible under scrutiny.