feat(events): edit a published geolocation as a new revision

[vidit-admin]

What

A geolocated event was frozen. An analyst who mistyped a coordinate while confirming detections had no way to fix it, and no path that would have preserved what the record said before the fix.

This adds the revision model and the owner's correction path.

• events.revision_no says which version the live row is. It starts at 1 (every existing row backfills there) and moves forward one step per correction. A version number is a public address, so it only ever increases and a revision is never deleted.
• event_revisions is append-only: one row per superseded version, holding who edited, when, an optional note, and a JSONB snapshot of the editable fields as they stood. History reads as "the snapshots, then the live row", so the publication paths (create_with_evidence, geolocate, _publish_detection) are untouched: version 1 is the published row itself.
• POST /events/{id}/revise (owner-only, geolocated-only) files the snapshot, applies the edit and increments the row, in one transaction under the same row lock close and geolocate take, so two concurrent edits take their numbers in order rather than racing.
• GET /events/{id}/revisions reads the superseded versions back, newest first. Public, like the event: a corrected record is auditable only when its corrections are readable.
• /events/{id}/edit no longer turns a published row away. One form, two shapes, selected by the row's state: Submit detection as before, or Edit geolocation with an optional edit note and a Save revision that writes on the click that made it. The event page gains Edit this geolocation for its author, behind the existing ⋯ menu, and prints v2 beside the byline once an event has been corrected.

/events/{id}/history and /events/{id}/vN land here too; see Version history below.

The editability contract

After publication the evidence anchor is immutable: source_url and the source media are what the published claim rests on. The endpoint declares no field for either, so it cannot be asked to move them, and the form renders both read-only under a lock marker whose ? says why. A wrong source is still handled by closing the event with a reason and posting it again, or by an admin.

Everything else the publish form wrote is editable and versioned: title, both coordinate sets, the event date and hour, the source post time, the graphic flag (still ratcheting), tags, conflicts, the proof body with its inline images, and the secondary source links, which are mirrors rather than the evidence origin and sit outside the anchor. source_snapshot_url is accepted, since it archives the anchor rather than changing it.

Two invariants ride with it:

• The published floor is re-checked on the post-edit state, so a correction cannot drop the row below what publishing it required: a source media on the row, a proof image in the final body, one conflict, one capture_source tag.
• A proof image a past version still shows is never deleted. Media are not versioned, so the shared intake asks the snapshots before dropping a proof row the current body no longer references.

Errors: 403 for anyone but the owner, 404 for a soft-deleted or withheld row, 409 invalid_state off geolocated, and the existing 400 floor codes (invalid_coordinates, invalid_proof, proof_image_required, tag_requirements_not_met, media_required, too_many_source_links, the file and snapshot codes). 422 caps note at 280 characters.

Tests

• Backend, tests/events/test_revisions.py (10 new): the happy path (snapshot holds the pre-edit state, row moves to version 2), owner-only 403, 409 off each of detected / requested / closed, the anchor unmoved when source_url / files / remove_media_ids are posted anyway, the floor held on a dropped conflict and an image-less proof, a proof image kept because a version still shows it, the history read (ordering, note, editor, empty before any edit, 404 unknown), and two concurrent revises taking their numbers in order under the row lock.
• Frontend, app/events/[id]/edit/page.test.tsx (6 new): the lifted gate, the read-only anchor, saving on one click and landing on the event, the note posted and the anchor never assembled, the floor held before posting, and a state with no owner edit.

Review fixes

Round 1

Follow-up commit on the same branch, one item per review finding.

