# 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.