# Field notes: specification review and implementation ## Review decisions The requested separation between recorded evidence and human context fits the application. Inspection found these differences from the illustrative spec: 1. **Bursts are Event/PendingEvent records with occurrences >= 3**, not separate incidents. The live browser listener has no server-side event until submission. `FieldNoteContext` is a small, author-owned association record, with no incident timestamps, count, audio or classification of its own. It holds a draft UUID and later references the existing PendingEvent or Event. Multiple notes attach once to that report rather than being copied across individual bangs. 2. **Pending manual ownership was session-based.** Note contexts preserve author attribution across sessions without inventing ownership for old reports. New draft tokens are signed, author-bound and expire after seven days. A submitted token cannot be reused for another report; the UI rotates it on success. Late note saves still follow the original report through moderation. 3. **The frontend uses custom SCSS, HTMX and existing theme tokens**, not Bootstrap. These conventions are reused; no second CSS framework is introduced. 4. **There was no incident export pipeline or event merge UI.** Added CSV/JSON note exports through one permission-filtered service. PDF export and event regrouping interfaces remain outside this pass. A tested regrouping service preserves note provenance for future merge operations. 5. **Corrections are new notes.** No edit/delete route or editable admin form is provided. This keeps original text and entry timestamps unchanged. Verification labels describe the author's stated assessment, not automated validation. 6. **Timezone follows Django's active timezone**, currently Europe/Amsterdam; there is no per-user timezone setting. Datetimes are stored timezone-aware, with the timezone shown beside entry/observation times. Adding a user timezone preference later can use the same fields. ## Privacy and permissions - Notes default to private, unknown source and unverified. Only content is required. - An authenticated author can read/create their own notes. Reportable notes are still not public and do not become verified. - Approved events are already public; authenticated users may add their own notes to them. Pending targets require existing session ownership, sensor ownership, a note context owned by that user, or staff `view_pendingevent` permission. - `view_all_fieldnotes` explicitly allows reading other authors' private notes. Staff status alone does not. Django superusers have this permission. - `export_reportable_fieldnotes` explicitly allows exporting other authors' reportable notes. Without it, exports contain only the caller's reportable notes. **Private notes are excluded even for superusers.** Read-all permission does not imply export-all permission. - Every export starts with `field_notes.reportable_notes(user)`. Future PDF/API reporting must use this service, rather than `visible_to()` or raw relations. - CSV escapes formula-like user values; HTML renders escaped plain text and keeps line breaks. Public event/map responses do not serialize note data. - Link operations are author-only, POST/CSRF-protected, and only accept an existing approved event. Existing linked notes cannot be silently reparented through the user endpoint. Each standalone observation context can hold several live notes; linking it moves that observation's notes together. - Admin is read-only and uses the same visibility boundary. Association history is similarly scoped. ORM `save()` rejects note/history edits; direct SQL or `QuerySet.update()` is not an application editing interface and must not be used to bypass this policy. ## Lifecycle and interfaces - The dashboard's Add field note form is adjacent to quick reporting and updates only its own HTMX region, leaving listener/audio controls mounted and running. - Submission binds the draft context to Pending Review. Approval atomically moves contexts to the approved Event and records the moderator (or system/null actor for non-request approvals). Notes retain their original entry timestamps. - Denial/deletion clears the foreign key but preserves the note and its historical target ID. The observation remains available in My field notes. - `regroup_event_notes(actor, source, target)` requires staff, `change_event` and `view_all_fieldnotes`. Existing or future merge code must call it inside its transaction before deleting the source. It moves associations without copying notes and records previous/current event IDs. No automatic grouping is added. - Historical event details show only visible notes and counts. Direct event pages and the archive now have normal links for no-JavaScript access. - `/fireworks/notes/` creates standalone observations and lists accessible notes; event/pending filters provide contextual forms. `/fireworks/notes/export/json/` and `/fireworks/notes/export/csv/` export authorised reportable notes, optionally filtered by approved event ID. - Standard POST forms redirect after saving. HTMX forms return their own updated region; validation responses intentionally use HTTP 200 so HTMX renders errors. - Occurrence and entry dates are displayed separately. New information is appended chronologically; author-supplied observed time does not reorder entry history. ## Validation and deployment Migration `0014` adds three tables, constraints and an author/time index. It does not rewrite existing event data. Apply with `python manage.py migrate` after updating the application; build assets with the existing `npm run build` command. No firmware changes or version bump are needed for this Django-only feature. Automated tests cover defaults, escaping, anonymous/cross-user access, explicit staff permissions, private export exclusion (including superuser), source and uncertainty preservation, observed/entry timestamps, append-only saves, invalid forms, active draft binding, approval, late saves, stale-token rejection, standalone linking, regrouping and denied-report retention. Browser verification uses the actual Django application with an isolated SQLite DB under `/tmp`. It covers HTMX note saves during a **synthetic browser audio stream**, listener continuity, report binding/token rotation, historical notes, mobile/desktop layouts, dark/light appearance, accessibility labels, exports and standard form submission in a JavaScript-disabled browser context. This is not a microphone/hardware validation and does not claim classification accuracy. Out of scope: attachments, CCTV files, witness identity management, PDF generation, new incident/merge interfaces, full timeline redesign, or changing detection logic.