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](overview.md#pipeline-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](../operations.md#publish-workflow).

## Key Behavior

- stage can self-skip when publish disabled or run upload disabled.
- validates prerequisite stage success and object-store availability.
- collects a deterministic run file list plus run `manifest.json`, excluding
  `audio/**` and the run-local `extract/notarius-output/**` staging bundle.
- keeps run-local Notarius receipt and stderr diagnostics eligible for the run
  archive.
- resolves publish output sources through runtime artifact catalog and manifest-aware resolution.
- publishes extraction lanes only through explicit configured output rules;
  neither run-local nor durable Notarius bundles are scanned or uploaded wholesale.
- 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/**` and `extract/notarius-output/**`.
- `extract/notarius.receipt.json` and `extract/notarius.stderr.log` remain
  eligible run-record diagnostics.
- publish locks are not overridden by `--force`.

The commit boundary and cleanup gate are normative architecture invariants; see
[Architecture](../policy/architecture.md#publish-commit-boundary).

## Related Contracts And Tests

- [Configuration](../config.md#publish-configuration-summary) owns output and
  static-lock fields.
- [Operations](../operations.md#publish-locks) owns remote lock lifecycle and
  physical remote state.
- [Artifact Internals](artifacts.md) 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`