1. Owner actions are scoped per surface. TIERS.event.owner put "Close this request" and "Delete this request" on /events/{id}, which serves rows of any status. The owner tier splits into revise (event page) and dispose (request page); new useEventActions.test.tsx pins that a requested or closed row on the event surface offers no request verb.
2. A snapshot pins only the images its own body displayed. build_snapshot recorded every role == "proof" row, so the snapshot the revise had just staged claimed every existing image and nothing was ever deleted, while later versions claimed images they never showed. proof_media is now the intersection with extract_image_srcs(geo.proof), and the keep set is the current body plus what readable (non-redacted) versions display.
3. source_posted_at is optional on revise. _publish_detection publishes with the column NULL, so the required field made such a row uneditable. Absent or empty keeps NULL; the frontend floor takes a requireSourcePostedAt option, false in revise mode and true on the confirmation path, matching geolocate.
4. The proof-image cap bounds the event, not the request. max_proof_images_per_event now counts the rows this write keeps plus the files it adds, before anything reaches S3. Message and api.md updated.
5. An admin reads a withheld row's history. GET /events/{id}/revisions mirrors get_event's optional-current-user branch.
6. Redaction, shipped. POST /admin/events/{id}/revisions/{revision_no}/redact, admin only, audited as event_revision_redacted, idempotent. Blanks snapshot and note, stamps redacted_at / redacted_by_id, and keeps the row, its number, its date and its byline so /vN never shifts. EventRevisionRead gains redacted. A redacted version contributes nothing to the media keep set, so redacting the last version that displayed a proof image deletes that image, row and object, on the same commit-then-sweep discipline. Migration g5i7k9m1o3q5.
7. The wrong-source remedy is reachable. close rejects a geolocated row, so the "close it and post it again" copy pointed nowhere. fieldHelp.evidence_anchor, the revise docstring, api.md and CHANGELOG.md now say a wrong source on a published event is an admin matter.
8. "Freezes" is gone. CONFIRM_SENTENCE, fieldHelp.action_submit, the EventEditInput doc comment and the EventStatus comment say publishing makes the event public and later changes become versions, with the source fixed. Tests that pinned the old sentence updated.
9. The history is paged. services/pagination cursor, Link: rel="next", limit clamped at 100, ordered created_at DESC, id DESC (which is revision_no DESC on an append-only per-event history written under the row lock). total is a real count, replacing MAX_REVISIONS = 200 truncating with total = len(items).
10. AGENTS.md lists lib/events.ts::EDIT_NOTE_MAX_LEN mirroring schemas/event.EDIT_NOTE_MAX_LENGTH.

One deviation from the brief: the redact verb lives in routers/admin.py under /admin/events/... rather than on the public events router, to sit beside PATCH /admin/events/{id}/moderation and share require_admin plus log_admin_event.

Round 2

Second follow-up commit, one item per finding. Items 4 and 9 above are superseded by items 1 and 4 here.

1. The proof-image ceiling counts what the new body displays. Counting the rows a write keeps charged the owner for images pinned only so an old version stays renderable, so an owner who swapped images across corrections spent the quota permanently with nothing left to free. attach_evidence_and_commit now counts the already-uploaded images the final proof body still references plus the files it adds; history-pinned rows count for nothing. Message, api.md (revise + geolocate) and the cap test updated, plus a new test that two image swaps in a row both pass on a one-image cap while three rows survive on the event.
2. A blank source_posted_at keeps the stored instant. parse_optional_iso_datetime maps a missing and an empty field alike to None and the client always posted the field, so an owner who cleared the input silently wiped the instant a published record was vouched with. revise reads None as "keep": only a parsed value replaces the column, and appendEventFormFields omits the field rather than posting an empty string. Tests: blank keeps the stored date, absent keeps it, a value replaces it, and a NULL row stays NULL through a blank. Frontend test on the assembly, both legs.
3. A proof body may only display this event's own stored images. _safe_image_src checks that an image URL lives on the media host, which says nothing about whose it is, so event B could embed event A's proof image and A's next revise or redact would delete the object out from under B. New _reject_foreign_proof_srcs runs on every path through the shared intake: an src the storage layer wrote (key_from_url resolves it) has to match one of this event's role='proof' rows, otherwise invalid_file (400). Create and geolocate carry placeholders or the event's own rows, so they are unaffected; the whole backend suite confirms it. Tests: a foreign URL is rejected and files no version, the event's own image is accepted.
4. The history orders and pages on revision_no. The keyset ran on created_at, which the application clock sets and which therefore skews between instances, while the endpoint claimed revision_no order. list_revisions now orders and cuts on revision_no (unique per event, taken under the row lock, so no tiebreaker column is needed). services/pagination gains encode_ordinal_cursor / decode_ordinal_cursor beside the (created_at, id) pair, and next_link takes the encoded cursor so one function still builds every Link header. Tests: a history whose version 2 is stamped a day before version 1 still reads and pages 3, 2, 1, and a malformed cursor is a 422.

No deviations from the brief.

Version history

