Audit log

Every command, verdict change, equipment connect/disconnect, and sequence event is recorded, so you can always reconstruct what happened and when. The audit log writes to two places at once:

• A SQLite database (starship_audit.db by default) — the complete, hash-chained record of every event, queried by the Audit Log page.
• A human-readable operations log (starship_monitor.log by default) — one plain-text line per event, the file you actually open and read (or grep) when you want to see what the rig did overnight.

Both live in the working directory. The audit log is on by default.

What's recorded

The log subscribes to everything on the event bus, so in practice it captures the whole life of the session:

• Console commands (capture, slew, focus, filter, cooler, halt) — with whether each one succeeded and the error text if it didn't
• Capture / focus / other jobs starting, finishing, or failing, including the saved frame's path
• Safety verdict changes with the reasons and source
• Solo / weather readings (sky-minus-ambient, wind, humidity, reading age, overall safe/unsafe)
• Autofocus samples (each V-curve measurement and the fit summary)
• Equipment connect / disconnect events
• Sequencer run start / pause / resume / stop / step events
• Plain log messages from any module

Each database entry includes a timestamp, the source module, the topic, the full payload, and a hash of the previous entry plus this one's content.

The operations-log line for each event is compact and greppable: timestamp topic source summary. A couple of pure-noise topics (safety heartbeats, jog nudges) are left out of the text file so it stays readable.

The Audit Log page

The Audit Log page shows the most recent events live. Two buttons:

• Refresh re-loads the latest events.
• Verify chain walks the entire hash chain and tells you whether it's intact — a green "chain valid" or, if anything has been altered, "chain broken" together with the id of the first bad row.

The Starship Monitor card on the dashboard also has a download log link that hands you the current operations-log file, and the one-click diagnostics bundle includes a tail of the audit log for remote debugging.

Keeping the log readable

High-frequency snapshot topics — CCTV and all-sky camera frames — fire many times a second and would otherwise drown out everything else. By default those are kept out of both the database and the text file, so what remains is the operational story, not a wall of image events. You can adjust which topics are excluded (matched by exact name or by prefix), or set the exclusion list to empty to log absolutely everything.

If you run through the night, you can turn on nightly rolling so the operations log starts a fresh file for each observatory-night. The active file is named with a noon-anchored date (for example starship_monitor_2026-03-06.log, which covers the evening of the 6th plus the morning of the 7th), and it rolls automatically at local noon. Off by default, which keeps everything in a single file.

Hash chain

Records are hash-chained: each row's hash is computed over its content plus the previous row's hash. Tampering with any row invalidates every row after it. This isn't tamper-proof against someone with write access to the DB file, but it is tamper-evident — the Verify chain button (walking the chain) will detect any modification and point you at the first altered row.

What it's for

• Postmortem. Something happened at 3am — what was the supervisor saying? What command did the sequencer issue? Did it succeed? The audit log answers all of these.
• Research provenance. When you publish data, you can trace each frame back to: which target, which filter, which sequence run, which environmental conditions at the time of capture.
• Regression testing. If a sequence misbehaves, replaying the audit log against the same plan reveals where the divergence happened.

Settings and limits

The audit database isn't garbage-collected automatically — it grows over time. There's a retain_days setting (90 by default) reserved for a future retention policy, but nothing prunes the database today. For a single-observatory installation that's fine — the event rate is low, and excluding the snapshot topics keeps it modest. For multi-instance deployments later we'll enforce retention properly.

You can also point the database and operations log at different paths, or disable the audit log entirely, from the audit settings.