Evalium — Engagements (Golden Thread Implementation)
1. Purpose (why Engagement exists)
An Engagement is the long-running, real-world work container that binds many execution events into a single defensible narrative.
If submissions prove what happened, Engagements prove that these things happened together, as part of one job.
Engagements exist to solve problems that individual WORM submissions cannot solve alone.
2. What an Engagement is (simple definition)
An Engagement is:
- a named instance of work
- usually client-, site-, asset-, or project-specific
- spanning days, weeks, or months
- containing many K/O/E executions
- optionally derived from a Programme template
It is the Golden Thread through the execution ledger.
3. What an Engagement is NOT
An Engagement is not:
- a replacement for Programmes
- a replacement for submissions
- a new execution mechanism
- a WORM substitute for KOE data
- a reporting-only concept
It does not store answers, scores, or evidence itself.
4. Engagement vs Programme (explicit comparison)
This is the missing clarity.
| Concept | Programme | Engagement |
|---|---|---|
| Type | Template / definition | Instance / container |
| Reusable | Yes | No |
| WORM | Definition versions are immutable | Lifecycle events are append-only |
| Purpose | “What must be done” | “This specific job” |
| Scope | Abstract / reusable | Concrete / real-world |
| Contains | Requirements / rules | Assignments + submissions |
| Ties to client | Indirect | Direct |
Mental model
- Programme = blueprint
- Engagement = build site
You already have Programmes. Engagements do not replace them — they instantiate them.
5. Relationship to existing KOE executions
This is the key answer to your confusion.
“If all tasks are already WORM submissions, why does Engagement need to exist?”
Because WORM submissions prove facts, but they do not prove grouping, intent, or completeness.
Engagement adds:
5.1 Narrative binding
Without Engagement:
- you have many correct facts
- but no authoritative statement that they belong to the same job
With Engagement:
- “These 27 submissions constitute the inspection of Site X”
5.2 Completeness guarantees
Engagement lets you answer:
- Were all required tasks done?
- Which were skipped?
- Which were voided or amended?
This cannot be inferred reliably from submissions alone.
5.3 Lifecycle events
Engagement has its own ledger events:
- created
- tasks added
- milestone reached
- closed
- ratified
These are not KOE submissions — they are meta-events about the work.
6. Engagement data model (conceptual)
Engagements are not answer tables.
They are ledger-backed containers.
6.1 Core table (mutable header)
engagements
- id
- tenant_id
- org_unit_id
- external_ref (client/job/site reference)
- title
- status (open | closed | superseded)
- created_at
This table may be mutable (status changes), because it is operational scaffolding.
6.2 Engagement ledger (append-only)
engagement_events
- id
- engagement_id
- event_type
- payload
- actor_id
- occurred_at
Examples:
- engagement_created
- task_attached
- milestone_reached
- engagement_closed
- engagement_superseded
These events are WORM.
7. How Engagement uses existing submissions
Submissions remain the durable source of truth.
Engagement only references them.
engagement_id → assignments → sessions → submissions
Key point:
Engagement never duplicates KOE data. It organises it.
8. Engagement + Programmes (clean integration)
8.1 Programme as Engagement template (recommended)
A Programme may define:
- required KOE evaluations
- ordering / gating rules
- completion criteria
When starting real work:
- Programme → creates an Engagement
- Engagement issues assignments from Programme rules
This preserves your existing Programme investment.
8.2 Engagement without Programme (allowed)
For ad-hoc or one-off work:
- Engagement created manually
- Tasks added explicitly
Same execution path, same ledger semantics.
9. Why Engagement is WORM-significant (even if not all data is WORM)
Important distinction:
- Engagement header: mutable
- Engagement events: append-only
- KOE submissions: append-only
Engagement matters because it becomes the unit of attestation.
You don’t ratify a submission. You ratify an engagement state.
10. Hashing at the Engagement level (why this matters)
This is the real payoff.
10.1 What gets hashed
At a milestone or closure:
- ordered list of submission IDs
- their snapshot hashes
- engagement event history
- evidence metadata hashes
- timestamps
Result:
engagement_state_hash
10.2 What that proves
“This exact set of work, as grouped, reviewed, and presented, existed at time T and has not changed.”
This is impossible to prove without Engagement.
11. Ratification (plain English)
Ratification means:
“An authorised party formally signs off this engagement state.”
It is:
- not approval of one form
- not approval of one submission
- approval of the whole job as represented
Ratification is stored as:
- an engagement ledger event
- referencing the state hash
- with signer identity + step-up proof
12. Client Glass Box (why Engagement is essential)
The Client Portal shows:
- one Engagement
- its timeline
- its submissions
- its amendments
- its evidence
- its ratification (if any)
Without Engagement:
- you can only show disconnected attempts
With Engagement:
- you show a coherent, defensible story
13. Why this is the cleanest long-term approach
To answer your explicit goal:
“I want whatever is better for the long-term goals of the product.”
Engagements give you:
- enterprise-grade defensibility without enterprise UX
- optional cryptographic proof without forcing it everywhere
- client transparency without leaking authoring complexity
- reuse of existing Programmes without overloading them
- zero duplication of KOE execution data
Most importantly:
Engagements let Evalium evolve from “a system of records” into a system of proof.
14. One-paragraph summary
An Engagement is not another execution mechanism. It is the binding context that turns many correct WORM submissions into a defensible account of real-world work, enables hashing and ratification, powers the Client Glass Box, and cleanly instantiates Programme templates without distorting them.