Developer guide

Assessment state, snapshots, autosave, and results

Preserve the decisions that produced an exam attempt and result instead of reconstructing them from mutable records.

MaintainerIntegratorReviewer

Marking and publication state. Objective and manual marks become a result only after required review, moderation, approval, and publication.

Responsibility

Assessment state is historical evidence. Approved question revisions, exam snapshots, assignments, attempts, answers, integrity events, marks, moderation, approvals, publication, holds, rechecks, and documents must remain distinguishable.

Components and data flow

Question revisions progress from draft through review and approval.
Published exams pin question snapshots and delivery rules.
Attempts receive versioned answer updates, heartbeats, events, and a final submission state.
Objective and manual grades feed moderation and result calculation.
Approval/publication gates control portals, documents, reports, and outbound exports.

Rules that must remain true

Approved question content used by a published exam is not rewritten in place.
Autosave rejects or reconciles stale versions without losing the latest accepted state.
Submission is authoritative and idempotent.
Published-result consumers read finalized persisted state.
Corrections, rechecks, holds, unpublication, and revocation create audit history.

Failure modes

Reading a current question instead of the pinned snapshot changes historical meaning.
Last-write-wins autosave can silently erase a newer answer.
Calculating reports from draft grades exposes incomplete results.
Regenerating documents without revocation rules creates conflicting records.

Safe extension guidance

Model transitions explicitly and reject invalid source states.
Store the actor, time, reason, and relevant prior/new values for sensitive transitions.
Keep calculation deterministic and test fixed fixtures.
Notify and export only after the primary state transaction commits.

Required tests

Question revision and published-snapshot immutability.
Concurrent answer versions, reconnect recovery, repeated submission, and time expiry.
Objective/manual grading, moderation disagreements, holds, rechecks, approval, publication, and unpublication.
Documents, portals, reports, and exports agree with published state.

Release gate: Replay a complete seeded assessment from approved question through published result and verify every transition and consumer.