2026-05-18 22:03:59 -05:00
|
|
|
# Stage: merge
|
|
|
|
|
|
|
|
|
|
## Purpose
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
Normalize raw transcript inputs and merge into base transcript via Seriatim.
|
2026-05-18 22:03:59 -05:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
## Inputs
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-18 22:03:59 -05:00
|
|
|
- `transcripts/raw/*.json`
|
|
|
|
|
- `inputs/speakers.yml`
|
|
|
|
|
- `inputs/autocorrect.yml`
|
|
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
## Outputs
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-22 19:05:23 -05:00
|
|
|
- `transcripts/base.json`
|
2026-05-23 12:57:59 +00:00
|
|
|
- optional `artifacts/seriatim.report.json`
|
|
|
|
|
|
|
|
|
|
## Key Behavior
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-09-22 00:31:32 +00:00
|
|
|
- discovers and validates raw transcript inputs. For versioned transcribe
|
|
|
|
|
state, discovery requires aggregate transcribe success and consumes only the
|
|
|
|
|
aggregate outputs that exactly match the current per-speaker collection.
|
|
|
|
|
Partial checkpoints and orphaned files are not merge inputs. Legacy/manual
|
|
|
|
|
workflows without versioned speaker state retain directory discovery.
|
2026-05-23 12:57:59 +00:00
|
|
|
- normalizes each raw transcript (`seriatim.Normalize`) into run-local scratch output.
|
|
|
|
|
- merges normalized inputs (`seriatim.Run`) into base transcript.
|
|
|
|
|
- validates merged transcript and optional report JSON.
|
|
|
|
|
- materializes canonical outputs and records stage logs/generated configs.
|
|
|
|
|
|
|
|
|
|
## Invariants
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- merge always consumes normalized forms of raw inputs.
|
2026-09-22 00:31:32 +00:00
|
|
|
- a versioned transcribe collection is usable only through its complete,
|
|
|
|
|
successful aggregate output declaration.
|
2026-05-23 12:57:59 +00:00
|
|
|
- base transcript must validate before stage success.
|
|
|
|
|
- report output is config-gated.
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-08-30 12:54:38 +00:00
|
|
|
## Resume Evidence
|
|
|
|
|
|
|
|
|
|
Merge records a versioned semantic-configuration fingerprint for the Seriatim
|
|
|
|
|
merge operation, output schema, coalesce gap, and every configured advanced
|
|
|
|
|
merge transformation. A change reruns merge and stales only its fixed
|
|
|
|
|
descendants; prepare and transcribe remain reusable. Binary path, timeout,
|
|
|
|
|
report emission, logs, and diagnostic retention are operational exclusions.
|
|
|
|
|
|
|
|
|
|
Configuration or resources loaded privately inside Seriatim are outside
|
|
|
|
|
Narratio's observable contract and require `--force` when changed. An existing
|
|
|
|
|
successful merge record without evidence reruns once when selected.
|
|
|
|
|
|
2026-08-09 21:50:21 +00:00
|
|
|
## Related Contracts And Tests
|
|
|
|
|
|
|
|
|
|
- [Seriatim](../integrations/seriatim.md) owns subprocess and output semantics.
|
|
|
|
|
- [Configuration](../config.md#pipeline) owns operator-selected Seriatim values.
|
|
|
|
|
- Implementation and tests: `internal/stage/merge.go`,
|
2026-08-30 12:54:38 +00:00
|
|
|
`internal/stage/merge_test.go`,
|
|
|
|
|
`internal/stage/semantic_contracts_initial.go`, and
|
|
|
|
|
`internal/stage/semantic_contracts_initial_test.go`
|
