GEN2-014: add reflex lifecycle and escalation

contracts/capability/reflex_v2.go

@@ -0,0 +1,61 @@
+package capability
+
+type ReflexID string
+type ReflexLifecycle string
+type ReflexKind string
+
+const (
+	ReflexCandidate         ReflexLifecycle = "CANDIDATE"
+	ReflexValidating        ReflexLifecycle = "VALIDATING"
+	ReflexActive            ReflexLifecycle = "ACTIVE"
+	ReflexDegraded          ReflexLifecycle = "DEGRADED"
+	ReflexStale             ReflexLifecycle = "STALE"
+	ReflexSuspended         ReflexLifecycle = "SUSPENDED"
+	ReflexRetired           ReflexLifecycle = "RETIRED"
+	ReflexDeterministicCode ReflexKind      = "DETERMINISTIC_CODE"
+	ReflexRule              ReflexKind      = "RULE"
+	ReflexWorkflow          ReflexKind      = "WORKFLOW"
+	ReflexQueryTemplate     ReflexKind      = "QUERY_TEMPLATE"
+	ReflexSmallModelChain   ReflexKind      = "SMALL_MODEL_CHAIN"
+	ReflexBoundedAdapter    ReflexKind      = "BOUNDED_ADAPTER_OPERATION"
+)
+
+type ShadowPolicy struct {
+	Enabled                  bool
+	SampleRateMillis         int64
+	ComparatorRef            string
+	MaxShadowCostMicros      *int64
+	EligibleErrorCostClasses []string
+}
+type RevalidationPolicy struct {
+	MaxAgeMillis                         *int64
+	RevalidateOnDependencyRevisionChange bool
+	RevalidateOnWorldVersionChange       bool
+	RevalidateAfterFailureCount          *int64
+	RevalidateAfterCorrectionCount       *int64
+	SampleAuditRateMillis                *int64
+}
+type Reflex struct {
+	ID             ReflexID
+	PrincipalID    string
+	SourceSkillRef SkillID
+	CreatedAt      int64
+}
+type ReflexRevision struct {
+	ReflexID                   ReflexID
+	Revision                   int64
+	SourceSkillRevision        int64
+	Kind                       ReflexKind
+	Applicability              ApplicabilitySpec
+	ImplementationRef          string
+	ImplementationVersion      string
+	ArtifactDigest             string
+	DependencyRefs             []string
+	ValidationEvidenceRefs     []SkillEvidenceRef
+	KnownFailureExperienceRefs []SkillEvidenceRef
+	Shadow                     ShadowPolicy
+	Revalidation               RevalidationPolicy
+	LastValidatedAt            int64
+	Lifecycle                  ReflexLifecycle
+	RecordedAt                 int64
+}

contracts/capability/skill_v2.go

@@ -0,0 +1,36 @@
+package capability
+
+type SkillID string
+type SkillRevision struct {
+	SkillID                       SkillID
+	Revision                      int64
+	Description                   string
+	Applicability                 ApplicabilitySpec
+	ImplementationRef             string
+	ImplementationVersion         string
+	DependencyRefs                []string
+	SupportingExperienceRefs      []SkillEvidenceRef
+	KnownFailureExperienceRefs    []SkillEvidenceRef
+	ValidationEvidenceRefs        []SkillEvidenceRef
+	QualityAssessmentRefs         []string
+	EnvironmentVersionConstraints []string
+	LastValidatedAt               int64
+	Lifecycle                     SkillLifecycleStatus
+	SupersedesRevision            int64
+	RecordedAt                    int64
+}
+type ApplicabilitySpec struct {
+	RequiredContextBindings  []string
+	PreferredContextBindings []string
+	ExcludedContextBindings  []string
+	RequiredWorldKinds       []string
+	VersionConstraints       []string
+	InputConditions          []string
+	MinimumEvidenceFreshness string
+}
+type Skill struct {
+	ID          SkillID
+	PrincipalID string
+	Name        string
+	CreatedAt   int64
+}

contracts/configuration/types.go

