Attestation
An attestation is a workspace member’s dated assertion that a scene accurately reflects reality. Agents keep the diagram current; the attestation records that a person looked at it and vouched for it. Auditors read the date: a diagram attested last week is evidence, a diagram nobody has vouched for in a year is a drawing.
Recording an attestation
POST /v1/scenes/:id/attest (no body) stamps three fields on the scene:
| Field | Meaning |
|---|---|
attestedAt | When the attestation was made (server clock, UTC) |
attestedByUserId | The signed-in user who made it |
attestedRevision | The revision that was current at that moment |
The scene document is not modified and no revision is created - attesting verifies content, it does not change it. Re-attesting overwrites the three fields, restarting the cycle.
Attestation is human-session-only. API-key callers (agents) receive 403 SESSION_AUTH_REQUIRED. This is stricter than the protection and legal-hold ratchets, where an agent may move the safe direction: there is no safe direction here. An agent attesting to its own output would make the signal circular, and the entire value of attestedAt is that a person put their name on it.
Agents CAN read the attestation fields - they come back on GET /v1/scenes/:id - so an agent can tell a user “this scene hasn’t been attested in 120 days” or route a re-attestation request to a human. It just cannot click the button itself.
Staleness
Freshness runs on a quarterly cycle, computed server-side from attestedAt:
| State | When |
|---|---|
fresh | Attested less than 76 days ago |
due | 76-89 days: inside the final two weeks of the quarter |
stale | 90 days or more |
never | The scene has never been attested |
Separately, a scene whose live revision is above attestedRevision has drifted: its content changed after a human last vouched for it. Drift is independent of age - a scene attested yesterday and edited today is fresh but drifted. When the deterministic importer drift signal lands, staleness becomes the maximum of age and importer drift; the revision comparison ships today.
The dashboard audit view (documented under revisions) shows a badge per scene (state plus drift) and an Attest button. GET /v1/workspaces/audit returns the same status object per scene: { state, attestedAt, attestedRevision, ageDays, drifted }. The status is always the live state - an attestation is a present-tense assertion, not part of the point-in-time revision history, which is why the badge does not change when you move the as-of date.
Reminders
Once a scene has been attested at least once, its owner receives a digest email when attestations cross the 90-day line - one email listing every currently-stale scene, never one email per scene, and each scene is mentioned at most once every 14 days. Re-attesting resets the cycle. Never-attested scenes are not nagged: attestation is opt-in, and they surface as never badges in the audit view instead.