The ordered run log is Nano's most differentiated feature. The JSON plumbing already exists — LogEntry.to_dict() in nano/runtime/effects.py, ModuleResult.to_dict() in nano/runtime/vm.py, surfaced through nano run --report json in nano/cli/commands.py.
What's missing is what makes it usable as an audit artifact by anyone outside this repo:
-
A documented, stable schema. Right now the shape is whatever to_dict() happens to emit. Nothing states which fields are guaranteed, what each means, or what a consumer may rely on across versions. Without that, external tooling is written against an accident.
-
A golden-file test proving determinism at the serialisation layer. Replay determinism is tested, but not that two identical runs emit byte-identical JSON. Key ordering, float formatting, and timestamp handling can all drift without breaking any current test — and byte-stability is exactly the property an audit trail is claimed to have. A golden-file comparison would pin it.
Together these turn "we emit a run log" into "you can diff, archive, and hand this to someone asking questions."
Worth flagging: LogEntry.timestamp may need an explicit rule for how it's produced during replay, since a wall-clock value would defeat byte-stability by construction. If that's already handled, the schema doc is the place to say so.
The ordered run log is Nano's most differentiated feature. The JSON plumbing already exists —
LogEntry.to_dict()innano/runtime/effects.py,ModuleResult.to_dict()innano/runtime/vm.py, surfaced throughnano run --report jsoninnano/cli/commands.py.What's missing is what makes it usable as an audit artifact by anyone outside this repo:
A documented, stable schema. Right now the shape is whatever
to_dict()happens to emit. Nothing states which fields are guaranteed, what each means, or what a consumer may rely on across versions. Without that, external tooling is written against an accident.A golden-file test proving determinism at the serialisation layer. Replay determinism is tested, but not that two identical runs emit byte-identical JSON. Key ordering, float formatting, and timestamp handling can all drift without breaking any current test — and byte-stability is exactly the property an audit trail is claimed to have. A golden-file comparison would pin it.
Together these turn "we emit a run log" into "you can diff, archive, and hand this to someone asking questions."
Worth flagging:
LogEntry.timestampmay need an explicit rule for how it's produced during replay, since a wall-clock value would defeat byte-stability by construction. If that's already handled, the schema doc is the place to say so.