Plan the ConfigKit upgrade and workspace development

This commit is contained in:
2026-10-04 12:28:09 +00:00
parent 40cbf42438
commit fe9817f354
6 changed files with 1136 additions and 0 deletions

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

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