Add archive storage path configuration

internal/artifacts/paths.go

@@ -1,6 +1,8 @@
 package artifacts
 
-import "path/filepath"
+import (
+	"path/filepath"
+)
 
 // SessionPaths contains canonical local paths for one session work directory.
 type SessionPaths struct {
@@ -23,6 +25,16 @@ func SessionWorkDir(rootDir, sessionID string) string {
 	return filepath.Join(rootDir, "work", sessionID)
 }
 
+// SessionRunWorkDir returns the campaign/session/run scoped local work directory.
+func SessionRunWorkDir(rootDir, campaign, sessionID, runID string) string {
+	return filepath.Join(rootDir, "work", campaign, sessionID, runID)
+}
+
+// SessionSpoolAudioDir returns the campaign/session/run scoped local spool audio path.
+func SessionSpoolAudioDir(spoolRoot, campaign, sessionID, runID string) string {
+	return filepath.Join(spoolRoot, campaign, sessionID, runID, "audio")
+}
+
 func buildSessionPaths(workspaceRoot, sessionID string) SessionPaths {
 	root := SessionWorkDir(workspaceRoot, sessionID)
 	transcripts := filepath.Join(root, "transcripts")

internal/artifacts/paths_model_test.go

@@ -0,0 +1,24 @@
+package artifacts
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestSessionRunWorkDir(t *testing.T) {
+	root := "/tmp/workspace"
+	got := SessionRunWorkDir(root, "forsaken", "2026-04-19", "20260515T031522Z-a1b2c3d4")
+	want := filepath.Join(root, "work", "forsaken", "2026-04-19", "20260515T031522Z-a1b2c3d4")
+	if got != want {
+		t.Fatalf("SessionRunWorkDir() = %q, want %q", got, want)
+	}
+}
+
+func TestSessionSpoolAudioDir(t *testing.T) {
+	root := "/var/spool/narratio"
+	got := SessionSpoolAudioDir(root, "forsaken", "2026-04-19", "20260515T031522Z-a1b2c3d4")
+	want := filepath.Join(root, "forsaken", "2026-04-19", "20260515T031522Z-a1b2c3d4", "audio")
+	if got != want {
+		t.Fatalf("SessionSpoolAudioDir() = %q, want %q", got, want)
+	}
+}

internal/artifacts/run_id.go

@@ -0,0 +1,30 @@
+package artifacts
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"time"
+)
+
+// NewRunID returns a run ID in format: YYYYMMDDTHHMMSSZ-xxxxxxxx.
+func NewRunID() (string, error) {
+	return NewRunIDWith(time.Now().UTC(), rand.Reader)
+}
+
+// NewRunIDWith returns a run ID in format: YYYYMMDDTHHMMSSZ-xxxxxxxx
+// using an injected timestamp and randomness source.
+func NewRunIDWith(now time.Time, random io.Reader) (string, error) {
+	if random == nil {
+		random = rand.Reader
+	}
+
+	var suffix [4]byte
+	if _, err := io.ReadFull(random, suffix[:]); err != nil {
+		return "", fmt.Errorf("generate run id random suffix: %w", err)
+	}
+
+	ts := now.UTC().Format("20060102T150405Z")
+	return ts + "-" + hex.EncodeToString(suffix[:]), nil
+}

internal/artifacts/run_id_test.go

@@ -0,0 +1,37 @@
+package artifacts
+
+import (
+	"bytes"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestNewRunIDWithFormat(t *testing.T) {
+	now := time.Date(2026, 5, 15, 3, 15, 22, 0, time.UTC)
+	random := bytes.NewReader([]byte{0xa1, 0xb2, 0xc3, 0xd4})
+
+	runID, err := NewRunIDWith(now, random)
+	if err != nil {
+		t.Fatalf("NewRunIDWith() error = %v", err)
+	}
+	if runID != "20260515T031522Z-a1b2c3d4" {
+		t.Fatalf("runID = %q, want %q", runID, "20260515T031522Z-a1b2c3d4")
+	}
+}
+
+func TestNewRunIDWithShape(t *testing.T) {
+	runID, err := NewRunIDWith(time.Now().UTC(), bytes.NewReader([]byte{0x01, 0x02, 0x03, 0x04}))
+	if err != nil {
+		t.Fatalf("NewRunIDWith() error = %v", err)
+	}
+	pattern := regexp.MustCompile(`^\d{8}T\d{6}Z-[0-9a-f]{8}$`)
+	if !pattern.MatchString(runID) {
+		t.Fatalf("runID = %q, want pattern %q", runID, pattern.String())
+	}
+	suffix := runID[len(runID)-8:]
+	if strings.ToLower(suffix) != suffix {
+		t.Fatalf("runID suffix = %q, want lowercase", suffix)
+	}
+}

internal/artifacts/s3_keys.go

@@ -0,0 +1,73 @@
+package artifacts
+
+import (
+	"path"
+	"strings"
+)
+
+// S3SessionPrefix builds the canonical S3 session prefix.
+// Format: {root_prefix}/campaigns/{campaign}/sessions/{session_id}/
+func S3SessionPrefix(rootPrefix, campaign, sessionID string) string {
+	prefix := path.Join(
+		cleanS3PathPart(rootPrefix),
+		"campaigns",
+		cleanS3PathPart(campaign),
+		"sessions",
+		cleanS3PathPart(sessionID),
+	)
+	return ensureS3TrailingSlash(prefix)
+}
+
+// S3RunPrefix builds the canonical S3 run prefix.
+// Format: {session_prefix}/runs/{run_id}/
+func S3RunPrefix(sessionPrefix, runID string) string {
+	prefix := path.Join(strings.TrimSuffix(cleanS3Key(sessionPrefix), "/"), "runs", cleanS3PathPart(runID))
+	return ensureS3TrailingSlash(prefix)
+}
+
+// S3AudioPrefix builds the session audio prefix from configured audio_s3.prefix.
+// Format: {session_prefix}/{audio_s3.prefix}
+func S3AudioPrefix(sessionPrefix, audioPrefix string) string {
+	key := path.Join(strings.TrimSuffix(cleanS3Key(sessionPrefix), "/"), cleanS3Key(audioPrefix))
+	return ensureS3TrailingSlash(key)
+}
+
+// S3CurrentManifestKey returns the current manifest pointer key.
+// Format: {session_prefix}/current/manifest.json
+func S3CurrentManifestKey(sessionPrefix string) string {
+	return path.Join(strings.TrimSuffix(cleanS3Key(sessionPrefix), "/"), "current", "manifest.json")
+}
+
+// S3CurrentRunPointerKey returns the current run pointer key.
+// Format: {session_prefix}/current/run_id.txt
+func S3CurrentRunPointerKey(sessionPrefix string) string {
+	return path.Join(strings.TrimSuffix(cleanS3Key(sessionPrefix), "/"), "current", "run_id.txt")
+}
+
+// S3PromotedArtifactKey returns the destination key for one promoted artifact.
+// Format: {session_prefix}/{promotion.to}
+func S3PromotedArtifactKey(sessionPrefix, to string) string {
+	return path.Join(strings.TrimSuffix(cleanS3Key(sessionPrefix), "/"), cleanS3Key(to))
+}
+
+// S3RunRelativeDestinationKey returns a run-scoped key for a workdir-relative path.
+// Format: {run_prefix}/{relative_workdir_path}
+func S3RunRelativeDestinationKey(runPrefix, relativeWorkdirPath string) string {
+	return path.Join(strings.TrimSuffix(cleanS3Key(runPrefix), "/"), cleanS3Key(relativeWorkdirPath))
+}
+
+func ensureS3TrailingSlash(v string) string {
+	key := cleanS3Key(v)
+	if key == "" {
+		return ""
+	}
+	return strings.TrimSuffix(key, "/") + "/"
+}
+
+func cleanS3PathPart(v string) string {
+	return strings.Trim(strings.ReplaceAll(strings.TrimSpace(v), "\\", "/"), "/")
+}
+
+func cleanS3Key(v string) string {
+	return strings.ReplaceAll(strings.TrimSpace(v), "\\", "/")
+}

internal/artifacts/s3_keys_test.go

@@ -0,0 +1,45 @@
+package artifacts
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestS3KeyConstruction(t *testing.T) {
+	runID := "20260515T031522Z-a1b2c3d4"
+	sessionPrefix := S3SessionPrefix("dnd", "forsaken", "2026-04-19")
+	if sessionPrefix != "dnd/campaigns/forsaken/sessions/2026-04-19/" {
+		t.Fatalf("sessionPrefix = %q", sessionPrefix)
+	}
+
+	audioPrefix := S3AudioPrefix(sessionPrefix, "audio/")
+	if audioPrefix != "dnd/campaigns/forsaken/sessions/2026-04-19/audio/" {
+		t.Fatalf("audioPrefix = %q", audioPrefix)
+	}
+
+	runPrefix := S3RunPrefix(sessionPrefix, runID)
+	wantRunPrefix := "dnd/campaigns/forsaken/sessions/2026-04-19/runs/" + runID + "/"
+	if runPrefix != wantRunPrefix {
+		t.Fatalf("runPrefix = %q, want %q", runPrefix, wantRunPrefix)
+	}
+
+	runPointer := S3CurrentRunPointerKey(sessionPrefix)
+	if runPointer != "dnd/campaigns/forsaken/sessions/2026-04-19/current/run_id.txt" {
+		t.Fatalf("run pointer key = %q", runPointer)
+	}
+
+	manifestKey := S3CurrentManifestKey(sessionPrefix)
+	if manifestKey != "dnd/campaigns/forsaken/sessions/2026-04-19/current/manifest.json" {
+		t.Fatalf("manifest key = %q", manifestKey)
+	}
+
+	promoted := S3PromotedArtifactKey(sessionPrefix, "transcripts/trimmed.json")
+	if promoted != "dnd/campaigns/forsaken/sessions/2026-04-19/transcripts/trimmed.json" {
+		t.Fatalf("promoted key = %q", promoted)
+	}
+
+	runRelative := S3RunRelativeDestinationKey(runPrefix, `logs\whisperx.stdout.log`)
+	if !strings.HasSuffix(runRelative, "/logs/whisperx.stdout.log") {
+		t.Fatalf("runRelative key = %q, want normalized forward slashes", runRelative)
+	}
+}