85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# 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.
|