171 lines
4.1 KiB
Markdown
171 lines
4.1 KiB
Markdown
# Operations
|
|
|
|
This guide covers the implemented operator lifecycle for Narratio.
|
|
|
|
For field-level settings, see [docs/config.md](./config.md). For syntax/flags, see [docs/cli.md](./cli.md).
|
|
|
|
## Normal Workflow
|
|
|
|
1. Ensure `pipeline.yml`, `campaign.yml`, and `session.yml` are available.
|
|
2. Ensure session audio is available (local `audio_dir`/`audio_files` or S3 prefix).
|
|
3. Run:
|
|
|
|
```bash
|
|
narratio run 2026-04-04
|
|
```
|
|
|
|
4. Inspect status:
|
|
|
|
```bash
|
|
narratio session status 2026-04-04
|
|
```
|
|
|
|
## Publish Workflow
|
|
|
|
Publish is the stage that commits remote current state.
|
|
|
|
```bash
|
|
narratio publish 2026-04-04
|
|
```
|
|
|
|
Equivalent command:
|
|
|
|
```bash
|
|
narratio run-stage publish 2026-04-04 --force
|
|
```
|
|
|
|
Publish uploads:
|
|
|
|
- run history files under `{session_prefix}/runs/{run_id}/` (excluding `audio/`)
|
|
- configured published outputs from `pipeline.publish.outputs`
|
|
- `previous/**` cache files when present
|
|
- `current/manifest.json`
|
|
- `current/run_id.txt` last
|
|
|
|
`current/run_id.txt` is the remote commit marker.
|
|
|
|
## Published Outputs and Locks
|
|
|
|
Published output behavior:
|
|
|
|
- outputs are source-based rules in `pipeline.publish.outputs`.
|
|
- required missing unlocked sources fail publish.
|
|
- optional missing unlocked sources are skipped.
|
|
- selected artifacts (`--artifacts`) only filter configured `narratio.artifact.<key>` output rules.
|
|
- built-in transcript and bounds output rules are not filtered by `--artifacts`.
|
|
|
|
Lock behavior:
|
|
|
|
- static locks: `pipeline.publish.locks`.
|
|
- mutable locks: `{session_prefix}/locks.yml`.
|
|
- effective lock set is static + mutable; static wins on duplicate sources.
|
|
- locked outputs are intentional skips and do not fail publish.
|
|
- lock commands mutate only remote mutable locks.
|
|
|
|
## Restore Workflow
|
|
|
|
Use restore when local durable session state is missing/stale and committed remote current state is authoritative.
|
|
|
|
Preview:
|
|
|
|
```bash
|
|
narratio session restore 2026-04-04 --dry-run
|
|
```
|
|
|
|
Apply:
|
|
|
|
```bash
|
|
narratio session restore 2026-04-04
|
|
```
|
|
|
|
Default restore scope:
|
|
|
|
- `manifest.json`
|
|
- `transcripts/**`
|
|
- `artifacts/**`
|
|
- `previous/**` when required by configured previous-session artifact inputs
|
|
|
|
Optional:
|
|
|
|
- add `--include-audio` to restore `audio/**`.
|
|
|
|
Restore reads committed current state only (`current/run_id.txt`, `current/manifest.json`).
|
|
|
|
## Workspace and State Layout
|
|
|
|
Session root:
|
|
|
|
- `{workspace.root}/work/{campaign}/{session_id}/`
|
|
|
|
Durable session state:
|
|
|
|
- `manifest.json`
|
|
- `inputs/**`
|
|
- `audio/**`
|
|
- `transcripts/**`
|
|
- `artifacts/**`
|
|
- `previous/**`
|
|
- `reports/**`
|
|
- `logs/**`
|
|
- `config/**`
|
|
- `runs/**`
|
|
|
|
Run-local stage layout:
|
|
|
|
- `runs/{run_id}/{stage}/outputs|logs|reports|config|scratch`
|
|
|
|
Stages typically write run-local outputs first, then materialize canonical session outputs on success.
|
|
|
|
## Resume and Force Rules
|
|
|
|
- `run` and `run-stage` skip succeeded stages unless `--force` is set.
|
|
- `resume` starts at the first non-succeeded stage.
|
|
- force-rerunning an upstream succeeded stage marks downstream succeeded stages as `stale`.
|
|
- `--force` does not bypass publish locks.
|
|
|
|
## Cleanup
|
|
|
|
Automatic post-publish cleanup is considered only when publish executes successfully and commits current state.
|
|
|
|
Config toggles:
|
|
|
|
- `pipeline.spool.delete_audio_after_publish=true`
|
|
- `pipeline.workspace.cleanup_after_publish=true`
|
|
|
|
Manual cleanup:
|
|
|
|
```bash
|
|
narratio clean 2026-04-04
|
|
narratio clean --all
|
|
```
|
|
|
|
Cache is preserved by default. Use `--clear-cache` to remove matching S3 audio cache entries.
|
|
|
|
## Failure and Recovery
|
|
|
|
After stage failure, Narratio keeps manifests and run-local files for inspection.
|
|
|
|
Standard recovery flow:
|
|
|
|
1. inspect status:
|
|
|
|
```bash
|
|
narratio session status 2026-04-04
|
|
```
|
|
|
|
2. if needed, inspect restore plan:
|
|
|
|
```bash
|
|
narratio session restore 2026-04-04 --dry-run
|
|
```
|
|
|
|
3. fix root cause.
|
|
4. continue with `resume`, or rerun a stage with `--force` then `resume`.
|
|
|
|
## Operational Caveats
|
|
|
|
- local and S3 audio modes are mutually exclusive.
|
|
- publish requires prerequisite stages through `analyze` to be `succeeded`.
|
|
- restore requires configured object storage and committed current state.
|
|
- `session status` and `session artifacts --remote` both report remote published-output availability when storage is configured.
|