narratio/docs/operations.md

# Operations

This guide describes the implemented operator lifecycle for Narratio.

For field-level configuration, see [docs/config.md](./config.md). For full command/flag reference, see [docs/cli.md](./cli.md).

## Normal workflow (S3-first path)

1. Upload session `.flac` files to the session audio prefix in object storage:
   - `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/{audio_s3.prefix}`
2. Run Narratio:

```bash
narratio run --session-id 2026-04-04
```

3. Read success output:
   - `narratio run: session <session_id>; executed=<n> skipped=<n>; manifest=<path>`
   - `manifest=<path>` is the local session manifest path to use with `status`.

Notes:

- This command relies on discoverable `pipeline.yml` and `session.yml` unless `--config` and `--session` are passed explicitly.
- For S3 audio input, `session.inputs.audio_s3.prefix` must be configured and audio files must already exist remotely.

## Local filesystem layout and state artifacts

Session root:

- `{workspace.root}/work/{campaign}/{session_id}/`

Primary state:

- `manifest.json`: session-level manifest (authoritative local stage state).
- `runs/{run_id}/manifest.json`: run-level manifest for one invocation.
- `.lock`: session lock file while a run is active.

Canonical session directories:

- `inputs/`
- `audio/`
- `transcripts/`
- `artifacts/`
- `reports/`
- `logs/`
- `config/`
- `current/`
- `runs/`

Run-local stage directories:

- `runs/{run_id}/{stage}/`
- Stage runtime files are written under deterministic run-local subdirectories such as:
  - `outputs/`, `logs/`, `reports/`, `config/`, `scratch/`

Behavior notes:

- Layout creation is idempotent.
- Durable outputs are promoted to canonical session paths after stage success.
- Run-local artifacts remain in `runs/{run_id}/...` unless configured post-archive cleanup removes that run scope.

## Remote archive layout and publish contract

When archive is enabled and run upload is enabled, archive publishes to object storage under:

- Session prefix: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/`
- Run prefix: `{session_prefix}/runs/{run_id}/`

Archive uploads:

- Run record files from run root (including stage subtrees and run manifest), excluding local `audio/`.
- Promoted artifacts from `archive.promote_artifacts` to session-level keys.

Publish order (commit contract):

1. Upload `current/manifest.json`
2. Upload `current/run_id.txt` last

Meaning of `current/run_id.txt`:

- It is the effective remote commit marker for published session state.
- It is written only after required run uploads and required promotions succeed.

## Resume, retry, and safe rerun behavior

Default skip behavior:

- `run` and `run-stage` skip stages already marked `succeeded` unless `--force` is set.

Resume behavior:

- `resume` starts at the first non-`succeeded` stage in canonical stage order.
- If all stages are `succeeded`, `resume` prints that no stages remain.
- `resume --force` runs full stage order rather than starting at first non-succeeded.

Forced rerun behavior:

- Successful forced rerun of an upstream stage marks downstream previously `succeeded` stages as `stale`.
- `stale` stages are not treated as complete and are eligible to run in subsequent commands.

Targeted rerun with one stage:

```bash
narratio run-stage --force <stage>
```

Valid stage names:

- `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `analyze`, `archive`, `notify`

Safe operator pattern:

1. Force-rerun the stage that changed.
2. Run `resume` to rebuild downstream stages in order.

## Cleanup behavior

Cleanup is considered only after run execution completes and only when archive stage both executed and succeeded.

Configured cleanup toggles:

- `pipeline.spool.delete_audio_after_archive=true`
  - deletes only run-scoped spool audio directory: `{spool.root}/{campaign}/{session_id}/{run_id}/audio/`
- `pipeline.workspace.cleanup_after_archive=true`
  - deletes only run-scoped local run directory: `{workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/`

Eligibility gates for cleanup:

- archive is enabled
- archive run upload is enabled
- archive metadata indicates run record upload happened
- archive metadata indicates `current` pointer write completed (`current/run_id.txt` written)

Cleanup does not run for:

- failed runs
- incomplete runs
- unarchived runs
- archive-skipped runs (`archive.enabled=false` or `archive.upload_run=false`)

## Failure and recovery playbooks

What remains after failure:

- Session manifest remains on disk.
- Run manifest remains under `runs/{run_id}/manifest.json`.
- Run-local stage artifacts/logs/config/reports remain under `runs/{run_id}/...`.
- Failed/incomplete runs remain local-only.
- Remote current pointer is not committed if archive prerequisite or pointer-write steps fail.

Recommended recovery flow:

1. Inspect current state:

```bash
narratio status --manifest <manifest-path-from-run-output>
```

2. Fix the root cause (config, input, credentials, adapter availability, etc.).
3. Continue with:
   - `narratio resume --session-id <id>` for ordered continuation, or
   - `narratio run-stage --force <stage>` for targeted correction, then `resume`.

## Operational caveats

- `status` requires an explicit manifest path; there is no direct session-id lookup command.
- S3 audio mode and local audio mode are mutually exclusive in session config.
- Archive verifies stage prerequisites (`prepare` through `analyze`) before publishing.
- By default, archive does not upload local `audio/` into run history.
- Unknown CLI commands fail and print usage.