The corrections were filed and served, and nothing read them: a published event printed v3 beside its byline with no way to see what versions 1 and 2 said. Two pages close that, both public, like the endpoint and the event itself.

• A History button sits beside the version pill on a published event, for every reader. It is not an owner control and it sits outside the three action tiers: the tiers act on the record, this one reads it.
• /events/{id}/history is one row per version, newest first: the version number, what its edit changed, then the editor, the date and their note. The whole row is one click, the model every catalogue row uses. A past version opens its own address; the current version opens /events/{id}, because that is where the record as it stands is read. A version an admin redacted keeps its number, its byline and its link, and says so.
• /events/{id}/vN renders the record as that version stood, through the same body the canonical page renders (EventPageBody, fed either the live row or snapshotToEventView(current, revision)), so a version cannot drift into a layout of its own. An amber banner opens it, and the action cluster is absent: sharing, reporting and editing act on the record.
• GET /events/{id}/revisions/{revision_no} is the direct read behind a /vN address, public and visibility-gated exactly like the list. Thin router over revisions.get_revision. The current version's own number answers 404, since the live row is not filed; a redacted version answers with its blanked shape rather than 404, because the version exists and the record still shows that it does.

A row is credited to the edit that produced it

This is the one interpretation worth flagging. A revision row carries the content of the version it holds alongside the byline, date and note of the edit that superseded it, so a row rendered from one payload alone would pair version 2's content with the note about the edit that made version 3. The list pairs version n's content with row n - 1's credit instead, the way a page history reads: who made this version, when, their words about it, and the fields it moved, all describing one edit. Version 1 was published rather than edited, so it reads Published and carries the record's own author and date.

Two consequences:

• The changed fields are computed client-side from the two adjacent versions, since the API serves what each version held rather than what an edit did. They print under the names the event page already uses for the same values (Title, Coordinates, Proof), over the field set build_snapshot files. Tags and conflicts compare by identity, so a referential row renamed under a published event changes no version, and the source post time compares as an instant, so +00:00 against Z is not an edit.
• The walk holds its oldest row back. A version's credit is filed on the version below it, so while Link: rel="next" says there are more pages the oldest loaded row is credit for the row above it rather than a row of its own. It appears once Load more brings the page that completes it: a row is whole or absent, never a version number with no editor beside it.

Routing and canonicality

/events/{id} stays canonical. A version page carries robots: noindex and a canonical link to the event, and asking for the current version's own number forwards there rather than serving the record at two addresses. The route is a [version] segment beside the static edit and history ones, which keeps /events/{id}/vN a one-segment address; Next matches a static sibling first, so edit and history keep their own routes, and parseVersionSegment refuses anything that is not v followed by a version number, which is a 404, as is a number past the current version.

useCursorList gains an optional reader for the rows of a page payload, since the history endpoint answers {items, total} rather than a bare array. The default is unchanged for its two existing callers.

Tests

• Backend, tests/events/test_revisions.py (4 new): the direct read by number, 404 outside the filed history (the current version's number, an unknown number, 0, an unknown event), a redacted version served blanked rather than missing, and the withheld-row branch.
• Frontend: lib/events.versions.test.ts (19) covers the segment parse, the snapshot mapper (the overlay, the immutables, mirrors paired with the copy archived for their own URL, a conflict falling back on its stored name, a redacted {} snapshot), the changed-field diff, and the version assembly including the held-back row and the redaction cases. app/events/[id]/history/page.test.tsx (7) and app/events/[id]/[version]/page.test.tsx (6) cover the rows, the credit pairing, the link targets, Load more, the banner, the redaction notice, the forward to the canonical page and both 404 branches.

Gates

Gate	Result
ruff check / ruff format --check / mypy / vulture	pass
pytest -n auto	pass, 1383 passed / 3 skipped
alembic upgrade head	pass
npm run lint	pass, 0 errors (30 pre-existing warnings)
npx tsc --noEmit	pass
npm test	pass, 599 passed
npm run build	pass
make gen-api-types + git diff --exit-code	pass, in sync
make hygiene (jscpd under the 1% cap, knip, palette coverage, video routes)	pass

The event_revisions Mermaid block in data-model.md was rendered locally with @mermaid-js/mermaid-cli before committing.

🤖 Generated with Claude Code