Skip to main content

Change Log: Archival Semantics, Delivery Snapshots, and Usage Endpoint

What Changed​

  • Archival on delete when in use: DELETE /evaluations/\{id\} now archives the evaluation if submissions or active sessions exist, instead of failing with a raw FK/23503. The handler returns a structured 409 with counts and archived=true.
  • Usage visibility: Added GET /api/v1/evaluations/\{id\}/usage, returning { submissions, activeSessions, archived } so clients know why delete is blocked and can guide users.
  • Session gating: Delivery session creation is blocked for archived evaluations.
  • Result snapshots: Submissions now store a frozen version_snapshot (sections/items/questions/payloads) at submit time. Submission responses include this snapshot so result rendering can use the frozen state rather than live authoring.
  • Results endpoint: Added /api/v1/submissions/\{id\} to fetch a submission with its stored version_snapshot and submission_items in one response, keeping result views decoupled from live authoring data.
  • Feedback config endpoint: Added PATCH /api/v1/evaluations/\{evalId\}/versions/\{versionId\}/feedback to set feedbackTagKeys per evaluation version. On submission, the current keys are copied into the snapshot and feedbackTags are derived from structured tags so historical submissions keep their config. Admin views see full tags; candidate views use the frozen feedbackTags.
  • Delivery script parity: backend/tests/delivery_session.sh cleanup accepts archive-on-delete semantics; script runs end-to-end without failing on submissions.

Why We Made These Changes​

  • Preserve results integrity: submissions/results should survive authoring edits or deletes via a stored snapshot.
  • Safer deletion UX: prevent accidental data loss by archiving when results/sessions exist, and surface clear usage counts to the client.
  • Align with roadmap: move toward a snapshot-based results model (Option B) and explicit archive semantics for in-use evaluations.
  • Reduce test friction: ensure E2E scripts reflect the new lifecycle (archive instead of hard delete when results exist).

Impact​

  • API behavior:
    • Delete: in-use evaluations return 409 with usage details and are archived; clean evaluations still hard-delete with 204.
    • New usage endpoint enables frontend to show actionable messages before delete.
    • Session creation now rejects archived evaluations.
  • Data model:
    • submissions.version_snapshot persists the evaluation graph used at submission time.
    • Results rendering can (and should) prefer version_snapshot when present.
  • Tests/scripts:
    • Integration tests cover delete usage response and snapshot presence.
    • delivery_session.sh passes under the new archive semantics.

Next Steps​

  • Add a results fetch endpoint/view that renders from version_snapshot, falling back to live authoring only if missing.
  • Optionally expose usage info in delete 409s and UI via the usage endpoint.
  • Continue porting flows to Go integration tests with the shared helpers and snapshot assertions.