Plan the ConfigKit upgrade and workspace development
This commit is contained in:
84
docs/adr/0001-classify-session-content.md
Normal file
84
docs/adr/0001-classify-session-content.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user