---
type: decision
date: 2026-05-19
project: cpas
tags:
  - cpas
  - snapshot
  - backdating
  - audit
  - mpm
---

# [[CPAS]] — back-dated insert refreshes downstream snapshots

## Context

On `main` branch (post `ba2b631 documentation`, pre any roll-off model overhaul), the CPAS app stores `prior_active_points` as an immutable snapshot at violation insert time. The PDF endpoint reads this snapshot to render "Prior Active Points → New Total → Tier".

When a violation is logged with a back-dated `incident_date` that precedes existing violations, the **new** violation's own snapshot is computed correctly, but **existing later-dated violations' snapshots are stale** — they were frozen before the back-dated event existed and so omit it from their 90-day prior window. Re-downloading their PDFs shows the pre-backdate prior/total/tier.

## Decision

Refresh downstream snapshots on back-dated insert. Treat back-dating as a *timeline rewrite* and exempt it from the otherwise strict snapshot-immutability rule. Negate, restore, amend, and hard delete are NOT timeline rewrites and continue to leave snapshots alone.

## Implementation (in `server.js`)

- New helper `recomputeSnapshotsAfter(employeeId, incidentDate)` finds all violations for the employee with `incident_date > new_date AND incident_date <= new_date + 90 days`, recomputes each via the existing `getPriorActivePoints()` formula, and only writes UPDATEs where the value changed.
- `POST /api/violations` now wraps the insert + recompute in a single `db.transaction()` so a partial failure can't leave the system with a new violation and stale sibling snapshots.
- When refresh affects ≥1 row, a `violation_snapshots_recomputed` audit entry is written with `reason: 'backdated_insert'`, `trigger_incident_date`, and an `affected[]` array of `{id, incident_date, old, new}` for full traceability.
- Forward-dated inserts (the common case) do zero UPDATEs — affected query returns rows but the equality check skips them.

## Docs

- `AGENTS.md` "Prior-Points Snapshot" section updated with the back-dating exception
- `AGENTS.md` "What NOT to Do" updated — the "do not modify prior_active_points" line now carves out the back-dating path explicitly

## Verification

- `node --check server.js` passes
- Not runtime-tested in this session (better-sqlite3 won't compile on local Node v24 — see project file). Verification path: docker build, log V1 with a recent date, log V2 with an earlier back-dated date, re-download V1's PDF, confirm "Prior Active Points" now includes V2.

## Relationship to roll-off model overhaul

The existing `projects/cpas.md` "Roll-off model fix (2026-05-27)" section describes a *different* implementation of `recomputeSnapshotsAfter` that widens the window to "all later violations" under a clean-cycle roll-off rule. That work is not on `main` as of today. If/when the roll-off overhaul lands on `main`, the helper's window scope will need to be widened to match (current scope is the legacy 90-day rolling window).