Files
narratio/docs/adr/0001-classify-session-content.md

85 lines
3.8 KiB
Markdown
Raw Normal View History

# 0001. Classify session content by purpose and lifecycle
## Status
Proposed
## Date
2026-10-01
## Context
Narratio coordinates applications that produce transcripts, artifacts,
diagnostics, and working files. The current session layout mixes some of these
roles, including complete Notarius bundles under `artifacts/`. Operators use
transcripts and artifacts to evaluate results during development and need
predictable locations for diagnostics.
A shared classification model will guide the workspace design and subsequent
adapter changes. The [operator guide](../operations.md#local-state-layout)
describes the implemented layout.
## Decision
Classify content by its primary purpose and lifecycle:
| Category | Purpose |
| --- | --- |
| Inputs | Material consumed by an application, including audio, configuration, and reference documents. |
| Outputs | Completed substantive products, including intermediate artifacts exposed for further use. |
| Logs | Records of execution, including process logs, execution reports, warnings, and diagnostic summaries. |
| Cache | Reusable information whose absence permits ordinary recomputation or retrieval. |
| State | Application condition, progress, recovery records, and unfinished work. |
Classification is relative to the consuming application. An output of one stage
can serve as an input to another while retaining its output location. Completed
outputs reused to skip work remain Outputs. Narratio's manifest is State and
records whether those outputs are reusable.
Classify checkpoints according to their recovery behavior. A checkpoint needed
to continue a particular interrupted operation is State. A saved work result
that can be reused or recomputed is Cache. Recomputation cost informs retention
policy. File-specific classification remains necessary for stores serving both
purposes.
Treat Debug as a capture and retention mode that can include detailed Logs,
snapshots of State, and other diagnostic evidence. Retained debug snapshots have
a diagnostic role; live recovery records retain their State role.
Apply these directory principles to Narratio:
- Store completed artifacts, including intermediate artifacts like
`session_bounds.json`, directly in a flat `artifacts/` directory.
- Store combined transcripts directly in `transcripts/`, with a subdirectory
for the initial per-speaker transcripts.
- Store prepared external audio in `audio/` and other prepared external inputs
in `inputs/`.
- Organize Logs under `logs/` by stage. Execution reports belong to this category.
- Organize Cache under a cache root by the application that owns its format and
reuse behavior.
- Treat scratch files and unfinished outputs as State until completion permits
promotion to Outputs.
## Alternatives Considered
- Group outputs by producer. This exposes subprocess packaging to operators;
flat artifact and transcript locations better support comparison and review.
- Group Logs by application. Stage names match the operator's workflow and
collect diagnostics from stages that invoke multiple applications.
- Classify all checkpoints as State. Recovery behavior provides a more useful
distinction for eviction and reuse decisions.
- Treat all Debug material as Logs. A separate debug location can accommodate
retained state snapshots and larger diagnostic bundles when needed.
## Consequences
Each managed file family needs an identified role, owner, scope, and retention
rule. Subprocess bundles require classification before their contents are
placed in Narratio's output and diagnostic directories.
Physical roots, retention rules, the mechanism for presenting latest logs,
debug placement, and ambiguous checkpoint classifications remain open. The file
inventory and subsequent roadmap will resolve these choices and define the
migration. Current versus historical views are separate from content categories.