narratio/docs/internal/stage-publish.md

Stage: publish

Purpose

Upload run/session outputs to object storage and atomically advance remote current state.

Inputs

• successful preceding stages from the canonical stage set
• invocation-scoped run files
• resolved publish output rules
• effective publish locks (static + remote merged lock set)
• durable previous-session cache files when present

Outputs

• uploaded invocation record and selected publish outputs;
• uploaded durable previous-session cache files when present;
• updated remote current manifest; and
• remote current-run commit marker, written last.

Exact remote placement and the operator workflow belong in Operations.

Key Behavior

• stage can self-skip when publish disabled or run upload disabled.
• validates prerequisite stage success and object-store availability.
• collects deterministic run file list plus run manifest.json.
• resolves publish output sources through runtime artifact catalog and manifest-aware resolution.
• selected artifact filter applies to configured artifact sources only.
• locked outputs are skipped intentionally (including required ones).
• optional missing outputs are skipped; required missing unlocked outputs fail.
• writes remote current manifest before current run pointer.

Metadata Signals

Includes counts/lists for:

• run uploads
• published output uploads
• previous uploads
• skipped optional outputs
• skipped unselected outputs
• locked outputs
• current-state key paths
• current_pointer_written

Invariants

• current/run_id.txt is the remote commit marker and is written last.
• run upload excludes audio/**.
• publish locks are not overridden by --force.

The commit boundary and cleanup gate are normative architecture invariants; see Architecture.

Related Contracts And Tests

• Configuration owns output and static-lock fields.
• Operations owns remote lock lifecycle and physical remote state.
• Artifact Internals explains source resolution and current-state helpers.
• Implementation and tests: internal/stage/publish.go, internal/stage/publish_test.go, internal/app/operator_helpers_test.go, internal/app/post_publish_cleanup_test.go