# 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 object storage under the session audio 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>`
- use `manifest=<path>` with `status` for inspection.

Notes:
- default config/session discovery applies unless `--config` and `--session` are passed.
- S3 audio mode requires `session.inputs.audio_s3.prefix` and valid object-store access.

## Local filesystem layout and state artifacts

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

Primary state:
- `manifest.json`: session-level stage state.
- `runs/{run_id}/manifest.json`: invocation-level state.
- `.lock`: session lock 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}/` with stage-local `outputs/`, `logs/`, `reports/`, `config/`, `scratch/`.

Behavior:
- directory creation is idempotent.
- stage outputs are generally generated run-local first, then promoted to canonical paths on success.

## Analyze artifact execution lifecycle

Analyze executes configured artifacts from `pipeline.scriptorium.artifacts`.

Execution model:
- executable set = enabled artifacts, filtered by `--artifacts` when provided.
- artifact-to-artifact dependencies are declared via `depends_on`.
- selected artifacts run in deterministic dependency order.
- after each successful artifact run, output is promoted to configured canonical `output_path`.

Configured artifact source reuse:
- a non-executable configured artifact can satisfy inputs if its configured output file already exists and is valid.
- reused configured artifact provenance is `filesystem.disabled_artifact_output`.

`--artifacts` behavior:
- accepted on `run`, `resume`, and `run-stage analyze`.
- filters analyze execution only; does not force stage rerun.

## Remote archive layout and publish contract

When archive is enabled and run upload is enabled, archive publishes 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 (excluding `audio/`).
- promoted files from explicit `archive.promote_artifacts` rules.

Publish order:
1. upload `current/manifest.json`
2. upload `current/run_id.txt` last

`current/run_id.txt` is the remote commit marker.

Archive promotion is explicit and path-based:
- Narratio does not auto-promote all generated analyze artifacts.
- missing required promotion sources fail archive stage.
- missing optional promotion sources are skipped.

## Resume, retry, and safe rerun behavior

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

Resume:
- `resume` starts at first non-succeeded stage.
- `resume --force` runs full stage order.

Forced reruns:
- force-rerunning an upstream succeeded stage marks downstream succeeded stages as `stale`.

Safe rerun pattern:
1. rerun the changed stage with `--force`.
2. run `resume` to rebuild downstream stages.

## Cleanup behavior

Cleanup is considered only when archive stage executed and succeeded.

Cleanup toggles:
- `pipeline.spool.delete_audio_after_archive=true` deletes run-scoped spool audio.
- `pipeline.workspace.cleanup_after_archive=true` deletes run-scoped local run directory.

Cleanup eligibility gates:
- archive enabled
- archive run upload enabled
- run record upload completed
- current pointer write completed (`current/run_id.txt` written)

No cleanup for failed/incomplete/unarchived/archive-skipped runs.

## Failure and recovery playbooks

After failure, Narratio keeps:
- session manifest
- run manifest
- run-local artifacts/logs/config/reports

Failed or incomplete runs remain local-only.

Recommended recovery:

1. inspect state:

```bash
narratio status --manifest <manifest-path>
```

2. fix root cause (config/input/credentials/service availability).
3. continue with `resume`, or targeted `run-stage --force` followed by `resume`.

## Operational caveats

- `status` requires explicit `--manifest`; there is no session-id lookup command.
- local and S3 audio input modes are mutually exclusive.
- archive publish requires upstream stages through `analyze` to be `succeeded`.
- required promotion rules can fail when selected analyze artifacts did not generate a required file path.