Bind declarative state effects to admission and target law (#209)

* Close declarative state effect boundaries

* Preserve append-only release history

* Preserve journal continuity across runtime updates

Author: bigboateng

boatstack/delivery/program_manifest_test.go

@@ -316,6 +316,7 @@ func programFixture() delivery.ProgramManifest {
 	advance.TargetPhases = []delivery.ProtocolPhase{delivery.PhaseTerminal}
 	advance.ObjectiveKinds = []delivery.ObjectiveKind{delivery.ObjectiveVerified}
 	advance.Authority = []delivery.AuthorityClass{delivery.AuthorityHuman, delivery.AuthorityRepository}
+	advance.RequiredCapabilities = []delivery.Capability{delivery.CapabilityRepositoryWrite, delivery.CapabilityProductMutate}
 	advance.Effect = "program.advance"
 	advance.LocalEffects = []delivery.EffectID{"program.advance"}
 	advance.Prescription = delivery.Prescription{Operation: "advance", Arguments: []string{"--exact"}, ExpectedPostcondition: "terminal"}
@@ -331,15 +332,15 @@ func programFixture() delivery.ProgramManifest {
 		SchemaVersion: delivery.ProgramSchemaVersion, ProgramID: "test-program", ProgramVersion: "1", RequiresRuntime: ">=1.0.0",
 		Capabilities: delivery.ProgramCapabilities{
 			Effects: []string{"program.advance", "program.recover"}, Verifiers: []string{"program.current", "program.terminal"},
-			CapabilitySurface: []delivery.Capability{delivery.CapabilityRepositoryWrite, delivery.CapabilityCommandExecute},
+			CapabilitySurface: []delivery.Capability{delivery.CapabilityRepositoryWrite, delivery.CapabilityCommandExecute, delivery.CapabilityProductMutate},
 		},
 		OwnedResources: []string{"program.state"}, ObjectiveContracts: []delivery.ObjectiveContract{{ObjectiveKind: delivery.ObjectiveVerified, Conditions: []delivery.FacetCondition{delivery.KnownCondition(delivery.FacetDelivery, "terminal")}}},
 		Transitions: []delivery.ProgramTransition{advance, recovery},
 	}
 }
 
 func runtimeFixture() delivery.RuntimeCompatibility {
-	return delivery.RuntimeCompatibility{Version: "v1.2.3", Effects: []string{"program.advance", "program.recover", "alternate.effect"}, Verifiers: []string{"program.current", "program.terminal", "alternate.verifier"}, Capabilities: []delivery.Capability{delivery.CapabilityRepositoryWrite, delivery.CapabilityCommandExecute, delivery.CapabilityHumanApprove}}
+	return delivery.RuntimeCompatibility{Version: "v1.2.3", Effects: []string{"program.advance", "program.recover", "alternate.effect"}, Verifiers: []string{"program.current", "program.terminal", "alternate.verifier"}, Capabilities: []delivery.Capability{delivery.CapabilityRepositoryWrite, delivery.CapabilityCommandExecute, delivery.CapabilityProductMutate, delivery.CapabilityHumanApprove}}
 }
 
 func loadManifest(t *testing.T, manifest delivery.ProgramManifest) delivery.ControlProgram {

boatstack/internal/softwaredelivery/catalog/capability.go

@@ -3,7 +3,8 @@ package catalog
 import (
 	"fmt"
 	"sort"
-	"strings"
+
+	"github.com/operatorstack/boatstack/boatstack/internal/softwaredelivery/model"
 )
 
 // Capability names a kernel-enforced class of effect. A declaration narrows
@@ -131,17 +132,17 @@ func KernelEffectCapabilities(transition Transition) []Capability {
 	if transition.RuntimeExecution {
 		required[CapabilityCommandExecute] = true
 	}
+	for _, facet := range transition.OwnedFacets {
+		if facet == model.StateFacetProduct {
+			required[CapabilityProductMutate] = true
+		}
+	}
 	id := string(transition.Effect)
 	switch id {
 	case "gate.build.record", "gate.test.record", "workspace.cut", "workspace.sync", "workspace.cleanup", "workspace.reap",
 		"publication.observe", "publication.reconcile", "publication.execute", "publication.correct":
 		required[CapabilityCommandExecute] = true
 	}
-	if strings.HasPrefix(id, "objective.") || strings.HasPrefix(id, "plan.") || strings.HasPrefix(id, "workspace.") ||
-		strings.HasPrefix(id, "gate.") || strings.HasPrefix(id, "evidence.") || strings.HasPrefix(id, "delivery.") ||
-		strings.HasPrefix(id, "publication.") {
-		required[CapabilityProductMutate] = true
-	}
 	if id == "publication.preview" {
 		required[CapabilityPublicationPrepare] = true
 	}

boatstack/internal/softwaredelivery/catalog/capability_test.go

@@ -1,6 +1,10 @@
 package catalog
 
-import "testing"
+import (
+	"testing"
+
+	"github.com/operatorstack/boatstack/boatstack/internal/softwaredelivery/model"
+)
 
 func TestCapabilityVocabularyFailsClosed(t *testing.T) {
 	if _, err := NormalizeCapabilities("test", []Capability{"production.nuke"}); err == nil {
@@ -15,6 +19,7 @@ func TestKernelEffectClassificationCannotBeWeakenedByTransitionDeclaration(t *te
 	// control-law: repository-authored requirements cannot under-classify a kernel effect
 	transition := Transition{
 		ID: "program/publish", Class: EventOwnedExternal, Effect: "publication.execute",
+		OwnedFacets:          []model.StateFacet{model.StateFacetControl, model.StateFacetProduct},
 		RequiredCapabilities: []Capability{CapabilityRepositoryWrite},
 		DeclaredCapabilities: []Capability{CapabilityRepositoryWrite, CapabilityCommandExecute, CapabilityProductMutate, CapabilityPublicationPublish},
 	}
@@ -26,6 +31,18 @@ func TestKernelEffectClassificationCannotBeWeakenedByTransitionDeclaration(t *te
 	}
 }
 
+func TestProductOwnershipRequiresProductMutationForArbitraryEffect(t *testing.T) {
+	transition := Transition{
+		ID: "program/advance", Class: EventOwnedLocal, Effect: "acme.advance",
+		OwnedFacets:          []model.StateFacet{model.StateFacetControl, model.StateFacetProduct},
+		RequiredCapabilities: []Capability{CapabilityRepositoryWrite},
+	}
+	required := NewCapabilitySet(RequiredCapabilities(transition)...)
+	if !required[CapabilityProductMutate] {
+		t.Fatalf("product-owning arbitrary effect was under-classified: %v", required.Sorted())
+	}
+}
+
 func TestCapabilityClassesHaveNoImplicitHierarchy(t *testing.T) {
 	granted := AuthorityCapabilities(AuthoritySet{AuthorityProvider: true})
 	if !granted[CapabilityPublicationPublish] || granted[CapabilityPublicationPrepare] || granted[CapabilityRepositoryWrite] {

boatstack/internal/softwaredelivery/catalog/state_effect_closure_test.go

@@ -126,6 +126,19 @@ func TestDeclarativeAssignmentsRejectApplyTimeOnlyValueConstraints(t *testing.T)
 	}
 }
 
+func TestStateAssignmentMustSatisfyEveryTargetCondition(t *testing.T) {
+	assignment := literalAssignment("delivery", string(model.DeliveryPublished))
+	transition := Transition{
+		TargetConditions: []FacetCondition{
+			{Facet: model.FacetDelivery, Statuses: []model.FactStatus{model.FactKnown}, Values: []string{string(model.DeliveryPublished)}},
+			{Facet: model.FacetDelivery, Statuses: []model.FactStatus{model.FactKnown}, Values: []string{string(model.DeliveryTerminal)}},
+		},
+	}
+	if stateAssignmentMatchesTarget(transition, assignment) {
+		t.Fatal("assignment matched only the first of two target conditions")
+	}
+}
+
 func closureTransition(source FacetCondition, assignments ...StateAssignment) Transition {
 	transition := Transition{
 		ID: "test.transition", SourcePhases: []model.ProtocolPhase{model.PhaseActive}, TargetPhases: []model.ProtocolPhase{model.PhaseActive},

boatstack/internal/softwaredelivery/catalog/state_facet.go

@@ -157,6 +157,26 @@ func DurableStateFacetPolicy(transition Transition) (StateFacetPolicy, error) {
 	return StateFacetPolicy{Reads: append([]model.StateFacet(nil), allStateFacets...), Writes: writes}, nil
 }
 
+// RecoveryStateFacets reconstructs the interrupted transition's write envelope
+// from admission-bound capability identity. Privileged core facets remain
+// closed over the fixed transition IDs that own them; repository-authored
+// programs can recover only control and admitted product mutations.
+func RecoveryStateFacets(id TransitionID, required []Capability) []model.StateFacet {
+	switch id {
+	case "runtime.hydrate", "runtime.replace", "runtime.reconcile", "installation.update":
+		return []model.StateFacet{model.StateFacetControl, model.StateFacetInstallation}
+	case "installation.initialize", "installation.reconcile-update":
+		return []model.StateFacet{model.StateFacetControl, model.StateFacetInstallation, model.StateFacetProgram}
+	case "repository.attach", "catalog.reconcile":
+		return []model.StateFacet{model.StateFacetControl, model.StateFacetProgram}
+	}
+	writes := []model.StateFacet{model.StateFacetControl}
+	if NewCapabilitySet(required...).ContainsAll([]Capability{CapabilityProductMutate}) {
+		writes = append(writes, model.StateFacetProduct)
+	}
+	return writes
+}
+
 func containsStateFacet(values []model.StateFacet, wanted model.StateFacet) bool {
 	for _, value := range values {
 		if value == wanted {

boatstack/internal/softwaredelivery/catalog/transition.go

@@ -858,22 +858,35 @@ func stateAssignmentMatchesTarget(t Transition, assignment StateAssignment) bool
 		if target.Facet != facet {
 			continue
 		}
-		if len(target.Statuses) != 1 || target.Statuses[0] != model.FactKnown {
+		if !containsFactStatus(target.Statuses, model.FactKnown) {
 			return false
 		}
 		if len(target.Values) == 0 {
-			return true
+			continue
 		}
+		matched := false
 		for _, value := range target.Values {
 			if value == *assignment.Value {
-				return true
+				matched = true
+				break
 			}
 		}
-		return false
+		if !matched {
+			return false
+		}
 	}
 	return true
 }
 
+func containsFactStatus(values []model.FactStatus, wanted model.FactStatus) bool {
+	for _, value := range values {
+		if value == wanted {
+			return true
+		}
+	}
+	return false
+}
+
 func cloneConditions(values []FacetCondition) []FacetCondition {
 	result := make([]FacetCondition, len(values))
 	for index, value := range values {

boatstack/internal/softwaredelivery/effects/cas_integration_test.go

@@ -141,7 +141,8 @@ func TestConcurrentApplyConsumesOneRevisionExactlyOnce(t *testing.T) {
 		t.Fatalf("canonical committed journal count=%d err=%v", len(committedJournals), err)
 	}
 	committedRaw, err := os.ReadFile(committedJournals[0])
-	if err != nil || !bytes.Contains(committedRaw, []byte(committed.Receipt.ID)) || !bytes.Contains(committedRaw, []byte("committed_effects")) {
+	if err != nil || !bytes.Contains(committedRaw, []byte(committed.Receipt.ID)) || !bytes.Contains(committedRaw, []byte("committed_effects")) ||
+		!bytes.Contains(committedRaw, []byte(`"schema_version": 8`)) || !bytes.Contains(committedRaw, []byte(`"allowed_state_facets"`)) {
 		t.Fatalf("committed journal lacks its complete transition fact: %v %q", err, committedRaw)
 	}
 	// Simulate a crash after canonical commit but before the passive receipt

boatstack/internal/softwaredelivery/effects/journal.go

@@ -33,10 +33,12 @@ func NewJournal(resolver ports.InvocationResolver, clock ports.Clock) (*Journal,
 }
 
 type journalRecord struct {
-	SchemaVersion      int                         `json:"schema_version"`
-	Admission          protocol.Admission          `json:"admission"`
-	TransitionID       catalog.TransitionID        `json:"transition_id"`
-	TransitionClass    catalog.EventClass          `json:"transition_class"`
+	SchemaVersion   int                  `json:"schema_version"`
+	Admission       protocol.Admission   `json:"admission"`
+	TransitionID    catalog.TransitionID `json:"transition_id"`
+	TransitionClass catalog.EventClass   `json:"transition_class"`
+	// AllowedStateFacets preserves the current schema-8 record shape. Recovery
+	// authority is reconstructed from Admission.RequiredCapabilities instead.
 	AllowedStateFacets []model.StateFacet          `json:"allowed_state_facets"`
 	ReconcilesProgram  bool                        `json:"reconciles_program,omitempty"`
 	Status             string                      `json:"status"`

boatstack/internal/softwaredelivery/effects/journal_schema_test.go

@@ -1,27 +1,13 @@
 package effects
 
 import (
-	"os"
-	"path/filepath"
-	"strings"
 	"testing"
-)
 
-func TestPriorJournalSchemaRequiresExplicitReset(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "adm-prior.pending")
-	raw := []byte(`{"schema_version":7,"admission":{"id":"adm-prior"},"transition_id":"plan.create","transition_class":"owned-local","status":"begun"}`)
-	if err := os.WriteFile(path, raw, 0o600); err != nil {
-		t.Fatal(err)
-	}
+	"github.com/operatorstack/boatstack/boatstack/internal/softwaredelivery/protocol"
+)
 
-	if _, err := readJournal(path); err == nil || !strings.Contains(err.Error(), "invalid transaction journal") {
-		t.Fatalf("read prior journal schema error = %v, want explicit invalid journal refusal", err)
-	}
-	got, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if string(got) != string(raw) {
-		t.Fatalf("prior journal changed during refusal:\n got %s\nwant %s", got, raw)
+func TestInstallationUpdateKeepsCurrentJournalSchema(t *testing.T) {
+	if protocol.JournalSchemaVersion != 8 {
+		t.Fatalf("journal schema = %d, want current schema 8 for in-flight installation updates", protocol.JournalSchemaVersion)
 	}
 }

boatstack/internal/softwaredelivery/effects/recovery.go

@@ -147,7 +147,7 @@ func recoveryStateFacets(record journalRecord, recovery catalog.TransitionID, in
 	if err != nil {
 		return nil, err
 	}
-	allowed := model.UnionStateFacets(record.AllowedStateFacets, []model.StateFacet{model.StateFacetControl})
+	allowed := catalog.RecoveryStateFacets(record.TransitionID, record.Admission.RequiredCapabilities)
 	if _, err := validateAllowedStateFacets(recovery, staged, allowed); err != nil {
 		return nil, err
 	}