Flattened End & Debug State System

The launcher writes a small set of JSON metadata files into each session folder using a flattened structure to simplify downstream tooling.

Files Generated

processed_parameters.json – final merged parameters (rig config + JSON + runtime prompts).
end_state.json – final experiment outcome and core identifiers.
debug_state.json – only created when an unexpected exception/crash occurs.
session.json – created by post-acquisition tools (e.g. session_creator) from the above.

End State Schema (Flattened)

Example:

{
    "session_uuid": "4fe1c6a0-2f5d-4f7e-9c44-5c2e9f6a9e1a",
    "subject_id": "mouse_001",
    "user_id": "researcher",
    "start_time": "2025-06-21T10:30:00.123456",
    "stop_time": "2025-06-21T10:45:30.654321",
    "process_returncode": 0,
    "rig_config": {"rig_id": "behavior_rig", "COM_port": "COM5"},
    "experiment_data": {"experiment_notes": "Good behavioral engagement"},
    "version": "<launcher_version>"
}

Debug State Schema

The debug file captures a crash snapshot with a dedicated crash_info block and a shallow serialization of the launcher state.

{
    "session_uuid": "4fe1c6a0-2f5d-4f7e-9c44-5c2e9f6a9e1a",
    "timestamp": "2025-06-21T10:40:05.001234",
    "exception": "ValueError('Invalid parameter value')",
    "traceback": "<stack trace>",
    "crash_info": {
        "exception_type": "ValueError",
        "message": "Invalid parameter value",
        "crash_time": "2025-06-21T10:40:05.001234"
    },
    "launcher_state": {
        "subject_id": "mouse_001",
        "user_id": "researcher",
        "session_uuid": "4fe1c6a0-2f5d-4f7e-9c44-5c2e9f6a9e1a"
        // ... additional shallow, JSON-safe fields ...
    }
}

Crash handling automatically writes this file before termination.

Session Creation (Post-Acquisition)

The session_creator module reads end_state.json + processed_parameters.json to build a standards-compliant session.json. If missing timestamps, it falls back gracefully and logs warnings.

Why Flatten?

Easier ingestion by lightweight tools
Reduced nesting ambiguity
Clear boundary for launcher vs. custom extension data

Best Practices Summary

Treat end_state.json as an append-only schema (stable top-level keys)
Never mutate or delete previous experiment metadata files mid-run
Keep debug states for crash forensics; do not rely on them for normal analytics