Skip to main content

Evalium Ledger Upgrades

Unified Implementation Plan (Approval, Evidence, Offline, O/E Enablement)​

Status: Planned Audience: Backend, Architecture Scope: Platform-level upgrades required to fully support Observation (O), Evidence (E), Offline Delivery, and Professional-Services-grade defensibility Non-Goals: Frontend UX, theming, marketing copy

0. Framing & Non-Negotiables​

This document implements laws of motion, not features.

The following principles are treated as platform invariants:

  1. Append-only truth — execution records are never edited or deleted
  2. Amendments, not edits — corrections create new records referencing old ones
  3. Contextual binding — every execution event is permanently bound to its circumstances
  4. Human verification (maker/checker) — approval is explicit, reviewable, and auditable
  5. State ratification — key milestones can be cryptographically sealed
  6. Single delivery engine — Knowledge (K), Observation (O), and Evidence (E) all run on the same session/submission infrastructure

Evidence (E) is not a silo. It is a capability that can appear:

  • inside Knowledge (candidate uploads artefacts about themselves),
  • inside Observation (observer uploads artefacts about a person/place/thing),
  • or as a standalone Evidence-first evaluation.

1. Milestone 1 — Universal Approval Layer (Trust Primitive)​

Purpose​

Introduce a generic maker/checker workflow that applies uniformly to K, O, and E without mutating captured data.

Approval is metadata about trust, not a modification of execution.

1.1 Database Changes​

submissions

  • approval_status ENUM

    • approved (default for K unless configured otherwise)
    • pending_review
    • rejected

  • reviewed_by_user_id (FK → users, nullable)

  • reviewed_at (timestamptz, nullable)

  • review_note (text, nullable)

Optional (recommended):

  • approval_required BOOLEAN on evaluations or evaluation_versions

1.2 Core Rules​

  • Submission content is immutable once lifecycle_status = completed

  • Approval state never unlocks or edits content

  • Rejection triggers:

    • new session / new submission
    • or explicit resubmission flow (no in-place edits)

1.3 API​

  • POST /submissions/\{id\}/approve

  • POST /submissions/\{id\}/reject

    • payload: { review_note }

  • Query defaults:

    • client-facing APIs return only approval_status = approved
    • reviewer/admin APIs can see all states

1.4 RBAC​

Capabilities:

  • submissions.review
  • submissions.approve
  • submissions.reject

1.5 Definition of Done (Milestone 1)​

Database

  • Columns added, enum enforced
  • RLS policies updated

API

  • Approve/reject endpoints
  • Visibility rules enforced

Logic

  • Cannot approve incomplete submission
  • Cannot modify completed content
  • Rejection does not reopen data

Tests

  • State machine tests
  • RLS + role tests

Docs

  • FOUNDATION.md updated (approval ≠ mutation)
  • ADR: “Universal Approval Layer”

2. Milestone 2 — Evidence & Asset Lifecycle (Evidence Primitive)​

Purpose​

Make files and media first-class, verifiable ledger artefacts that can attach to K, O, or E without ambiguity.

Evidence is contextual, not a global library.

2.1 Database​

media_assets

  • id
  • tenant_id, org_unit_id
  • owner_user_id
  • status ENUM: created → uploading → uploaded → verified → failed → deleted
  • content_type
  • byte_size
  • sha256
  • original_filename
  • captured_at_client (informational)
  • captured_gps (informational)
  • created_at
  • verified_at
  • storage_key

submission_item_assets

  • submission_item_id
  • asset_id
  • attached_at
  • attached_by_user_id
  • role (primary/supporting/derivative)

This table is the immutable chain of custody between execution and artefact.

2.2 API​

  • POST /assets → create asset placeholder + upload instructions
  • POST /assets/\{id\}/complete → verify hash, size, existence
  • GET /assets/\{id\} → metadata + authorized download/view
  • POST /submission-items/\{id\}/attach-asset

Upload methods:

  • Presigned PUT (default)
  • TUS resumable (large video / field use)

2.3 Core Rules​

  • Unverified assets cannot satisfy requirements
  • Assets cannot be attached across tenant/org boundaries
  • Completed submissions cannot receive new attachments

