Promote current session artifacts to storage

docs/archive-storage.md

@@ -1,27 +1,38 @@
 # Archive Storage
 
-This document describes implemented archive-stage storage behavior.
+This document describes implemented archive-stage publish behavior.
+
+## S3 Paths
+
+Session root:
+
+`{root_prefix}/campaigns/{campaign}/sessions/{session_id}/`
+
+Run prefix:
+
+`{root_prefix}/campaigns/{campaign}/sessions/{session_id}/runs/{run_id}/`
 
 ## Scope
 
 Implemented:
 
 - archive uploads successful run records to remote object storage through the storage backend abstraction.
-- upload destination is the run prefix:
-  - `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/runs/{run_id}/`
+- archive uploads configured promoted outputs to session-level keys.
+- archive uploads `current/manifest.json`.
+- archive uploads `current/run_id.txt` last as the effective commit marker.
 - tests use fake storage and do not require live S3.
 
-Not implemented:
+Future work:
 
-- promotion uploads to top-level `transcripts/` or `artifacts/`
-- `current/manifest.json` write
-- `current/run_id.txt` write
-- audio re-upload from local workdir
-- failed/incomplete run uploads
+- spool audio cleanup/deletion behavior
+- `notify` stage behavior
+- stale detection
+- optional future source-audio upload mode
+- additional artifact generation beyond current implemented set
 
 ## Prerequisites
 
-Archive verifies the following stages succeeded before upload:
+Archive verifies these stages succeeded before upload:
 
 - `prepare`
 - `transcribe`
@@ -32,8 +43,9 @@ Archive verifies the following stages succeeded before upload:
 - `analyze`
 
 If any prerequisite is missing or not succeeded, archive fails and does not upload.
+Failed or incomplete runs remain local only.
 
-## Uploaded Run Record
+## Run Upload
 
 Archive uploads existing files from the run workdir when present:
 
@@ -45,12 +57,38 @@ Archive uploads existing files from the run workdir when present:
 - `logs/`
 - `manifest.json`
 
-Archive preserves relative file paths under `runs/{run_id}/`.
+Relative paths are preserved under `runs/{run_id}/`.
 
-Example:
+## Promotion Rules
 
-- local `transcripts/raw/speaker.json`
-- remote `runs/{run_id}/transcripts/raw/speaker.json`
+Archive applies `archive.promote_artifacts` in config order.
+
+Rule behavior:
+
+- `from`: local workdir-relative source path
+- `to`: session-root-relative destination key
+- `required: true`: missing source fails archive
+- `required: false`: missing source is skipped and recorded
+
+Default promoted outputs:
+
+- `transcripts/trimmed.json`
+- `artifacts/session_recap.md`
+
+## Current Pointers
+
+Archive writes:
+
+1. `current/manifest.json` (after run upload + promotions)
+2. `current/run_id.txt` last
+
+`current/run_id.txt` contains exactly:
+
+- `{run_id}` plus trailing newline
+
+Writing `current/run_id.txt` last makes it the effective commit marker for published session state.
+
+If any required run upload, promotion upload, or current-manifest upload fails, archive returns failure and does not write `current/run_id.txt`.
 
 ## Audio Upload Policy
 
@@ -64,10 +102,14 @@ Original audio is expected at the session-level audio prefix and is not duplicat
 
 ## Metadata
 
-Archive stage metadata includes non-secret upload context:
+Archive stage metadata includes non-secret upload context (for example):
 
 - `s3_bucket`
 - `s3_run_prefix`
-- `files_uploaded`
-- `uploaded_paths`
+- run upload counts/paths
+- promoted upload counts/paths
+- skipped optional promotions
+- `current_manifest_key`
+- `current_run_id_key`
+- `current_pointer_written`
 - `audio_upload_skipped`

docs/roadmap/narratio-s3-archive-implementation-plan.md

@@ -107,11 +107,22 @@ Implemented in repository:
   - local audio is not uploaded by default
   - upload uses storage backend abstraction and deterministic ordering
   - archive skips cleanly when `archive.enabled` or `archive.upload_run` is false
+- archive promotion and current publish behavior:
+  - promotion rules upload configured outputs to session-level destinations
+  - required missing promotion sources fail archive
+  - optional missing promotion sources are skipped and recorded
+  - `current/manifest.json` is uploaded after run upload and promotions
+  - `current/run_id.txt` is uploaded last as the effective commit marker
+  - current pointer content is `{run_id}` plus trailing newline
+  - if promotion/current manifest upload fails, current pointer is not written
 
 Not implemented yet:
 
-- promotion uploads
-- writing `current/manifest.json` and `current/run_id.txt` to S3
+- spool audio cleanup / deletion behavior
+- `notify` stage behavior
+- generic stale detection based on input/config checksums
+- optional future mode for uploading source audio from local workspace/spool
+- additional artifact generation beyond current implemented set
 
 ## 3. S3 Layout