Require explicit manifest schemas

internal/manifest/manifest.go

@@ -7,6 +7,15 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/artifactmodel"
 )
 
+const (
+	// SessionManifestSchemaVersion identifies the only supported durable session
+	// manifest representation.
+	SessionManifestSchemaVersion = "narratio.session-manifest.v1"
+	// RunManifestSchemaVersion identifies the only supported invocation manifest
+	// representation.
+	RunManifestSchemaVersion = "narratio.run-manifest.v1"
+)
+
 // ErrorRecord captures structured error metadata at run or stage scope.
 type ErrorRecord struct {
 	Message string     `json:"message"`
@@ -95,6 +104,7 @@ type SelectedProfileProvenance struct {
 
 // Manifest is the durable run-state record for a session execution.
 type Manifest struct {
+	SchemaVersion      string                     `json:"schema_version"`
 	SessionID          string                     `json:"session_id"`
 	Campaign           string                     `json:"campaign,omitempty"`
 	RunID              string                     `json:"run_id,omitempty"`
@@ -117,10 +127,11 @@ type Manifest struct {
 // New constructs a new manifest with deterministic timestamps.
 func New(sessionID string, now time.Time) *Manifest {
 	return &Manifest{
-		SessionID: strings.TrimSpace(sessionID),
-		CreatedAt: now,
-		UpdatedAt: now,
-		Stages:    map[string]*StageRecord{},
+		SchemaVersion: SessionManifestSchemaVersion,
+		SessionID:     strings.TrimSpace(sessionID),
+		CreatedAt:     now,
+		UpdatedAt:     now,
+		Stages:        map[string]*StageRecord{},
 	}
 }
 
@@ -210,6 +221,10 @@ func (m *Manifest) ensureStage(name string, at time.Time) *StageRecord {
 			CreatedAt: at,
 			UpdatedAt: at,
 		}
+		if stageName == "analyze" {
+			s.AnalyzeStateVersion = AnalyzeStateContractVersion
+			s.AnalyzeArtifacts = map[string]AnalyzeArtifactRecord{}
+		}
 		m.Stages[stageName] = s
 	}