Added run manifest scaffolding and helpers
This commit is contained in:
164
internal/manifest/run_manifest.go
Normal file
164
internal/manifest/run_manifest.go
Normal file
@@ -0,0 +1,164 @@
|
||||
package manifest
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
type RunManifestStatus string
|
||||
|
||||
const (
|
||||
RunManifestStatusRunning RunManifestStatus = "running"
|
||||
RunManifestStatusSucceeded RunManifestStatus = "succeeded"
|
||||
RunManifestStatusFailed RunManifestStatus = "failed"
|
||||
)
|
||||
|
||||
type RunStageAction string
|
||||
|
||||
const (
|
||||
RunStageActionRun RunStageAction = "run"
|
||||
RunStageActionSkip RunStageAction = "skip"
|
||||
)
|
||||
|
||||
// RunStageRecord tracks lifecycle and provenance for one stage within a single invocation.
|
||||
type RunStageRecord struct {
|
||||
Name string `json:"name"`
|
||||
Action RunStageAction `json:"action"`
|
||||
Status StageStatus `json:"status"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
StartedAt *time.Time `json:"started_at,omitempty"`
|
||||
CompletedAt *time.Time `json:"completed_at,omitempty"`
|
||||
Outputs []ArtifactRecord `json:"outputs,omitempty"`
|
||||
Logs []string `json:"logs,omitempty"`
|
||||
GeneratedConfigs []string `json:"generated_configs,omitempty"`
|
||||
Error *ErrorRecord `json:"error,omitempty"`
|
||||
Metadata map[string]any `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// RunManifest is the invocation-scoped execution record under runs/{run_id}/manifest.json.
|
||||
type RunManifest struct {
|
||||
SessionID string `json:"session_id"`
|
||||
Campaign string `json:"campaign,omitempty"`
|
||||
RunID string `json:"run_id"`
|
||||
Force bool `json:"force"`
|
||||
RequestedStages []string `json:"requested_stages,omitempty"`
|
||||
SessionManifestPath string `json:"session_manifest_path,omitempty"`
|
||||
LocalWorkDir string `json:"local_workdir,omitempty"`
|
||||
LocalSpoolDir string `json:"local_spool_dir,omitempty"`
|
||||
S3Bucket string `json:"s3_bucket,omitempty"`
|
||||
S3SessionPrefix string `json:"s3_session_prefix,omitempty"`
|
||||
S3RunPrefix string `json:"s3_run_prefix,omitempty"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
StartedAt *time.Time `json:"started_at,omitempty"`
|
||||
CompletedAt *time.Time `json:"completed_at,omitempty"`
|
||||
Status RunManifestStatus `json:"status"`
|
||||
LastError *ErrorRecord `json:"last_error,omitempty"`
|
||||
Stages map[string]*RunStageRecord `json:"stages"`
|
||||
Metadata map[string]any `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// NewRun constructs a new run manifest with deterministic timestamps.
|
||||
func NewRun(sessionID, campaign, runID string, force bool, requestedStages []string, now time.Time) *RunManifest {
|
||||
return &RunManifest{
|
||||
SessionID: strings.TrimSpace(sessionID),
|
||||
Campaign: strings.TrimSpace(campaign),
|
||||
RunID: strings.TrimSpace(runID),
|
||||
Force: force,
|
||||
RequestedStages: append([]string(nil), requestedStages...),
|
||||
CreatedAt: now,
|
||||
UpdatedAt: now,
|
||||
StartedAt: timePtr(now),
|
||||
Status: RunManifestStatusRunning,
|
||||
Stages: map[string]*RunStageRecord{},
|
||||
}
|
||||
}
|
||||
|
||||
func (m *RunManifest) SetStageAction(name string, action RunStageAction, at time.Time) {
|
||||
s := m.ensureStage(name, at)
|
||||
s.Action = action
|
||||
s.UpdatedAt = at
|
||||
m.UpdatedAt = at
|
||||
}
|
||||
|
||||
func (m *RunManifest) MarkStageRunning(name string, at time.Time) {
|
||||
s := m.ensureStage(name, at)
|
||||
s.Status = StatusRunning
|
||||
s.StartedAt = timePtr(at)
|
||||
s.CompletedAt = nil
|
||||
s.Error = nil
|
||||
s.UpdatedAt = at
|
||||
m.UpdatedAt = at
|
||||
}
|
||||
|
||||
func (m *RunManifest) MarkStageSucceeded(name string, at time.Time, outputs []ArtifactRecord) {
|
||||
s := m.ensureStage(name, at)
|
||||
s.Status = StatusSucceeded
|
||||
s.CompletedAt = timePtr(at)
|
||||
s.Error = nil
|
||||
s.Outputs = append([]ArtifactRecord(nil), outputs...)
|
||||
s.UpdatedAt = at
|
||||
m.UpdatedAt = at
|
||||
}
|
||||
|
||||
func (m *RunManifest) MarkStageFailed(name string, at time.Time, message string) {
|
||||
s := m.ensureStage(name, at)
|
||||
s.Status = StatusFailed
|
||||
s.CompletedAt = timePtr(at)
|
||||
s.Error = &ErrorRecord{Message: strings.TrimSpace(message), At: timePtr(at)}
|
||||
s.UpdatedAt = at
|
||||
m.LastError = &ErrorRecord{Message: strings.TrimSpace(message), At: timePtr(at)}
|
||||
m.UpdatedAt = at
|
||||
m.Status = RunManifestStatusFailed
|
||||
m.CompletedAt = timePtr(at)
|
||||
}
|
||||
|
||||
func (m *RunManifest) MarkStageSkipped(name string, at time.Time, reason string) {
|
||||
s := m.ensureStage(name, at)
|
||||
s.Status = StatusSkipped
|
||||
s.CompletedAt = timePtr(at)
|
||||
s.Error = &ErrorRecord{Message: strings.TrimSpace(reason), Code: "skipped", At: timePtr(at)}
|
||||
s.UpdatedAt = at
|
||||
m.UpdatedAt = at
|
||||
}
|
||||
|
||||
func (m *RunManifest) MarkSucceeded(at time.Time) {
|
||||
m.Status = RunManifestStatusSucceeded
|
||||
m.CompletedAt = timePtr(at)
|
||||
m.UpdatedAt = at
|
||||
}
|
||||
|
||||
func (m *RunManifest) MarkFailed(at time.Time, message string) {
|
||||
m.Status = RunManifestStatusFailed
|
||||
m.CompletedAt = timePtr(at)
|
||||
m.LastError = &ErrorRecord{Message: strings.TrimSpace(message), At: timePtr(at)}
|
||||
m.UpdatedAt = at
|
||||
}
|
||||
|
||||
func (m *RunManifest) ensureStage(name string, at time.Time) *RunStageRecord {
|
||||
if m.Stages == nil {
|
||||
m.Stages = map[string]*RunStageRecord{}
|
||||
}
|
||||
|
||||
stageName := strings.TrimSpace(name)
|
||||
s, ok := m.Stages[stageName]
|
||||
if !ok || s == nil {
|
||||
s = &RunStageRecord{
|
||||
Name: stageName,
|
||||
Action: RunStageActionRun,
|
||||
Status: StatusPending,
|
||||
CreatedAt: at,
|
||||
UpdatedAt: at,
|
||||
}
|
||||
m.Stages[stageName] = s
|
||||
}
|
||||
if s.Name == "" {
|
||||
s.Name = stageName
|
||||
}
|
||||
if s.CreatedAt.IsZero() {
|
||||
s.CreatedAt = at
|
||||
}
|
||||
|
||||
return s
|
||||
}
|
||||
50
internal/manifest/run_manifest_test.go
Normal file
50
internal/manifest/run_manifest_test.go
Normal file
@@ -0,0 +1,50 @@
|
||||
package manifest
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestRunManifestStageMarkHelpers(t *testing.T) {
|
||||
rm := NewRun("2026-05-03", "forsaken", "20260517T000000Z-abcdef12", false, []string{"prepare"}, time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
|
||||
if rm.Status != RunManifestStatusRunning {
|
||||
t.Fatalf("status = %q, want %q", rm.Status, RunManifestStatusRunning)
|
||||
}
|
||||
|
||||
runningAt := time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC)
|
||||
rm.SetStageAction("prepare", RunStageActionRun, runningAt)
|
||||
rm.MarkStageRunning("prepare", runningAt)
|
||||
rm.MarkStageSucceeded("prepare", runningAt.Add(30*time.Second), []ArtifactRecord{
|
||||
{Kind: "input", LocalPath: "inputs/session.yml"},
|
||||
})
|
||||
|
||||
stage := rm.Stages["prepare"]
|
||||
if stage == nil {
|
||||
t.Fatal("prepare stage missing")
|
||||
}
|
||||
if stage.Action != RunStageActionRun {
|
||||
t.Fatalf("action = %q, want %q", stage.Action, RunStageActionRun)
|
||||
}
|
||||
if stage.Status != StatusSucceeded {
|
||||
t.Fatalf("status = %q, want %q", stage.Status, StatusSucceeded)
|
||||
}
|
||||
|
||||
skippedAt := runningAt.Add(1 * time.Minute)
|
||||
rm.SetStageAction("notify", RunStageActionSkip, skippedAt)
|
||||
rm.MarkStageSkipped("notify", skippedAt, "already_succeeded")
|
||||
skipped := rm.Stages["notify"]
|
||||
if skipped == nil {
|
||||
t.Fatal("notify stage missing")
|
||||
}
|
||||
if skipped.Action != RunStageActionSkip {
|
||||
t.Fatalf("action = %q, want %q", skipped.Action, RunStageActionSkip)
|
||||
}
|
||||
if skipped.Status != StatusSkipped {
|
||||
t.Fatalf("status = %q, want %q", skipped.Status, StatusSkipped)
|
||||
}
|
||||
|
||||
rm.MarkSucceeded(skippedAt.Add(10 * time.Second))
|
||||
if rm.Status != RunManifestStatusSucceeded {
|
||||
t.Fatalf("status = %q, want %q", rm.Status, RunManifestStatusSucceeded)
|
||||
}
|
||||
}
|
||||
@@ -129,6 +129,89 @@ func (s *LocalStore) Save(ctx context.Context, path string, m *Manifest) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// CreateRun returns a new in-memory run manifest for one invocation.
|
||||
func (s *LocalStore) CreateRun(
|
||||
ctx context.Context,
|
||||
sessionID, campaign, runID string,
|
||||
force bool,
|
||||
requestedStages []string,
|
||||
) (*RunManifest, error) {
|
||||
if err := checkContext(ctx); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if strings.TrimSpace(sessionID) == "" {
|
||||
return nil, fmt.Errorf("create run manifest: session_id is required")
|
||||
}
|
||||
if strings.TrimSpace(runID) == "" {
|
||||
return nil, fmt.Errorf("create run manifest: run_id is required")
|
||||
}
|
||||
|
||||
now := time.Now().UTC()
|
||||
return NewRun(sessionID, campaign, runID, force, requestedStages, now), nil
|
||||
}
|
||||
|
||||
// LoadRun reads and validates a local JSON run manifest from path.
|
||||
func (s *LocalStore) LoadRun(ctx context.Context, path string) (*RunManifest, error) {
|
||||
if err := checkContext(ctx); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if strings.TrimSpace(path) == "" {
|
||||
return nil, fmt.Errorf("load run manifest: path is required")
|
||||
}
|
||||
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("load run manifest %q: %w", path, err)
|
||||
}
|
||||
|
||||
var m RunManifest
|
||||
if err := json.Unmarshal(data, &m); err != nil {
|
||||
return nil, fmt.Errorf("decode run manifest %q: %w", path, err)
|
||||
}
|
||||
|
||||
if err := validateLoadedRunManifest(&m); err != nil {
|
||||
return nil, fmt.Errorf("run manifest %q invalid: %w", path, err)
|
||||
}
|
||||
normalizeRunManifest(&m)
|
||||
|
||||
return &m, nil
|
||||
}
|
||||
|
||||
// SaveRun writes the run manifest to path atomically via temp file + rename.
|
||||
func (s *LocalStore) SaveRun(ctx context.Context, path string, m *RunManifest) error {
|
||||
if err := checkContext(ctx); err != nil {
|
||||
return err
|
||||
}
|
||||
if strings.TrimSpace(path) == "" {
|
||||
return fmt.Errorf("save run manifest: path is required")
|
||||
}
|
||||
if m == nil {
|
||||
return fmt.Errorf("save run manifest: manifest is nil")
|
||||
}
|
||||
if strings.TrimSpace(m.SessionID) == "" {
|
||||
return fmt.Errorf("save run manifest: session_id is required")
|
||||
}
|
||||
if strings.TrimSpace(m.RunID) == "" {
|
||||
return fmt.Errorf("save run manifest: run_id is required")
|
||||
}
|
||||
if m.CreatedAt.IsZero() {
|
||||
return fmt.Errorf("save run manifest: created_at is required")
|
||||
}
|
||||
|
||||
m.UpdatedAt = time.Now().UTC()
|
||||
if m.Stages == nil {
|
||||
m.Stages = map[string]*RunStageRecord{}
|
||||
}
|
||||
|
||||
data, err := json.MarshalIndent(m, "", " ")
|
||||
if err != nil {
|
||||
return fmt.Errorf("save run manifest: marshal: %w", err)
|
||||
}
|
||||
data = append(data, '\n')
|
||||
|
||||
return writeJSONAtomically(ctx, path, ".run-manifest.json.tmp-*", data)
|
||||
}
|
||||
|
||||
func validateLoadedManifest(m *Manifest) error {
|
||||
if m == nil {
|
||||
return fmt.Errorf("manifest is nil")
|
||||
@@ -161,6 +244,88 @@ func normalizeManifest(m *Manifest) {
|
||||
}
|
||||
}
|
||||
|
||||
func validateLoadedRunManifest(m *RunManifest) error {
|
||||
if m == nil {
|
||||
return fmt.Errorf("manifest is nil")
|
||||
}
|
||||
if strings.TrimSpace(m.SessionID) == "" {
|
||||
return fmt.Errorf("session_id is required")
|
||||
}
|
||||
if strings.TrimSpace(m.RunID) == "" {
|
||||
return fmt.Errorf("run_id is required")
|
||||
}
|
||||
if m.CreatedAt.IsZero() {
|
||||
return fmt.Errorf("created_at is required")
|
||||
}
|
||||
if m.UpdatedAt.IsZero() {
|
||||
return fmt.Errorf("updated_at is required")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func normalizeRunManifest(m *RunManifest) {
|
||||
if m.Stages == nil {
|
||||
m.Stages = map[string]*RunStageRecord{}
|
||||
}
|
||||
for name, stage := range m.Stages {
|
||||
if stage == nil {
|
||||
stage = &RunStageRecord{
|
||||
Name: name,
|
||||
Action: RunStageActionRun,
|
||||
Status: StatusPending,
|
||||
CreatedAt: m.CreatedAt,
|
||||
UpdatedAt: m.UpdatedAt,
|
||||
}
|
||||
m.Stages[name] = stage
|
||||
}
|
||||
if stage.Name == "" {
|
||||
stage.Name = name
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func writeJSONAtomically(ctx context.Context, path, tempPattern string, data []byte) error {
|
||||
dir := filepath.Dir(path)
|
||||
if err := os.MkdirAll(dir, 0o755); err != nil {
|
||||
return fmt.Errorf("create directory %q: %w", dir, err)
|
||||
}
|
||||
|
||||
tmp, err := os.CreateTemp(dir, tempPattern)
|
||||
if err != nil {
|
||||
return fmt.Errorf("create temp file: %w", err)
|
||||
}
|
||||
tmpName := tmp.Name()
|
||||
removeTmp := true
|
||||
defer func() {
|
||||
if removeTmp {
|
||||
_ = os.Remove(tmpName)
|
||||
}
|
||||
}()
|
||||
|
||||
if _, err := tmp.Write(data); err != nil {
|
||||
_ = tmp.Close()
|
||||
return fmt.Errorf("write temp file: %w", err)
|
||||
}
|
||||
if err := tmp.Sync(); err != nil {
|
||||
_ = tmp.Close()
|
||||
return fmt.Errorf("sync temp file: %w", err)
|
||||
}
|
||||
if err := tmp.Close(); err != nil {
|
||||
return fmt.Errorf("close temp file: %w", err)
|
||||
}
|
||||
if err := checkContext(ctx); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if err := os.Rename(tmpName, path); err != nil {
|
||||
return fmt.Errorf("rename temp file: %w", err)
|
||||
}
|
||||
removeTmp = false
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func checkContext(ctx context.Context) error {
|
||||
if ctx == nil {
|
||||
return nil
|
||||
|
||||
@@ -150,3 +150,73 @@ func TestLoadRejectsInvalidManifest(t *testing.T) {
|
||||
t.Fatalf("error = %q, want session_id validation", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestLocalStoreCreateSaveLoadRunManifestRoundTrip(t *testing.T) {
|
||||
store := &LocalStore{}
|
||||
ctx := context.Background()
|
||||
|
||||
run, err := store.CreateRun(
|
||||
ctx,
|
||||
"2026-05-03",
|
||||
"forsaken",
|
||||
"20260517T000000Z-abcdef12",
|
||||
true,
|
||||
[]string{"prepare", "transcribe"},
|
||||
)
|
||||
if err != nil {
|
||||
t.Fatalf("CreateRun() error = %v", err)
|
||||
}
|
||||
run.SessionManifestPath = "/var/lib/narratio/work/forsaken/2026-05-03/manifest.json"
|
||||
run.MarkStageRunning("prepare", time.Date(2026, 5, 3, 12, 1, 0, 0, time.UTC))
|
||||
run.MarkStageSucceeded("prepare", time.Date(2026, 5, 3, 12, 2, 0, 0, time.UTC), []ArtifactRecord{
|
||||
{Kind: "input", LocalPath: "inputs/session.yml"},
|
||||
})
|
||||
run.MarkSucceeded(time.Date(2026, 5, 3, 12, 3, 0, 0, time.UTC))
|
||||
|
||||
path := filepath.Join(t.TempDir(), "run-manifest.json")
|
||||
if err := store.SaveRun(ctx, path, run); err != nil {
|
||||
t.Fatalf("SaveRun() error = %v", err)
|
||||
}
|
||||
|
||||
loaded, err := store.LoadRun(ctx, path)
|
||||
if err != nil {
|
||||
t.Fatalf("LoadRun() error = %v", err)
|
||||
}
|
||||
|
||||
if loaded.SessionID != "2026-05-03" {
|
||||
t.Fatalf("SessionID = %q, want %q", loaded.SessionID, "2026-05-03")
|
||||
}
|
||||
if loaded.Campaign != "forsaken" {
|
||||
t.Fatalf("Campaign = %q, want %q", loaded.Campaign, "forsaken")
|
||||
}
|
||||
if loaded.RunID != "20260517T000000Z-abcdef12" {
|
||||
t.Fatalf("RunID = %q, want %q", loaded.RunID, "20260517T000000Z-abcdef12")
|
||||
}
|
||||
if loaded.Status != RunManifestStatusSucceeded {
|
||||
t.Fatalf("Status = %q, want %q", loaded.Status, RunManifestStatusSucceeded)
|
||||
}
|
||||
if loaded.Stages["prepare"] == nil || loaded.Stages["prepare"].Status != StatusSucceeded {
|
||||
t.Fatalf("prepare stage = %#v, want succeeded", loaded.Stages["prepare"])
|
||||
}
|
||||
if loaded.Stages["prepare"].Action != RunStageActionRun {
|
||||
t.Fatalf("prepare action = %q, want %q", loaded.Stages["prepare"].Action, RunStageActionRun)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadRunRejectsInvalidManifest(t *testing.T) {
|
||||
store := &LocalStore{}
|
||||
ctx := context.Background()
|
||||
|
||||
path := filepath.Join(t.TempDir(), "run-manifest.json")
|
||||
if err := os.WriteFile(path, []byte(`{"session_id":"2026-05-03"}`), 0o644); err != nil {
|
||||
t.Fatalf("WriteFile() error = %v", err)
|
||||
}
|
||||
|
||||
_, err := store.LoadRun(ctx, path)
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "run_id is required") {
|
||||
t.Fatalf("error = %q, want run_id validation", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user