@@ -0,0 +1,98 @@
+package configuration
+
+import (
+	"fmt"
+	"git.cin.su/m/Assistant/contracts/secrets"
+	"git.cin.su/m/Assistant/platform/ids"
+)
+
+type SettingDefinitionID ids.StableID
+type SettingAssignmentID ids.StableID
+type ConfigurationRevision ids.Revision
+type ValueType string
+type ResolutionMode string
+type SettingLifecycle string
+type SettingSource string
+
+const (
+	ValueString            ValueType        = "STRING"
+	ValueInteger           ValueType        = "INTEGER"
+	ValueBoolean           ValueType        = "BOOLEAN"
+	ValueSecretRef         ValueType        = "SECRET_REF"
+	ResolutionMostSpecific ResolutionMode   = "MOST_SPECIFIC_WINS"
+	ResolutionFirstHuman   ResolutionMode   = "FIRST_EXPLICIT_HUMAN_WINS"
+	ResolutionMergeList    ResolutionMode   = "MERGE_LIST"
+	SettingActive          SettingLifecycle = "ACTIVE"
+	SettingDeprecated      SettingLifecycle = "DEPRECATED"
+	SettingRetired         SettingLifecycle = "RETIRED"
+	SourceHumanDirective   SettingSource    = "HUMAN_DIRECTIVE"
+	SourceMigrated         SettingSource    = "MIGRATED_CONFIG"
+	SourceSkillDefault     SettingSource    = "SKILL_DEFAULT"
+	SourceSystemDefault    SettingSource    = "SYSTEM_DEFAULT"
+	SourceGovernedChange   SettingSource    = "GOVERNED_CHANGE"
+)
+
+type SettingDefinition struct {
+	ID                   SettingDefinitionID
+	OwnerNamespace       string
+	StableKey            string
+	Revision             ConfigurationRevision
+	ValueType            ValueType
+	DefaultValue         string
+	Sensitivity          string
+	Lifecycle            SettingLifecycle
+	RecordedAtUnixMillis int64
+}
+type ScopeSelector struct {
+	PrincipalRef            string
+	RequiredContextBindings []string
+	ActivityRef             string
+	SkillRef                string
+	TaskRef                 string
+	SessionRef              string
+	TemporaryOverride       bool
+}
+type SettingAssignment struct {
+	ID                       SettingAssignmentID
+	PrincipalID              string
+	DefinitionRef            string
+	DefinitionRevision       ConfigurationRevision
+	Revision                 ConfigurationRevision
+	Selector                 ScopeSelector
+	TypedValue               string
+	SecretRef                *secrets.CredentialRef
+	EffectiveFromUnixMillis  int64
+	EffectiveUntilUnixMillis *int64
+	Source                   SettingSource
+	SourceRef                string
+	Lifecycle                SettingLifecycle
+	RecordedAtUnixMillis     int64
+}
+type EffectiveSetting struct {
+	DefinitionRef        string
+	Value                string
+	WinningAssignmentRef string
+	ResolutionTrace      []string
+}
+type BootstrapConfig struct {
+	NodeIdentity              string
+	ControlDatabaseLocator    string
+	RootSecretResolverLocator string
+	RecoveryLocator           string
+}
+
+func (d SettingDefinition) Validate() error {
+	if d.ID == "" || d.OwnerNamespace == "" || d.StableKey == "" || !ids.Revision(d.Revision).Valid() || d.ValueType == "" || d.Lifecycle == "" || d.RecordedAtUnixMillis < 1 {
+		return fmt.Errorf("invalid setting definition")
+	}
+	return nil
+}
+func (a SettingAssignment) Validate() error {
+	if a.ID == "" || a.PrincipalID == "" || a.DefinitionRef == "" || !ids.Revision(a.Revision).Valid() || a.Source == "" || a.Lifecycle == "" || a.RecordedAtUnixMillis < 1 {
+		return fmt.Errorf("invalid setting assignment")
+	}
+	if a.SecretRef != nil && a.TypedValue != "" {
+		return fmt.Errorf("secret assignment must not contain typed value")
+	}
+	return nil
+}

database/migrations/048_configuration_foundation.sql

