Updated transcript artifact names and canonical paths to use a consistent, role-based nomenclature
This commit is contained in:
@@ -361,8 +361,8 @@ Examples:
|
||||
|
||||
```bash
|
||||
narratio locks --session-id 2026-04-04
|
||||
narratio locks add --session-id 2026-04-04 --reason "manual transcript review" narratio.transcript.trimmed
|
||||
narratio locks remove --session-id 2026-04-04 narratio.transcript.trimmed
|
||||
narratio locks add --session-id 2026-04-04 --reason "manual transcript review" narratio.transcript.final_trimmed
|
||||
narratio locks remove --session-id 2026-04-04 narratio.transcript.final_trimmed
|
||||
```
|
||||
|
||||
### `run-stage`
|
||||
|
||||
@@ -185,8 +185,8 @@ archive:
|
||||
enabled: true
|
||||
upload_run: true
|
||||
promote_artifacts:
|
||||
- source: narratio.transcript.trimmed
|
||||
dest: transcripts/trimmed.json
|
||||
- source: narratio.transcript.final_trimmed
|
||||
dest: transcripts/final.trimmed.json
|
||||
required: true
|
||||
- source: narratio.artifact.session_recap
|
||||
dest: artifacts/session_recap.md
|
||||
@@ -206,7 +206,7 @@ scriptorium:
|
||||
output_path: artifacts/session_recap.md
|
||||
inputs:
|
||||
transcript:
|
||||
source: narratio.transcript.trimmed
|
||||
source: narratio.transcript.final_trimmed
|
||||
required: true
|
||||
previous_recap:
|
||||
source: narratio.previous_session.artifact.session_recap
|
||||
@@ -280,7 +280,7 @@ Operational notes:
|
||||
| `pipeline.cache.s3_audio` | bool | No | `true` |
|
||||
| `pipeline.archive.enabled` | bool | No | `true` |
|
||||
| `pipeline.archive.upload_run` | bool | No | `true` |
|
||||
| `pipeline.archive.promote_artifacts[]` | list | No | trimmed transcript rule |
|
||||
| `pipeline.archive.promote_artifacts[]` | list | No | final-trimmed transcript rule |
|
||||
| `pipeline.archive.promote_artifacts[].source` | string | Yes (per rule) | none |
|
||||
| `pipeline.archive.promote_artifacts[].dest` | string | No | derived from source |
|
||||
| `pipeline.archive.promote_artifacts[].required` | bool | No | `true` |
|
||||
@@ -317,7 +317,7 @@ Operational notes:
|
||||
| `pipeline.audita.output_schema` | string | No | empty |
|
||||
| `pipeline.audita.work_dir_retention` | string | No | empty |
|
||||
| `pipeline.audita.report` | bool | No | `true` |
|
||||
| `pipeline.normalize.output_path` | string | No | `transcripts/normalized.json` |
|
||||
| `pipeline.normalize.output_path` | string | No | `transcripts/final.json` |
|
||||
| `pipeline.normalize.output_schema` | string | No | `seriatim-intermediate` |
|
||||
| `pipeline.normalize.report` | bool | No | `true` |
|
||||
| `pipeline.trim.enabled` | bool | No | `false` |
|
||||
@@ -366,19 +366,19 @@ Scriptorium artifact-key and dependency rules:
|
||||
Allowed `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source` values:
|
||||
|
||||
- `narratio.previous_session.artifact.<configured_artifact_key>`
|
||||
- `narratio.transcript.merged`
|
||||
- `narratio.transcript.base`
|
||||
- `narratio.transcript.polished`
|
||||
- `narratio.transcript.full`
|
||||
- `narratio.transcript.trimmed`
|
||||
- `narratio.transcript.final`
|
||||
- `narratio.transcript.final_trimmed`
|
||||
- `narratio.bounds.session`
|
||||
- `narratio.artifact.<configured_artifact_key>`
|
||||
|
||||
`pipeline.archive.promote_artifacts[].source` values:
|
||||
|
||||
- `narratio.transcript.merged`
|
||||
- `narratio.transcript.base`
|
||||
- `narratio.transcript.polished`
|
||||
- `narratio.transcript.full`
|
||||
- `narratio.transcript.trimmed`
|
||||
- `narratio.transcript.final`
|
||||
- `narratio.transcript.final_trimmed`
|
||||
- `narratio.bounds.session`
|
||||
- `narratio.artifact.<configured_artifact_key>`
|
||||
|
||||
|
||||
@@ -5,9 +5,9 @@ Define Narratio's adapter contract for transcript polishing via Audita CLI subpr
|
||||
|
||||
## Inputs and Outputs
|
||||
Inputs (`audita.PolishRequest`):
|
||||
- merged transcript path
|
||||
- base transcript path
|
||||
- glossary path
|
||||
- output processed transcript path
|
||||
- output polished transcript path
|
||||
- optional report path (required when report enabled)
|
||||
- work dir
|
||||
- generated config path
|
||||
@@ -15,7 +15,7 @@ Inputs (`audita.PolishRequest`):
|
||||
- optional module/model/base URL and concurrency knobs
|
||||
|
||||
Outputs (`audita.PolishResult`):
|
||||
- processed transcript path
|
||||
- polished transcript path
|
||||
- optional report path
|
||||
- generated config path
|
||||
- stdout/stderr log paths
|
||||
@@ -27,7 +27,7 @@ Owns:
|
||||
- Deterministic CLI argument construction for `audita process`
|
||||
- Environment bridging for API credentials
|
||||
- Invocation config emission
|
||||
- Output validation for processed transcript and report
|
||||
- Output validation for polished transcript and report
|
||||
|
||||
Does not own:
|
||||
- Upstream/downstream stage orchestration
|
||||
@@ -52,7 +52,7 @@ Via `pipeline.audita.*` mapped in app/stage wiring:
|
||||
|
||||
## Failure Behavior
|
||||
- Constructor validation fails on invalid binary/timeout/schema/concurrency/URL values.
|
||||
- Run fails on missing required paths, missing required credential env var, subprocess errors, invalid processed JSON shape, or invalid report JSON.
|
||||
- Run fails on missing required paths, missing required credential env var, subprocess errors, invalid polished JSON shape, or invalid report JSON.
|
||||
- Failures preserve stdout/stderr paths in returned result metadata.
|
||||
|
||||
## Tests to Inspect Before Changing
|
||||
@@ -61,6 +61,6 @@ Via `pipeline.audita.*` mapped in app/stage wiring:
|
||||
- `internal/stage/polish_test.go`
|
||||
|
||||
## Architectural Invariants
|
||||
- Processed output must be valid JSON with top-level `segments` array.
|
||||
- Polished output must be valid JSON with top-level `segments` array.
|
||||
- When report is enabled, report output must be valid JSON.
|
||||
- If `llm_api_key_env` is configured, credential must be present in environment.
|
||||
|
||||
@@ -5,7 +5,7 @@ Define Narratio's adapter contract for merge, normalize, and trim subprocess inv
|
||||
|
||||
## Inputs and Outputs
|
||||
Inputs:
|
||||
- `MergeRequest`: raw/normalized transcript inputs, output path, optional report, speaker/autocorrect paths, logs/config
|
||||
- `MergeRequest`: raw/per-speaker normalized transcript inputs, base output path, optional report, speaker/autocorrect paths, logs/config
|
||||
- `NormalizeRequest`: input transcript, output path, schema, optional report, timeout/log/config
|
||||
- `TrimRequest`: input transcript, output path, keep selector, timeout/log/config
|
||||
|
||||
@@ -44,8 +44,8 @@ Via `pipeline.seriatim.*` mapped in app/stage wiring:
|
||||
## Failure Behavior
|
||||
- Constructor fails for invalid binary/timeout/output-schema/coalesce-gap.
|
||||
- Merge fails on missing output path/inputs/report path (if enabled), subprocess errors, invalid merged output JSON, invalid report JSON.
|
||||
- Normalize fails on missing input/output, invalid schema, subprocess errors, invalid normalized output JSON shape, invalid report JSON.
|
||||
- Trim fails on missing input/output/keep selector, subprocess errors, invalid trimmed output JSON shape.
|
||||
- Normalize fails on missing input/output, invalid schema, subprocess errors, invalid final output JSON shape, invalid report JSON.
|
||||
- Trim fails on missing input/output/keep selector, subprocess errors, invalid final-trimmed output JSON shape.
|
||||
|
||||
## Tests to Inspect Before Changing
|
||||
- `internal/adapters/seriatim/subprocess_test.go`
|
||||
@@ -56,5 +56,5 @@ Via `pipeline.seriatim.*` mapped in app/stage wiring:
|
||||
|
||||
## Architectural Invariants
|
||||
- Supported output schemas are limited to `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`.
|
||||
- Normalize/trim outputs must include `segments` arrays.
|
||||
- Final and final-trimmed outputs must include `segments` arrays.
|
||||
- Merge/normalize/trim all route through deterministic subprocess invocation.
|
||||
|
||||
@@ -33,10 +33,10 @@ Does not own:
|
||||
## Built-in IDs
|
||||
| Artifact ID | Canonical file | Producer stage | Output kind |
|
||||
| --- | --- | --- | --- |
|
||||
| `narratio.transcript.merged` | `transcripts/merged.json` | `merge` | `transcript_merged` |
|
||||
| `narratio.transcript.polished` | `transcripts/processed.json` | `polish` | `transcript_processed` |
|
||||
| `narratio.transcript.full` | `transcripts/normalized.json` | `normalize` | `transcript_normalized` |
|
||||
| `narratio.transcript.trimmed` | `transcripts/trimmed.json` | `trim` | `transcript_trimmed` |
|
||||
| `narratio.transcript.base` | `transcripts/base.json` | `merge` | `transcript_base` |
|
||||
| `narratio.transcript.polished` | `transcripts/polished.json` | `polish` | `transcript_polished` |
|
||||
| `narratio.transcript.final` | `transcripts/final.json` | `normalize` | `transcript_final` |
|
||||
| `narratio.transcript.final_trimmed` | `transcripts/final.trimmed.json` | `trim` | `transcript_final_trimmed` |
|
||||
| `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
|
||||
|
||||
## Source families
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Stage: merge
|
||||
|
||||
## Purpose
|
||||
Normalize per-speaker raw transcripts and merge them into one merged transcript via Seriatim.
|
||||
Normalize per-speaker raw transcripts and merge them into the base transcript via Seriatim.
|
||||
|
||||
## Inputs and Outputs
|
||||
Inputs:
|
||||
@@ -10,7 +10,7 @@ Inputs:
|
||||
- `inputs/autocorrect.yml`
|
||||
|
||||
Outputs:
|
||||
- `transcripts/merged.json`
|
||||
- `transcripts/base.json`
|
||||
- optional `artifacts/seriatim.report.json` (when report enabled)
|
||||
|
||||
## Boundaries
|
||||
@@ -19,7 +19,7 @@ Owns:
|
||||
- Per-input normalize calls to Seriatim
|
||||
- Final merge call to Seriatim
|
||||
- Run-local log/config/report path wiring
|
||||
- Promotion of merged/report outputs to canonical paths
|
||||
- Promotion of base/report outputs to canonical paths
|
||||
|
||||
Does not own:
|
||||
- Transcript polishing or downstream artifact generation
|
||||
@@ -43,7 +43,7 @@ Does not own:
|
||||
## State and Manifest Behavior
|
||||
- Reads transcript inputs from transcribe stage outputs in manifest when present; falls back to canonical raw directory.
|
||||
- Writes run-local outputs/logs/config under `runs/{run_id}/merge/...` when enabled.
|
||||
- Promotes canonical merged transcript and optional report.
|
||||
- Promotes canonical base transcript and optional report.
|
||||
- Records normalized-input provenance and adapter metadata in stage metadata.
|
||||
|
||||
## Skip and Resume Behavior
|
||||
@@ -51,7 +51,7 @@ Does not own:
|
||||
- Forced rerun of this or upstream stages can stale downstream succeeded stages via runner invalidation.
|
||||
|
||||
## Failure Behavior
|
||||
- Fails on missing/invalid raw transcripts, missing speakers/autocorrect files, normalize failure, merge failure, invalid merged output JSON, or invalid report JSON when enabled.
|
||||
- Fails on missing/invalid raw transcripts, missing speakers/autocorrect files, normalize failure, merge failure, invalid base output JSON, or invalid report JSON when enabled.
|
||||
|
||||
## Tests to Inspect Before Changing
|
||||
- `internal/stage/merge_test.go`
|
||||
@@ -59,5 +59,5 @@ Does not own:
|
||||
|
||||
## Architectural Invariants
|
||||
- Merge consumes normalized forms of each raw transcript.
|
||||
- Merged transcript must validate before promotion.
|
||||
- Base transcript must validate before promotion.
|
||||
- Report output is optional and gated by config.
|
||||
|
||||
@@ -1,22 +1,22 @@
|
||||
# Stage: normalize
|
||||
|
||||
## Purpose
|
||||
Normalize the processed transcript into a deterministic intermediate schema for trim and optionally emit a normalize report.
|
||||
Normalize the polished transcript into the full final transcript and optionally emit a normalize report.
|
||||
|
||||
## Inputs and Outputs
|
||||
Inputs:
|
||||
- `transcripts/processed.json`
|
||||
- `transcripts/polished.json`
|
||||
|
||||
Outputs:
|
||||
- `transcripts/normalized.json` (or configured normalize output path)
|
||||
- `transcripts/final.json` (or configured normalize output path)
|
||||
- optional `artifacts/seriatim.normalize.report.json`
|
||||
|
||||
## Boundaries
|
||||
Owns:
|
||||
- Processed transcript discovery/validation
|
||||
- Polished transcript discovery/validation
|
||||
- Normalize request construction and invocation
|
||||
- Optional normalize report wiring
|
||||
- Promotion of normalized transcript and optional report
|
||||
- Promotion of final transcript and optional report
|
||||
|
||||
Does not own:
|
||||
- Bounds detection or segment trimming
|
||||
@@ -35,9 +35,9 @@ Does not own:
|
||||
- Seriatim adapter (`Normalize`).
|
||||
|
||||
## State and Manifest Behavior
|
||||
- Reads processed transcript from polish outputs in manifest when present; falls back to canonical path.
|
||||
- Reads polished transcript from polish outputs in manifest when present; falls back to canonical path.
|
||||
- Uses run-local output/report/log/config paths when run layout is enabled.
|
||||
- Promotes canonical normalized transcript and optional normalize report.
|
||||
- Promotes canonical final transcript and optional normalize report.
|
||||
- Records adapter/result metadata including source path selection.
|
||||
|
||||
## Skip and Resume Behavior
|
||||
@@ -45,12 +45,12 @@ Does not own:
|
||||
- Forced reruns can stale downstream succeeded stages.
|
||||
|
||||
## Failure Behavior
|
||||
- Fails on missing/invalid processed transcript, adapter error, invalid normalized output, or invalid report output when report enabled.
|
||||
- Fails on missing/invalid polished transcript, adapter error, invalid final output, or invalid report output when report enabled.
|
||||
|
||||
## Tests to Inspect Before Changing
|
||||
- `internal/stage/normalize_test.go`
|
||||
- `internal/adapters/seriatim/subprocess_test.go`
|
||||
|
||||
## Architectural Invariants
|
||||
- Normalized output must validate as processed-transcript-compatible JSON (`segments` array required).
|
||||
- Final output must validate as transcript-compatible JSON (`segments` array required).
|
||||
- Default normalize config is applied when `pipeline.normalize` is unset.
|
||||
|
||||
@@ -1,23 +1,23 @@
|
||||
# Stage: polish
|
||||
|
||||
## Purpose
|
||||
Polish merged transcript with Audita and produce a processed transcript for downstream normalization/analyze.
|
||||
Polish the base transcript with Audita and produce a polished transcript for downstream normalization/analyze.
|
||||
|
||||
## Inputs and Outputs
|
||||
Inputs:
|
||||
- `transcripts/merged.json`
|
||||
- `transcripts/base.json`
|
||||
- `inputs/glossary.yml`
|
||||
|
||||
Outputs:
|
||||
- `transcripts/processed.json`
|
||||
- `transcripts/polished.json`
|
||||
- optional `artifacts/audita.report.json` (when report enabled)
|
||||
|
||||
## Boundaries
|
||||
Owns:
|
||||
- Merged transcript discovery/validation
|
||||
- Base transcript discovery/validation
|
||||
- Audita invocation request construction
|
||||
- Run-local logs/config/work-dir/report wiring
|
||||
- Promotion of processed transcript and optional report
|
||||
- Promotion of polished transcript and optional report
|
||||
|
||||
Does not own:
|
||||
- Upstream merge normalization
|
||||
@@ -47,9 +47,9 @@ Does not own:
|
||||
- Audita adapter (`env.Audita.Run`).
|
||||
|
||||
## State and Manifest Behavior
|
||||
- Reads merged transcript from merge manifest outputs when available; falls back to canonical merged path.
|
||||
- Reads base transcript from merge manifest outputs when available; falls back to canonical base path.
|
||||
- Uses run-local output/report/log/config/scratch paths when run layout is enabled.
|
||||
- Promotes canonical `transcripts/processed.json` and optional report.
|
||||
- Promotes canonical `transcripts/polished.json` and optional report.
|
||||
- Records adapter invocation metadata, credential presence signal, and output provenance in stage metadata.
|
||||
|
||||
## Skip and Resume Behavior
|
||||
@@ -57,13 +57,13 @@ Does not own:
|
||||
- Forced rerun can stale downstream succeeded stages via runner invalidation.
|
||||
|
||||
## Failure Behavior
|
||||
- Fails on missing/invalid merged transcript, missing glossary, adapter error, invalid processed output shape (`segments` array required), or invalid report JSON when enabled.
|
||||
- Fails on missing/invalid base transcript, missing glossary, adapter error, invalid polished output shape (`segments` array required), or invalid report JSON when enabled.
|
||||
|
||||
## Tests to Inspect Before Changing
|
||||
- `internal/stage/polish_test.go`
|
||||
- `internal/adapters/audita/subprocess_test.go`
|
||||
|
||||
## Architectural Invariants
|
||||
- Processed transcript must contain a top-level `segments` array.
|
||||
- Polished transcript must contain a top-level `segments` array.
|
||||
- Report behavior is strictly config-gated.
|
||||
- Stage output canonicalization always ends at `transcripts/processed.json`.
|
||||
- Stage output canonicalization always ends at `transcripts/polished.json`.
|
||||
|
||||
@@ -1,21 +1,21 @@
|
||||
# Stage: trim
|
||||
|
||||
## Purpose
|
||||
Optionally trim the normalized transcript to session bounds; always produce a durable trimmed transcript.
|
||||
Optionally trim the final transcript to session bounds; always produce a durable final-trimmed transcript.
|
||||
|
||||
## Inputs and Outputs
|
||||
Inputs:
|
||||
- `transcripts/normalized.json`
|
||||
- `transcripts/final.json`
|
||||
|
||||
Outputs:
|
||||
- `transcripts/trimmed.json` (or configured trim output path)
|
||||
- `transcripts/final.trimmed.json` (or configured trim output path)
|
||||
- when trim enabled: `artifacts/session_bounds.json`
|
||||
|
||||
## Boundaries
|
||||
Owns:
|
||||
- Trim-enabled switch behavior
|
||||
- Bounds generation via Scriptorium artifact run
|
||||
- Bounds validation against normalized transcript
|
||||
- Bounds validation against final transcript
|
||||
- Keep-selector derivation and Seriatim trim invocation
|
||||
- Copy-through behavior when disabled or bounds indicate unchanged transcript
|
||||
|
||||
@@ -50,19 +50,19 @@ Does not own:
|
||||
- `Trim` when bounds indicate trimming is required
|
||||
|
||||
## State and Manifest Behavior
|
||||
- Reads normalized transcript from normalize manifest outputs when available; falls back to canonical path.
|
||||
- Reads final transcript from normalize manifest outputs when available; falls back to canonical path.
|
||||
- Uses run-local outputs/logs/reports/config/scratch paths when run layout is enabled.
|
||||
- Promotes canonical trimmed transcript; promotes session bounds when trim enabled.
|
||||
- Promotes canonical final-trimmed transcript; promotes session bounds when trim enabled.
|
||||
- Records bounds diagnostics, trim action, keep selector, and adapter metadata.
|
||||
|
||||
## Skip and Resume Behavior
|
||||
- Runner-level skip applies when already succeeded and not forced.
|
||||
- Forced reruns can stale downstream succeeded stages.
|
||||
- When `trim.enabled=false`, stage still succeeds by copying normalized to trimmed output.
|
||||
- When `trim.enabled=false`, stage still succeeds by copying final to final-trimmed output.
|
||||
|
||||
## Failure Behavior
|
||||
- Fails on missing/invalid normalized transcript.
|
||||
- With trim enabled, fails on missing adapters/config, bounds generation/validation errors, invalid bounds JSON, invalid range/segment ids, trim adapter failures, or invalid trimmed output.
|
||||
- Fails on missing/invalid final transcript.
|
||||
- With trim enabled, fails on missing adapters/config, bounds generation/validation errors, invalid bounds JSON, invalid range/segment ids, trim adapter failures, or invalid final-trimmed output.
|
||||
|
||||
## Tests to Inspect Before Changing
|
||||
- `internal/stage/trim_test.go`
|
||||
@@ -70,6 +70,6 @@ Does not own:
|
||||
- `internal/adapters/seriatim/subprocess_test.go`
|
||||
|
||||
## Architectural Invariants
|
||||
- Trim never falls back to processed transcript; normalized transcript is required input.
|
||||
- Trim never falls back to polished transcript; final transcript is required input.
|
||||
- `session_bounds` output exists only for enabled trim path.
|
||||
- Render-debug artifacts are diagnostics and not declared stage outputs.
|
||||
|
||||
210
docs/roadmap/transcripts.md
Normal file
210
docs/roadmap/transcripts.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Roadmap: Transcript Artifact Naming
|
||||
|
||||
Status: Implemented
|
||||
|
||||
## Problem
|
||||
|
||||
Narratio's built-in transcript artifact names and canonical paths currently mix
|
||||
operator-facing artifact meaning with historical stage and tool terminology:
|
||||
|
||||
- `narratio.transcript.merged` maps to `transcripts/merged.json`.
|
||||
- `narratio.transcript.polished` maps to `transcripts/processed.json`.
|
||||
- `narratio.transcript.full` maps to `transcripts/normalized.json`.
|
||||
- `narratio.transcript.trimmed` maps to `transcripts/trimmed.json`.
|
||||
|
||||
This makes the public artifact surface harder to reason about. Operators see
|
||||
`full`, `normalized`, `processed`, `polished`, `merged`, and `trimmed` used in
|
||||
different places for the same transcript lineage.
|
||||
|
||||
The transcript source IDs, canonical paths, and manifest output kinds should
|
||||
use one vocabulary based on each transcript's role in the session artifact
|
||||
model.
|
||||
|
||||
## Target Model
|
||||
|
||||
Built-in transcript artifacts should use these public source IDs, canonical
|
||||
paths, and manifest output kinds:
|
||||
|
||||
| Source ID | Canonical path | Output kind | Meaning |
|
||||
| --- | --- | --- | --- |
|
||||
| `narratio.transcript.base` | `transcripts/base.json` | `transcript_base` | First unified transcript produced by merging per-speaker raw transcripts. |
|
||||
| `narratio.transcript.polished` | `transcripts/polished.json` | `transcript_polished` | Audita-polished transcript. |
|
||||
| `narratio.transcript.final` | `transcripts/final.json` | `transcript_final` | Full final transcript after normalization. |
|
||||
| `narratio.transcript.final_trimmed` | `transcripts/final.trimmed.json` | `transcript_final_trimmed` | Trimmed version of the final transcript. |
|
||||
|
||||
Stage names remain process-oriented and unchanged:
|
||||
|
||||
- `merge`
|
||||
- `polish`
|
||||
- `normalize`
|
||||
- `trim`
|
||||
|
||||
Downstream adapter contracts also remain process-oriented. The rename changes
|
||||
Narratio's artifact model, canonical paths, config examples, archive promotion
|
||||
sources, lock sources, status output, and documentation. It should not rename
|
||||
the stages themselves or move external integration details into stage logic.
|
||||
|
||||
## Compatibility Policy
|
||||
|
||||
This is a hard cutover.
|
||||
|
||||
After implementation, these old source IDs should be rejected:
|
||||
|
||||
- `narratio.transcript.merged`
|
||||
- `narratio.transcript.full`
|
||||
- `narratio.transcript.trimmed`
|
||||
|
||||
These old canonical paths should not be compatibility fallbacks:
|
||||
|
||||
- `transcripts/merged.json`
|
||||
- `transcripts/processed.json`
|
||||
- `transcripts/normalized.json`
|
||||
- `transcripts/trimmed.json`
|
||||
|
||||
Existing remote archives are not migrated automatically. Operators who want
|
||||
new promoted keys for old sessions should republish those sessions after
|
||||
updating configuration.
|
||||
|
||||
## Implementation Stages
|
||||
|
||||
### Stage 1: Centralize Transcript Artifact Naming
|
||||
|
||||
Status: Implemented
|
||||
|
||||
Consolidate transcript artifact source IDs, canonical paths, and output kinds
|
||||
in the artifact/path layer before changing runtime behavior.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- Add or consolidate constants/helpers for built-in transcript source IDs.
|
||||
- Add or consolidate constants/helpers for canonical transcript paths.
|
||||
- Add or consolidate constants/helpers for transcript manifest output kinds.
|
||||
- Keep source ID, path, and output-kind mappings in one registry or one
|
||||
obviously shared artifact model.
|
||||
- Update artifact registry tests to prove the target mapping.
|
||||
- Avoid changing stage output behavior in this stage unless the implementation
|
||||
is simpler and still reviewable.
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- There is one clear source of truth for built-in transcript artifact names,
|
||||
paths, and output kinds.
|
||||
- Tests prove the new target mapping in the artifact layer.
|
||||
- No generic workflow abstraction is introduced.
|
||||
|
||||
### Stage 2: Rename Runtime Outputs and Defaults
|
||||
|
||||
Status: Implemented
|
||||
|
||||
Switch runtime behavior to the new transcript artifact model.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- Update `merge` to write and record `transcripts/base.json` with
|
||||
`transcript_base`.
|
||||
- Update `polish` to write and record `transcripts/polished.json` with
|
||||
`transcript_polished`.
|
||||
- Update `normalize` to write and record `transcripts/final.json` with
|
||||
`transcript_final`.
|
||||
- Update `trim` to write and record `transcripts/final.trimmed.json` with
|
||||
`transcript_final_trimmed`.
|
||||
- Update normalize and trim defaults to:
|
||||
- `pipeline.normalize.output_path: transcripts/final.json`
|
||||
- `pipeline.trim.output_path: transcripts/final.trimmed.json`
|
||||
- Update built-in artifact resolution, archive promotion destination
|
||||
derivation, archive locks, status output, artifact catalog output,
|
||||
previous-cache resolution, restore planning, and restore execution to use
|
||||
the new registry values.
|
||||
- Ensure old source IDs fail config validation.
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- New runs produce the target canonical transcript files.
|
||||
- Manifest outputs use the target output kinds.
|
||||
- Archive promotion and lock validation accept new source IDs and reject old
|
||||
source IDs.
|
||||
- Status and artifact listing display new source IDs.
|
||||
- Restore uses the new canonical paths and does not restore old transcript
|
||||
paths as canonical outputs.
|
||||
|
||||
### Stage 3: Update Tests, Examples, and Current Documentation
|
||||
|
||||
Status: Implemented
|
||||
|
||||
Update all implemented-behavior references after the runtime cutover lands.
|
||||
|
||||
Implementation requirements:
|
||||
|
||||
- Update examples to use `narratio.transcript.final_trimmed` and
|
||||
`transcripts/final.trimmed.json` where trimmed final transcript is intended.
|
||||
- Update examples that refer to full final transcripts to use
|
||||
`narratio.transcript.final` and `transcripts/final.json`.
|
||||
- Update `docs/config.md`, `docs/internal/artifacts.md`, stage docs,
|
||||
CLI examples, operations examples, archive examples, lock examples, and
|
||||
status/artifact-list examples.
|
||||
- Add strict validation tests proving old source IDs are rejected.
|
||||
- Mark roadmap stages implemented only after code, tests, examples, and
|
||||
current-behavior docs agree.
|
||||
|
||||
Acceptance criteria:
|
||||
|
||||
- Maintained examples load and validate.
|
||||
- Current-behavior docs describe only implemented new names.
|
||||
- Old names remain only in this roadmap as historical/planning context until
|
||||
this roadmap is retired or archived.
|
||||
|
||||
## Test Guidance
|
||||
|
||||
Run focused tests while implementing:
|
||||
|
||||
- `go test ./internal/artifacts -v`
|
||||
- `go test ./internal/config -v`
|
||||
- `go test ./internal/stage -v`
|
||||
- `go test ./internal/app -v`
|
||||
|
||||
Run full validation before finishing:
|
||||
|
||||
- `go test ./...`
|
||||
|
||||
Run final searches:
|
||||
|
||||
- Old source IDs:
|
||||
- `narratio.transcript.merged`
|
||||
- `narratio.transcript.full`
|
||||
- `narratio.transcript.trimmed`
|
||||
- Old paths:
|
||||
- `transcripts/merged.json`
|
||||
- `transcripts/processed.json`
|
||||
- `transcripts/normalized.json`
|
||||
- `transcripts/trimmed.json`
|
||||
- Old output kinds:
|
||||
- `transcript_merged`
|
||||
- `transcript_processed`
|
||||
- `transcript_normalized`
|
||||
- `transcript_trimmed`
|
||||
|
||||
Expected remaining matches should be limited to this roadmap's
|
||||
historical/planning references until the roadmap is fully completed.
|
||||
|
||||
## Architecture Guardrails
|
||||
|
||||
- Keep Narratio explicit and stage-driven; do not introduce a generic workflow
|
||||
or DAG abstraction.
|
||||
- Keep path and artifact naming in centralized helpers rather than scattered
|
||||
string concatenation.
|
||||
- Preserve manifest-driven resume behavior.
|
||||
- Keep storage details behind storage adapters.
|
||||
- Do not move Seriatim, Audita, or Scriptorium command details out of their
|
||||
adapter boundaries.
|
||||
- Keep current-behavior documentation in sync only after implementation lands;
|
||||
planned behavior belongs in this roadmap until then.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The cutover is intentionally not backward-compatible.
|
||||
- Existing remote archive objects are not renamed or migrated automatically.
|
||||
- Stage names and downstream adapter request field names remain unchanged.
|
||||
- The term `base` is preferred over `merged` for the first unified transcript.
|
||||
- The term `final` is preferred over `full` or `normalized` for the full final
|
||||
transcript.
|
||||
- The trimmed final path is `transcripts/final.trimmed.json`.
|
||||
Reference in New Issue
Block a user