TN-007: Output Filename Convention¶

Summary¶

Measurement output files are saved under <workspace>/YYYYMMDD/events_<mac>_<timestamp>_<file_id>.jsonl. The format prioritizes human readability and shell usability over strict standards compliance.

Background¶

Long-running measurements produce many JSONL files. A consistent naming convention is needed so that:

• Files sort correctly by date and time in a directory listing
• The device identity (MAC address) and session position (file ID) are immediately visible
• Filenames work without escaping in shells and file completion

Decision¶

Files are stored under a date subdirectory inside the workspace root:

<workspace>/
└── YYYYMMDD/
    └── events_<mac>_<timestamp>_<file_id>.jsonl

Workspace root is resolved from KAZUNOKO_WORKSPACE env var, falling back to . (current directory). The current-directory default was chosen so that users who have not configured an environment variable are not surprised by files appearing in an unexpected location.

Date subdirectory (YYYYMMDD) groups files by day — the natural unit of a measurement session. The directory changes when the date changes, which means a measurement that runs past midnight will split across two directories. This is intentional: splitting by day is preferred over accumulating all files in a single directory indefinitely, in anticipation of long-span continuous measurements. Files from a multi-day run can be joined at analysis time by reading across directories; the reverse — splitting a flat directory into per-day groups after the fact — is much harder. No further subdirectory nesting is defined yet; multi-site or multi-device directory structure will be decided separately when those use cases become concrete.

Filename components:

Full example: events_aabbccddeeff_2026-03-04_09h48m41s_0000000.jsonl

The timestamp format YYYY-MM-DD_HHhMMmSSs avoids : (which breaks shell tab-completion) while remaining immediately interpretable. The MAC address colons are removed and letters lowercased so it can appear in a filename without quoting. The 7-digit zero-padding ensures lexicographic sort order matches numeric order and provides headroom for even multi-day continuous runs (~10 million files).

Multiple sessions on the same day write into the same YYYYMMDD/ directory. Because filenames are timestamp-based, files from different sessions do not overwrite each other. If measurement conditions change between sessions (e.g., different thresholds), users should separate sessions by renaming the directory (e.g., YYYYMMDD_run01/) to avoid mixing incompatible data.

Run number management is the user's responsibility, not the system's. Users sometimes need to delete or redo a failed run; automatically assigning sequential run numbers would make it harder to discard bad data cleanly. The recommended convention is to rename YYYYMMDD/ to YYYYMMDD_runNN/ after each completed session, with the run number incrementing continuously across days:

20241216_run01/   ← first session (e.g., threshold scan)
20241216_run02/   ← second session (e.g., cosmic measurement)
20241217_run03/   ← next day — run number continues, does not reset

The run number is a simple sequence counter and carries no metadata on its own. Details about each run — conditions, thresholds, notes — are expected to be recorded separately by the user (e.g., in a spreadsheet or logbook).

Alternatives Considered¶

Consequences¶

• Files sort correctly by date → device → time → sequence in any file manager or ls output.
• generate_filename(mac_address, file_id) is the single source of truth; all scripts call it rather than constructing paths manually.
• The date subdirectory is created with path.parent.mkdir(parents=True, exist_ok=True) at write time — callers do not need to pre-create it.
• Multi-site or multi-device directory nesting is not yet defined and will require a separate design decision when those workflows are formalized.