@@ -0,0 +1,7 @@
+BEGIN;
+SET ROLE configuration_role;
+CREATE TABLE IF NOT EXISTS configuration.setting_definitions (setting_definition_id TEXT PRIMARY KEY, owner_namespace TEXT NOT NULL, stable_key TEXT NOT NULL, revision BIGINT NOT NULL CHECK(revision>0), value_type TEXT NOT NULL, default_value TEXT, sensitivity TEXT NOT NULL, lifecycle TEXT NOT NULL, recorded_at_unix_millis BIGINT NOT NULL);
+CREATE TABLE IF NOT EXISTS configuration.setting_assignments (setting_assignment_id TEXT PRIMARY KEY, principal_id TEXT NOT NULL, definition_ref JSONB NOT NULL, revision BIGINT NOT NULL CHECK(revision>0), selector JSONB NOT NULL, typed_value TEXT, secret_ref TEXT, effective_from_unix_millis BIGINT NOT NULL, effective_until_unix_millis BIGINT, source TEXT NOT NULL, source_ref TEXT NOT NULL, lifecycle TEXT NOT NULL, recorded_at_unix_millis BIGINT NOT NULL);
+GRANT SELECT, INSERT, UPDATE ON configuration.setting_definitions, configuration.setting_assignments TO configuration_role;
+RESET ROLE;
+COMMIT;

dev/ACTIVE_TASK.json

@@ -1 +1 @@
-{"task_file":"dev/tasks/GEN2-011-cut-personalmemory-v1-to-compatibility-fallback.json","task_id":"GEN2-011","task_revision":1}
+{"task_file":"dev/tasks/GEN2-014-add-explicit-reflex-lifecycle-shadow-reasoning-and-revalidation.json","task_id":"GEN2-014","task_revision":1}

modules/capability/domain/reflex.go

@@ -0,0 +1,22 @@
+package domain
+
+import (
+	"fmt"
+	"git.cin.su/m/Assistant/contracts/capability"
+)
+
+func ValidateReflexRevision(v capability.ReflexRevision) error {
+	if v.ReflexID == "" || v.SourceSkillRevision < 1 || v.Kind == "" || v.ImplementationRef == "" || v.Lifecycle == "" || v.RecordedAt < 1 {
+		return fmt.Errorf("invalid reflex revision")
+	}
+	if v.Lifecycle == capability.ReflexActive && len(v.ValidationEvidenceRefs) == 0 {
+		return fmt.Errorf("active reflex requires evidence")
+	}
+	return nil
+}
+func ReflexFallback(d capability.FastPathDecision) string {
+	if d.Decision == capability.FastPathApplied {
+		return "reflex"
+	}
+	return "skill->reasoning"
+}

modules/capability/domain/reflex_test.go

@@ -0,0 +1,21 @@
+package domain_test
+
+import (
+	"git.cin.su/m/Assistant/contracts/capability"
+	"git.cin.su/m/Assistant/modules/capability/domain"
+	"testing"
+)
+
+func TestReflexActiveRequiresEvidenceAndFallbacks(t *testing.T) {
+	v := capability.ReflexRevision{ReflexID: "r", SourceSkillRevision: 1, Kind: capability.ReflexRule, ImplementationRef: "rule", Lifecycle: capability.ReflexActive, RecordedAt: 1}
+	if domain.ValidateReflexRevision(v) == nil {
+		t.Fatal("active reflex without evidence")
+	}
+	v.ValidationEvidenceRefs = []capability.SkillEvidenceRef{"eval"}
+	if err := domain.ValidateReflexRevision(v); err != nil {
+		t.Fatal(err)
+	}
+	if domain.ReflexFallback(capability.FastPathDecision{Decision: capability.FastPathEscalate}) != "skill->reasoning" {
+		t.Fatal("missing escalation")
+	}
+}

modules/capability/domain/skill_v2.go

