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.
|
||||
76
docs/adr/0002-assign-subprocess-content-ownership.md
Normal file
76
docs/adr/0002-assign-subprocess-content-ownership.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# 0002. Assign subprocess content ownership
|
||||
|
||||
## Status
|
||||
|
||||
Proposed
|
||||
|
||||
## Date
|
||||
|
||||
2026-10-03
|
||||
|
||||
## Context
|
||||
|
||||
[ADR 0001](0001-classify-session-content.md) defines content categories and
|
||||
operator-facing directory principles. Narratio also needs an ownership boundary
|
||||
for the applications it invokes. That boundary determines who selects locations,
|
||||
manages retained files, and controls cleanup.
|
||||
|
||||
The current subprocess workflows can execute with fresh working state. Notarius
|
||||
can reuse persistent chunk-plan and checkpoint caches. Narratio maintains its own
|
||||
session progress and recovery records.
|
||||
|
||||
## Decision
|
||||
|
||||
Assign responsibility by content category:
|
||||
|
||||
| Category | Responsibility |
|
||||
| --- | --- |
|
||||
| Inputs | Narratio supplies paths to prepared inputs, transcripts, and artifacts. |
|
||||
| Outputs | Narratio selects destinations and promotes completed products into the output locations defined by ADR 0001. |
|
||||
| Logs | Narratio selects stage-based destinations and captures subprocess output streams. |
|
||||
| Debug | Narratio selects the destination when capture is enabled; the subprocess defines the diagnostic contents. |
|
||||
| Subprocess State | Each application manages its working directory, temporary files, and execution lifecycle through its own configuration and defaults. |
|
||||
| Subprocess Cache | Each application manages its configured persistent cache, including its format, identity, and reuse behavior. |
|
||||
|
||||
Narratio retains ownership of its own State, including the session manifest,
|
||||
recovery bookkeeping, and staging files it manages.
|
||||
|
||||
Recommend a dedicated cache root for each cache-aware application, configurable
|
||||
through that application's supported controls. For system-wide deployments,
|
||||
`/var/cache/<application>` is a suggested location; `/var/cache/notarius` is an
|
||||
example for Notarius. Each application defines its cache configuration, defaults,
|
||||
and internal layout. Operators select locations and retention settings through
|
||||
those controls. Narratio's session cleanup leaves subprocess caches under their
|
||||
separate lifecycle policies.
|
||||
|
||||
Subprocesses retain ownership of their file formats and bundle structures.
|
||||
Narratio can receive a complete result bundle at a selected staging destination
|
||||
and promote the selected products into its canonical output directories.
|
||||
Diagnostic snapshots of subprocess State follow the Debug destination selected
|
||||
by Narratio.
|
||||
|
||||
Narratio's `runs/` directory can hold staging outputs and retained execution
|
||||
evidence. Subprocess working directories follow the application's configuration
|
||||
and may reside elsewhere. Narratio cleanup manages Narratio-owned material;
|
||||
subprocess State and Cache follow their separate lifecycle policies.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Place all subprocess working files and caches inside each Narratio session.
|
||||
This makes sessions easier to collect as a unit, but couples application
|
||||
internals and cache retention to Narratio's session lifecycle.
|
||||
- Allow subprocesses to choose output, log, and debug destinations independently.
|
||||
This simplifies invocation but scatters the material operators inspect.
|
||||
- Give Narratio control of downstream bundle formats. This simplifies some
|
||||
destination mappings but increases integration coupling. Selecting and
|
||||
promoting products preserves application ownership of those formats.
|
||||
|
||||
## Consequences
|
||||
|
||||
Adapters need supported controls for Narratio-selected output, log, and debug
|
||||
locations. Upstream changes may be needed where those destinations are coupled
|
||||
to application working directories or to one another.
|
||||
|
||||
Workspace layout and file classification can proceed independently of subprocess
|
||||
working-directory conventions. Exact debug placement, retained diagnostic views,
|
||||
and migration steps remain for the workspace design and roadmap.
|
||||
Reference in New Issue
Block a user