narratio/docs/internal/stage-cleanup.md

Stage: cleanup

Purpose

Remove explicitly configured local data for the run selected by a successful publish commit. Cleanup is the twelfth and final canonical stage, after notify.

Authorization And Targets

Cleanup is disabled unless at least one of these policies is true:

• pipeline.spool.delete_audio_after_publish
• pipeline.workspace.cleanup_after_publish

An enabled cleanup requires the manifest's publish stage to be succeeded with uploaded=true, a canonical published_run_id, and the exact remote commit and current commit-pointer keys for the manifest campaign/session prefix. The configured campaign and session must match the manifest. Cleanup derives its only possible targets through the canonical artifact path helpers:

• the published run's session spool-audio directory; and
• the published run's workspace run directory.

It does not scan parent directories, infer the newest run, or read object storage. Every deletion uses the root-confined file operation, which rejects a root itself, traversal, symlink escape, and out-of-root targets.

Execution And Resume

Disabled cleanup records an explicit skipped result. Enabled cleanup removes targets in deterministic policy order and treats an already-missing target as success. A successful record contains the published run ID and completed policy names.

A previous cleanup success is reusable only while its semantic configuration matches and every selected target remains absent. A recreated target makes the stage non-resumable. A failure is recorded against cleanup; publish remains succeeded and remote current state is unchanged. On a later normal full run, valid upstream stages are skipped and cleanup is retried without republishing.

narratio publish selects publish only and never invokes cleanup. A bounded run through notify or any earlier endpoint also excludes it. Operators may run narratio run-stage cleanup <session_id> directly; missing, failed, malformed, or identity-mismatched publication evidence fails before deletion.

Implementation And Tests

• Planning and evidence validation: internal/stage/cleanup_plan.go
• Execution and resume: internal/stage/cleanup.go
• Root-confined deletion: internal/fileops/cleanup.go
• Focused tests: internal/stage/cleanup_plan_test.go, internal/stage/cleanup_test.go, and internal/app/cleanup_orchestration_test.go