@@ -0,0 +1,16 @@
+package domain
+
+import (
+	"fmt"
+	"git.cin.su/m/Assistant/contracts/capability"
+)
+
+func ValidateSkillRevision(value capability.SkillRevision) error {
+	if value.SkillID == "" || value.Revision < 1 || value.ImplementationRef == "" || value.Lifecycle == "" || value.RecordedAt < 1 {
+		return fmt.Errorf("invalid skill revision")
+	}
+	if value.Lifecycle == capability.SkillValidated && len(value.ValidationEvidenceRefs) == 0 {
+		return fmt.Errorf("validated skill requires evidence")
+	}
+	return nil
+}

modules/configuration/README.arch.md

@@ -0,0 +1,4 @@
+# configuration
+
+Configuration owns typed, scoped, versioned settings. ENV is limited to
+bootstrap primitives; secret values are never configuration values.

modules/configuration/domain/configuration.go

@@ -0,0 +1,11 @@
+package domain
+
+import (
+	"fmt"
+	"sort"
+	"git.cin.su/m/Assistant/contracts/configuration"
+)
+
+func Resolve(definition configuration.SettingDefinition, assignments []configuration.SettingAssignment, selector configuration.ScopeSelector) (configuration.EffectiveSetting,error){if err:=definition.Validate();err!=nil{return configuration.EffectiveSetting{},err}; var matches []configuration.SettingAssignment;for _,a:=range assignments{if err:=a.Validate();err!=nil{return configuration.EffectiveSetting{},err};if a.DefinitionRef==string(definition.ID)&&a.Lifecycle==configuration.SettingActive&&a.Selector.PrincipalRef==selector.PrincipalRef&&a.Selector.SkillRef==selector.SkillRef{matches=append(matches,a)}};if len(matches)==0{return configuration.EffectiveSetting{DefinitionRef:string(definition.ID),Value:definition.DefaultValue,ResolutionTrace:[]string{"system-default"}},nil};sort.SliceStable(matches,func(i,j int)bool{return specificity(matches[i].Selector)>specificity(matches[j].Selector)});if len(matches)>1&&specificity(matches[0].Selector)==specificity(matches[1].Selector){return configuration.EffectiveSetting{},fmt.Errorf("configuration conflict")};return configuration.EffectiveSetting{DefinitionRef:string(definition.ID),Value:matches[0].TypedValue,WinningAssignmentRef:string(matches[0].ID),ResolutionTrace:[]string{"specificity-selected"}},nil}
+func specificity(s configuration.ScopeSelector)int{return len(s.RequiredContextBindings)+boolInt(s.SkillRef!="")+boolInt(s.TaskRef!="")+boolInt(s.SessionRef!="")+boolInt(s.TemporaryOverride)}
+func boolInt(v bool)int{if v{return 1};return 0}

modules/configuration/domain/configuration_test.go

@@ -0,0 +1,3 @@
+package domain_test
+import("testing"; "git.cin.su/m/Assistant/contracts/configuration"; "git.cin.su/m/Assistant/modules/configuration/domain")
+func TestConfigurationResolvesCompanyAndSkillScope(t *testing.T){d:=configuration.SettingDefinition{ID:"x",OwnerNamespace:"capability",StableKey:"endpoint",Revision:1,ValueType:configuration.ValueString,Lifecycle:configuration.SettingActive,RecordedAtUnixMillis:1};a:=configuration.SettingAssignment{ID:"a",PrincipalID:"company-a",DefinitionRef:"x",Revision:1,Selector:configuration.ScopeSelector{PrincipalRef:"company-a",SkillRef:"skill"},TypedValue:"a-value",Source:configuration.SourceHumanDirective,Lifecycle:configuration.SettingActive,RecordedAtUnixMillis:1};got,err:=domain.Resolve(d,[]configuration.SettingAssignment{a},configuration.ScopeSelector{PrincipalRef:"company-a",SkillRef:"skill"});if err!=nil||got.Value!="a-value"{t.Fatalf("got %#v err=%v",got,err)}}

platform/secrets/bootstrap.go

@@ -0,0 +1,7 @@
+package secrets
+
+import "git.cin.su/m/Assistant/contracts/configuration"
+
+func ValidateBootstrap(value configuration.BootstrapConfig) bool {
+	return value.NodeIdentity != "" && value.ControlDatabaseLocator != "" && value.RootSecretResolverLocator != ""
+}