---
desc: The state model for one public Sirno entry file.
lifecycle: Active
name: Entry Lifecycle
structural:
  category:
  - concept
  belongs:
  - sirno-lake
  refines:
  - entry
---

## Model

An *entry lifecycle* describes how one public Markdown *entry* moves through the lake.
The public file is the working form.
Sirno Frost is the committed reference line when Frost is configured.
The state definitions use *waterline* for the current public *lake*
and *frostline* for the latest Frost snapshot.

The lifecycle has stored states and check gates.
Stored states are visible from files, Frost snapshots, and the lock file.
Check gates are predicates that commands require before they continue.
`sirno check`, `sirno query`, `sirno rg`, `sirno witness`, and `sirno status`
observe entries without changing their lifecycle state.

## Transition Maps

The maps below separate transition families so each diagram stays readable.
Each node is a lifecycle state.
Each edge is a command or event that moves one entry between states.

### Creation And Editing

Creation and ordinary editing are public-lake operations.
They create or change the working file before Frost is involved.
Edits, render operations, and renames keep an entry in the working state,
so they are explained below rather than drawn as state changes.

```mermaid
stateDiagram-v2
    [*] --> absent

    absent --> working: new / init / manual file
    working --> absent: delete file
```

### Review And Commit

Review and commit move a valid working file set into the aligned state.
The reviewed state is a command gate,
not a flag stored on the entry file.
A failed check or no-op commit leaves the entry in its existing state,
so those cases are described in prose.

```mermaid
stateDiagram-v2
    working --> reviewed: check succeeds
    reviewed --> aligned: frost commit
    reviewed --> working: edit again

    aligned --> working: edit / render / rename
    aligned --> absent: delete file
```

### Freeze Protection

Freeze protects one aligned entry from drift.
It does not create a Frost snapshot.
A failed commit from the drifted state leaves the entry drifted.

```mermaid
stateDiagram-v2
    aligned --> frozen: freeze
    frozen --> aligned: melt
    frozen --> drifted: changed despite protection

    drifted --> working: melt
    drifted --> frozen: restore to current Frost
```

### Checkout And History

Checkout materializes Frost snapshots back into the public lake.
Latest checkout returns to the aligned state.
Explicit version checkout creates a historical public file.

```mermaid
stateDiagram-v2
    absent --> aligned: checkout latest with live entry
    absent --> historical: checkout version with live entry
    aligned --> historical: checkout version
    frozen --> historical: checkout version

    historical --> aligned: checkout latest
    historical --> working: unsafe mutable checkout / edit
    historical --> absent: checkout version where entry is absent
```

### Non-Transition Commands

Observer and frame commands do not move one entry file.
They report state,
update review bookkeeping,
or move configured storage paths.
Because they do not transition one entry between lifecycle states,
they are not drawn as lifecycle transitions.

## State Definitions

`absent` means no managed Markdown file exists for the *entry* id in the waterline.
`sirno new`, `sirno init`, `sirno lake init`, manual file creation,
or checkout of a live Frost entry can create the file.
If an entry is absent from the waterline but live in the frostline,
`sirno commit` records a lifecycle deletion marker.

`working` means the waterline file exists and may differ from the frostline.
It is the normal editing state.
Direct Markdown edits, generated-link rendering,
metadata updates, and renames keep the file in working state.
A rename changes the *entry* id.
For Frost, the old id and new id are different entries.

`reviewed` means the working file set passed the review checks required for commit.
It is a gate, not a stored state.
A later edit, stale generated footer,
bad structural reference,
bad witness reference,
parse error, or unsupported lake file can remove this gate.

`aligned` means the committed form of the waterline *entry* matches the frostline.
Generated-link regions are public lake projections
and are removed before comparison with Frost.
An aligned entry can still be writable.
Editing it moves it back to working state until the next successful Frost commit.

`frozen` means the waterline file carries `frozen:`
and its committed form matches the frostline.
`sirno freeze ENTRY_ID` enters this state.
The command verifies current Frost first,
then adds the marker and applies local file protection.
`sirno melt ENTRY_ID` removes the marker,
clears local file protection,
and returns the entry to the aligned state if the content still matches Frost.

`drifted` means a frozen waterline entry no longer matches the frostline.
This is an error state.
It can happen if a read-only file is changed outside Sirno,
if a frozen entry is renamed,
or if metadata or prose is changed after bypassing file permissions.
`sirno commit` refuses this state.
The supported exits are to restore the entry to current Frost
or to melt it before intentionally changing it.

`historical` means the public file was materialized from an explicit Frost version.
A normal version checkout is immutable:
Sirno writes a read-only blockquote
and removes write permission from managed entry files.
`sirno checkout --latest` returns to the mutable current lake.
`sirno checkout VERSION --unsafe-mutable` deliberately turns a historical version
into a writable working baseline.

## Projections And Frame Commands

`sirno render` changes only Sirno-owned generated footer regions.
Those regions help readers navigate,
but they are removed before Frost commits.
Authored prose and metadata are the committed entry content.

`sirno query`, `sirno rg`, `sirno witness`, `sirno check`, and `sirno status`
do not move an entry between lifecycle states.
They read the public lake,
report structure,
or inspect configured repository evidence.

Storage commands affect the frame around entries.
`sirno init` creates the public lake and private Frost path together.
`sirno lake move PATH` moves the public lake path.
`sirno frost init` and `sirno frost move PATH` configure or move the private Frost path.
`sirno move lake PATH` and `sirno move frost PATH` select the same storage moves.
They do not change one entry file's lifecycle state by themselves.
`sirno move entry OLD_ID NEW_ID` follows the same lifecycle behavior as `sirno entry move`.
