narratio/docs/operations.md

Operations

This guide describes the implemented operator lifecycle for Narratio.

For field-level configuration, see docs/config.md. For full command/flag reference, see docs/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:

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:

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:

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.