2.4 Definition of Done (Milestone 2)​

Database

  • Asset + link tables in place
  • RLS enforced

API

  • Asset lifecycle endpoints
  • Attach endpoint

Logic

  • Verification gate enforced
  • Compliance deletion routed via assets

Tests

  • Asset lifecycle tests
  • Attach validation tests

Docs

  • rich-content-handling.md updated
  • ADR: “Evidence as First-Class Asset”

3. Milestone 3 — Offline Sync & Policy Enforcement​

Purpose​

Enable offline capture with defensible sync while preserving server authority and auditability.

Offline is a policy decision, not a client assumption.

3.1 Policy Flags (Hierarchy)​

Offline policy can be set at:

  • Tenant
  • Org Unit
  • Programme
  • Evaluation / Version

Values:

  • online_only
  • offline_allowed
  • offline_preferred

Server enforces policy at session creation.

3.2 Database​

  • Ensure wiring of existing:

    • submission_items.client_timestamp

  • Add:

    • client_device_id
    • client_app_instance_id

Idempotency

  • delivery_event_ingest

    • session_id
    • event_id (UUID)
    • received_at

3.3 API​

  • POST /delivery-sessions/\{id\}/sync

Payload:

{
  "client_session_version": 7,
  "events": [
    {
      "event_id": "uuid",
      "type": "answer_recorded",
      "occurred_at_client": "timestamp",
      "payload": { }
    }
  ]
}

Server:

  • validates session state
  • applies events idempotently
  • returns canonical timestamps

Final seal remains:

  • POST /submit-session

3.4 Definition of Done (Milestone 3)​

Database

  • Client metadata persisted
  • Idempotency table live

API

  • Batch sync endpoint
  • Policy enforcement at session creation

Logic

  • Offline blocked where disallowed
  • Server time authoritative

Tests

  • Idempotent sync tests
  • Policy matrix tests

Docs

  • Offline Delivery Implementation doc updated
  • ADR: “Offline Capture & Sync”

4. Milestone 4 — Evidence Evaluations (E) & Observation Strengthening​

Purpose​

Activate real O and E behaviour using the primitives above — no new engine.

4.1 Evidence Evaluations (Standalone E)​

authoring

  • Evidence requirements defined as structured items:

    • allowed types
    • min/max files
    • required notes

Delivery

  • Completion requires all requirements satisfied
  • Default approval_status = pending_review

Reporting

  • Evidence pack = projection of submission + attached assets + approval state

4.2 Evidence inside Knowledge (K)​

Examples:

  • Upload portfolio
  • Submit video explanation
  • Attach external artefact

Rules:

  • Evidence attaches to submission items
  • Approval optional (default auto-approved unless configured)

4.3 Evidence inside Observation (O)​

Examples:

  • Inspector uploads photo of hazard
  • Observer uploads video of performance

Rules:

  • Rubric options may declare:
{
  "requires_evidence": true,
  "requires_comment": true,
  "finding": true,
  "severity": "major"
}

System enforces:

  • Cannot complete item without required artefacts/comments
  • Findings aggregated into report projection

4.4 Definition of Done (Milestone 4)​

Logic

  • Evidence completion rules enforced
  • Observation “requires evidence” enforced

API

  • Evidence requirements exposed in delivery DTOs
  • Findings projection available in reporting

Tests

  • Evidence-first evaluation flows
  • O + E combined flows
  • Offline + evidence + submit E2E test

Docs

  • Evidence Implementation Spec
  • Observational Implementation updated (inspection defaults clarified)

5. Resulting System Properties (Why This Order Matters)​

After Milestone 4, your platform guarantees:

  • O and E inherit the same forensic guarantees as K
  • Evidence works everywhere, not as a bolt-on
  • Offline capture does not weaken trust
  • Approval, not editing, is how quality is asserted
  • You can credibly claim: “We don’t store answers. We maintain a ledger of execution.”

6. What This Enables Next (Not in Scope Here)​

  • Step-up identity at execution time (MFA / biometric gates)
  • Cryptographic state ratification for client sign-off
  • External regulator / auditor read-only portals
  • Pass-through pricing tied to Evidence volume