Module sidecar 

On-disk state sidecars: the soft schema-version check, the atomic writers, and the one freshness-gated reader.

A state sidecar is a small JSON snapshot a service drops under the run directory (/run/ados/*.json) so the REST and heartbeat surfaces can read its state without an IPC round-trip. Unlike the frozen wire contracts, a sidecar is best-effort: a reader must tolerate a file written by an older or newer agent rather than reject or crash on it.

So the version discipline here is deliberately softer than the wire contracts: when a sidecar’s declared version does not match the value this build expects, check_sidecar_version logs a warning and returns false but the reader keeps using the data. A stale sidecar written by an older agent (which had no version field at all, so it reads back as 0) must never brick a reader — it warns once and proceeds.

Each sidecar’s expected version is registered in crate::contracts and mirrored by a per-file constant on the writer side; a reader passes both to check_sidecar_version at its deserialize site.

Freshness: a producer rewrites its sidecar whole on each tick, so the file’s mtime is the age of the reading inside it, and a producer that died leaves its last file behind until reboot. read_fresh reads a registered sidecar and classifies it against the registry’s max_age_ms window; a future mtime (a clock that stepped backwards) makes the age unprovable and reads as Reading::Stale, never as a fresh measurement.

Structs

Versioned

A minimal mixin for peeking a sidecar’s schema version.

Enums

Reading

The outcome of a freshness-gated sidecar read.

Functions

check_sidecar_version

Compare a sidecar’s declared schema version against the version this build expects.

file_age

A file’s mtime age relative to now, or None when the file is absent, its mtime is unreadable, or its mtime is after now (an unprovable age).

read_fresh

Read the registered sidecar id from its resolved path (crate::paths::run_path) and classify it against its registered freshness window. An unregistered id reads as Reading::Malformed.

read_fresh_at

The path-injectable core of read_fresh: read path as T and classify it against max_age (None = no window, every parsed read is fresh). A future or unreadable mtime is Reading::Stale.

write_atomic

Atomically replace path with data at file mode mode.

write_durable

Replace path with data so a power cut leaves either the old file or the new one, never a truncated mix. The replacement keeps the target’s permissions when the target exists and is created 0644 otherwise. See write_atomic for the write sequence.

write_json_atomic

Serialize value as JSON and write it through write_atomic.