Executions & Events¶

Procnote uses event sourcing to manage execution state. Every action the operator takes is recorded as an immutable event in an append-only log.

What is an Execution?¶

An execution is a recorded instance of running a procedure template. It consists of:

• An event log (events.jsonl) -- the single source of truth
• A template snapshot -- the procedure as it was when the execution started
• Attachments -- any files uploaded during the execution

Event Log¶

The event log is a JSONL file where each line is a JSON object representing one event. Events are appended sequentially and never modified or deleted.

Each event carries:

• A type discriminator (e.g., StepSkipped, CheckboxToggled)
• An at timestamp (ISO 8601)
• An execution_id
• Event-specific payload fields

Event Types¶

Lifecycle Events¶

Step Events¶

Data Capture Events¶

Metadata & Audit Events¶

State Machine¶

The current execution state is the combination of one execution lifecycle, step presence/skip state for each UI step, and captured data state for each checkbox, input, attachment, and note. Events are applied by replaying the log in order; LogMeta is replay metadata rather than a direct state transition.

Execution Lifecycle¶

stateDiagram-v2
    direction LR

    [*] --> Pending

    Pending --> Active: ExecutionStarted

    Active --> FinishedPass: ExecutionCompleted(Pass)
    Active --> FinishedFail: ExecutionCompleted(Fail)
    Active --> FinishedAborted: ExecutionCompleted(Aborted)
    Active --> FinishedAborted: ExecutionAborted

    FinishedPass: Finished(Pass)
    FinishedFail: Finished(Fail)
    FinishedAborted: Finished(Aborted)

    Active --> Active: StepAdded / StepSkipped / StepUnskipped
    Active --> Active: CheckboxToggled / InputRecorded / InputCleared
    Active --> Active: AttachmentAdded / AttachmentRemoved
    Active --> Active: NoteAdded / NoteRemoved
    Active --> Active: ExecutionRenamed

    FinishedPass --> Active: ExecutionReopened
    FinishedFail --> Active: ExecutionReopened
    FinishedAborted --> Active: ExecutionReopened

    FinishedPass --> FinishedPass: ExecutionRenamed
    FinishedFail --> FinishedFail: ExecutionRenamed
    FinishedAborted --> FinishedAborted: ExecutionRenamed

Lifecycle rules:

Step State¶

Steps are primarily UI/grouping units for procedure content and captured data. Procnote does not model “starting” or “completing” each step; the current/selected step is UI state, not event-sourced domain state.

stateDiagram-v2
    direction LR

    [*] --> NotPresent
    NotPresent --> Present: StepAdded

    Present --> Present: data events
    Present --> Skipped: StepSkipped
    Skipped --> Present: StepUnskipped

Here, data events means checkbox, input, attachment, and step-scoped note events. The implementation requires the execution to be active and the step to be present, not skipped.

Step state rules:

Data State¶

Data state is modeled per data item. Data events require the execution to be active. Step-scoped data also requires the referenced step to be present, not skipped; global notes are scoped to the execution instead.

Checkbox State¶

stateDiagram-v2
    direction LR

    [*] --> Unchecked
    Unchecked --> Checked: CheckboxToggled(checked=true)
    Checked --> Unchecked: CheckboxToggled(checked=false)

Input State¶

stateDiagram-v2
    direction LR

    [*] --> Empty
    Empty --> Recorded: InputRecorded
    Recorded --> Empty: InputCleared

Attachment State¶

Attachment inputs can contain zero or more files. A single operator action can add one file or a batch of files.

stateDiagram-v2
    direction LR

    [*] --> Empty
    Empty --> HasFiles: AttachmentAdded / AttachmentsAdded
    HasFiles --> HasFiles: AttachmentAdded / AttachmentsAdded
    HasFiles --> HasFiles: AttachmentFileRemoved
    HasFiles --> Empty: AttachmentFileRemoved (last file)
    HasFiles --> Empty: AttachmentsCleared / AttachmentRemoved

Note State¶

stateDiagram-v2
    direction LR

    [*] --> NotPresent
    NotPresent --> Present: NoteAdded
    Present --> Removed: NoteRemoved

Data state rules:

Together, the lifecycle, step, and data diagrams cover all state-affecting event types. LogMeta is the only event type that is purely replay metadata.

State Reconstruction¶

Execution state is never stored directly. It is always reconstructed by replaying the event log in order. Every event is applied; metadata events such as LogMeta are ignored by the state machine.

This means the app can crash at any point and recover perfectly by re-reading the log on restart.

Reversing Actions¶

Procnote does not model reversal as a generic “undo event” that points at a previous log entry. Operators do not edit the event log; they take another domain action in the UI. The event log records that action explicitly.

This keeps replay simple: apply every event in order.

It also keeps reversibility type-checked. Reversible concepts have explicit event variants and explicit state-machine transitions. Adding a new event type requires deciding, in the event and state-machine code, whether it is irreversible or what typed domain action reverses its effect.

The original event remains in the log and the reversing action is appended. This preserves a complete audit trail: you can see what was done, what was later changed, and the reason where the UI captures one.