GEN2-008: promote experience and episode projections

contracts/epistemics/freshness.go

@@ -0,0 +1,90 @@
+package epistemics
+
+import (
+	"fmt"
+	"git.cin.su/m/Assistant/contracts/world"
+)
+
+type VolatilityMode string
+
+const (
+	VolatilityImmutable    VolatilityMode = "IMMUTABLE"
+	VolatilityVersionBound VolatilityMode = "VERSION_BOUND"
+	VolatilityVerySlow     VolatilityMode = "VERY_SLOW"
+	VolatilitySlow         VolatilityMode = "SLOW"
+	VolatilityMedium       VolatilityMode = "MEDIUM"
+	VolatilityFast         VolatilityMode = "FAST"
+	VolatilityEphemeral    VolatilityMode = "EPHEMERAL"
+	VolatilityCustom       VolatilityMode = "CUSTOM"
+)
+
+type TemporalApplicability struct {
+	ObservedAtUnixMillis     int64
+	ValidFromUnixMillis      *int64
+	ValidUntilUnixMillis     *int64
+	LastVerifiedAtUnixMillis *int64
+	Volatility               VolatilitySpec
+	VersionBindings          []world.VersionBinding
+}
+type VolatilitySpec struct {
+	Mode                         VolatilityMode
+	ExpectedChangeIntervalMillis *int64
+	RevalidateAfterMillis        *int64
+	HardStaleAfterMillis         *int64
+	InvalidateOnVersionChange    bool
+	RevalidationPolicyRef        string
+}
+type FreshnessAssessmentState string
+
+const (
+	FreshnessAssessmentCurrent         FreshnessAssessmentState = "CURRENT"
+	FreshnessAssessmentAcceptable      FreshnessAssessmentState = "ACCEPTABLE"
+	FreshnessAssessmentAging           FreshnessAssessmentState = "AGING"
+	FreshnessAssessmentStale           FreshnessAssessmentState = "STALE"
+	FreshnessAssessmentVersionMismatch FreshnessAssessmentState = "VERSION_MISMATCH"
+	FreshnessAssessmentHistoricalOnly  FreshnessAssessmentState = "HISTORICAL_ONLY"
+	FreshnessAssessmentUnknown         FreshnessAssessmentState = "UNKNOWN"
+)
+
+type FreshnessAssessment struct {
+	SourceKnowledgeRef     string
+	TaskRef                string
+	State                  FreshnessAssessmentState
+	Reason                 string
+	AgeMillis              int64
+	VersionMatchState      string
+	RevalidationAttemptRef string
+	AssessedAtUnixMillis   int64
+}
+type RevalidationRequest struct {
+	ID                    string
+	SourceKnowledgeRef    string
+	TaskRef               string
+	RequiredVersionRefs   []world.SemanticReference
+	RequestedAtUnixMillis int64
+}
+type RevalidationResponse struct {
+	RequestID             string
+	Assessment            FreshnessAssessment
+	NewEvidenceRefs       []EvidenceRef
+	CompletedAtUnixMillis int64
+}
+
+func (v VolatilitySpec) Validate() error {
+	if v.Mode == "" {
+		return fmt.Errorf("volatility mode is required")
+	}
+	return nil
+}
+func (t TemporalApplicability) Validate() error {
+	if t.ObservedAtUnixMillis < 1 {
+		return fmt.Errorf("observed time is required")
+	}
+	return t.Volatility.Validate()
+}
+func (a FreshnessAssessment) Validate() error {
+	if a.SourceKnowledgeRef == "" || a.TaskRef == "" || a.State == "" || a.AgeMillis < 0 || a.AssessedAtUnixMillis < 1 {
+		return fmt.Errorf("freshness assessment is incomplete")
+	}
+	return nil
+}

contracts/epistemics/truth.go

@@ -1,5 +1,7 @@
 package epistemics
 
+import "git.cin.su/m/Assistant/platform/ids"
+
 type BeliefState string
 
 const (
@@ -9,19 +11,27 @@ const (
 )
 
 type Observation struct {
-	ID             ObservationID
-	SourceSnapshot SourceSnapshotID
-	Excerpt        SourceExcerptID
-	Text           string
-	ObservedAt     int64
+	ID              ObservationID
+	SourceSnapshot  SourceSnapshotID
+	Excerpt         SourceExcerptID
+	Text            string
+	ObservedAt      int64
+	PrincipalID     string
+	ContextScopeRef string
+	ObservationKind string
+	Payload         string
+	ExtractorRef    string
 }
 
 type Claim struct {
-	ID            ClaimID
-	Statement     string
-	ObservationID ObservationID
-	CitationID    CitationID
-	Verification  VerificationState
+	ID                   ClaimID
+	Statement            string
+	ObservationID        ObservationID
+	CitationID           CitationID
+	Verification         VerificationState
+	PropositionID        ids.ID
+	RevisedFrom          *ClaimID
+	RecordedAtUnixMillis int64
 }
 
 type Belief struct {

contracts/epistemics/types.go

@@ -24,6 +24,8 @@ type HelpMethodKind string
 type OutcomeClass string
 type ReflectionTriggerKind string
 type ReflectionCandidateState string
+type PropositionKind string
+type BeliefAssessmentState string
 
 const (
 	VerificationUnverified    VerificationState = "UNVERIFIED"
@@ -73,6 +75,12 @@ const (
 	ReflectionCandidateEvaluating ReflectionCandidateState = "EVALUATING"
 	ReflectionCandidateSuperseded ReflectionCandidateState = "SUPERSEDED"
 	ReflectionCandidateResolved   ReflectionCandidateState = "RESOLVED"
+	PropositionWorldFacet         PropositionKind          = "WORLD_FACET"
+	PropositionWorldRelation      PropositionKind          = "WORLD_RELATION"
+	PropositionOwnerDefined       PropositionKind          = "OWNER_DEFINED"
+	PropositionTextual            PropositionKind          = "TEXTUAL"
+	BeliefAssessmentCurrent       BeliefAssessmentState    = "CURRENT"
+	BeliefAssessmentSuperseded    BeliefAssessmentState    = "SUPERSEDED"
 )
 
 // SystemExpectation records what Domovoy expected a meaningful help path to
@@ -114,6 +122,15 @@ type ExperienceRecord struct {
 	VerificationEvidence          []EvidenceRef
 	ConfidenceMillis              int64
 	RecordedAtUnixMillis          int64
+	ProblemStatement              string
+	AttemptRef                    string
+	WhyAttempted                  string
+	ApplicabilityConditions       []string
+	ContextScopeRef               string
+	EpisodeRef                    string
+	GoalRef                       string
+	TaskRef                       string
+	WhySucceededOrFailed          string
 }
 
 // ReflectionCandidate records that broader reflection may be warranted.
@@ -134,3 +151,34 @@ type ReflectionCandidate struct {
 	ClaimedBy                string
 	ClaimExpiresAtUnixMillis int64
 }
+
+type Proposition struct {
+	ID           ids.ID
+	Kind         PropositionKind
+	SubjectRef   string
+	PredicateRef string
+	ObjectValue  string
+	ObjectRef    string
+	Qualifiers   []string
+	TextFallback string
+}
+
+type BeliefAssessment struct {
+	ID                   ids.ID
+	ClaimID              ClaimID
+	Revision             ids.Revision
+	State                BeliefAssessmentState
+	ConfidenceMillis     int64
+	EvidenceRefs         []EvidenceRef
+	AssessedAtUnixMillis int64
+}
+
+type EpisodeID ids.ID
+type Episode struct {
+	ID                   EpisodeID
+	PrincipalID          string
+	ExperienceRefs       []ExperienceRecordID
+	Summary              string
+	Outcome              OutcomeClass
+	RecordedAtUnixMillis int64
+}

contracts/work/freshness.go

@@ -0,0 +1,28 @@
+package work
+
+import "git.cin.su/m/Assistant/contracts/world"
+
+type FreshnessRequirementMode string
+type FreshnessFallbackPolicy string
+
+const (
+	FreshnessAny                 FreshnessRequirementMode = "ANY"
+	FreshnessPreferCurrent       FreshnessRequirementMode = "PREFER_CURRENT"
+	FreshnessRequireCurrent      FreshnessRequirementMode = "REQUIRE_CURRENT"
+	FreshnessRequireWithinAge    FreshnessRequirementMode = "REQUIRE_WITHIN_AGE"
+	FreshnessRequireVersionMatch FreshnessRequirementMode = "REQUIRE_VERSION_MATCH"
+	FreshnessLiveRequired        FreshnessRequirementMode = "LIVE_REQUIRED"
+	FallbackAllowStaleDisclosure FreshnessFallbackPolicy  = "ALLOW_STALE_WITH_DISCLOSURE"
+	FallbackHypothesisOnly       FreshnessFallbackPolicy  = "USE_AS_HYPOTHESIS_ONLY"
+	FallbackWaitForSource        FreshnessFallbackPolicy  = "WAIT_FOR_SOURCE"
+	FallbackAskOwner             FreshnessFallbackPolicy  = "ASK_OWNER"
+	FallbackStopUnknown          FreshnessFallbackPolicy  = "STOP_WITH_UNKNOWN"
+)
+
+type TaskFreshnessRequirement struct {
+	Mode                 FreshnessRequirementMode
+	MaximumAgeMillis     *int64
+	RequiredVersionRefs  []world.SemanticReference
+	RevalidationRequired bool
+	FallbackPolicy       FreshnessFallbackPolicy
+}

contracts/world/primitives.go

@@ -12,6 +12,48 @@ import (
 // a reference only; it does not expose another owner's storage.
 type SemanticReference = ids.SemanticRef
 
+// VersionBinding is a typed applicability constraint. Absence of VersionRef
+// means unknown, never an implicit "latest".
+type VersionMatchMode string
+
+const (
+	VersionExact            VersionMatchMode = "EXACT"
+	VersionCompatibleFamily VersionMatchMode = "COMPATIBLE_FAMILY"
+	VersionAtOrBefore       VersionMatchMode = "AT_OR_BEFORE"
+	VersionUnknown          VersionMatchMode = "UNKNOWN"
+)
+
+type VersionBinding struct {
+	SubjectRef SemanticReference
+	VersionRef SemanticReference
+	MatchMode  VersionMatchMode
+}
+
+type EnvironmentReference struct {
+	EnvironmentRef SemanticReference
+	VersionRef     *SemanticReference
+}
+
+func (b VersionBinding) Validate() error {
+	if !b.SubjectRef.Valid() || !b.VersionRef.Valid() {
+		return fmt.Errorf("version binding references are invalid")
+	}
+	if b.MatchMode != VersionExact && b.MatchMode != VersionCompatibleFamily && b.MatchMode != VersionAtOrBefore && b.MatchMode != VersionUnknown {
+		return fmt.Errorf("version binding match mode is invalid")
+	}
+	return nil
+}
+
+func (r EnvironmentReference) Validate() error {
+	if !r.EnvironmentRef.Valid() {
+		return fmt.Errorf("environment reference is invalid")
+	}
+	if r.VersionRef != nil && !r.VersionRef.Valid() {
+		return fmt.Errorf("environment version reference is invalid")
+	}
+	return nil
+}
+
 type PrincipalRealm string
 
 const (

dev/ACTIVE_TASK.json

@@ -1 +1 @@
-{"task_file":"dev/tasks/GEN2-004-replace-project-centric-focus-with-contextscope-focusframe-focusstack.json","task_id":"GEN2-004","task_revision":1}
+{"task_file":"dev/tasks/GEN2-008-promote-episode-and-experience-v2-including-negative-experience.json","task_id":"GEN2-008","task_revision":1}

modules/epistemics/domain/episode.go

@@ -0,0 +1,29 @@
+package domain
+
+import (
+	"git.cin.su/m/Assistant/contracts/epistemics"
+	"git.cin.su/m/Assistant/platform/ids"
+	"strings"
+)
+
+func BuildEpisode(experiences []epistemics.ExperienceRecord, summary string, at int64) (epistemics.Episode, error) {
+	if len(experiences) == 0 || strings.TrimSpace(summary) == "" || at < 1 {
+		return epistemics.Episode{}, ErrInvalidExperience
+	}
+	refs := make([]epistemics.ExperienceRecordID, 0, len(experiences))
+	outcome := epistemics.OutcomeUnknown
+	for _, e := range experiences {
+		if _, err := NewExperienceRecord(e); err != nil {
+			return epistemics.Episode{}, err
+		}
+		refs = append(refs, e.ID)
+		if e.ActualOutcome != epistemics.OutcomeSuccess {
+			outcome = e.ActualOutcome
+		}
+	}
+	id, err := ids.New()
+	if err != nil {
+		return epistemics.Episode{}, err
+	}
+	return epistemics.Episode{ID: epistemics.EpisodeID(id), ExperienceRefs: refs, Summary: summary, Outcome: outcome, RecordedAtUnixMillis: at}, nil
+}

modules/epistemics/domain/episode_test.go

@@ -0,0 +1,15 @@
+package domain_test
+
+import (
+	"git.cin.su/m/Assistant/contracts/epistemics"
+	"git.cin.su/m/Assistant/modules/epistemics/domain"
+	"testing"
+)
+
+func TestEpisodeIsRebuildableFromExperience(t *testing.T) {
+	e := epistemics.ExperienceRecord{ID: "e", SourceKind: epistemics.ExperienceSourceInteraction, OriginalIntentID: "i", SourceUtteranceID: "u", HelpMethod: epistemics.HelpMethodFallback, ExpectedOutcome: epistemics.OutcomeSuccess, ActualOutcome: epistemics.OutcomeFailed, RecordedAtUnixMillis: 1}
+	ep, err := domain.BuildEpisode([]epistemics.ExperienceRecord{e}, "failed attempt", 1)
+	if err != nil || len(ep.ExperienceRefs) != 1 || ep.Outcome != epistemics.OutcomeFailed {
+		t.Fatalf("episode=%#v err=%v", ep, err)
+	}
+}

modules/epistemics/domain/freshness.go

@@ -0,0 +1,30 @@
+package domain
+
+import "git.cin.su/m/Assistant/contracts/epistemics"
+
+// AssessFreshness receives the Work-owned requirement as primitive policy
+// inputs, keeping the Epistemics owner independent of Work package types.
+func AssessFreshness(applicability epistemics.TemporalApplicability, mode string, maximumAgeMillis *int64, nowMillis int64) epistemics.FreshnessAssessment {
+	age := nowMillis - applicability.ObservedAtUnixMillis
+	if age < 0 {
+		age = 0
+	}
+	state := epistemics.FreshnessAssessmentCurrent
+	reason := "observation is within applicability window"
+	if applicability.ValidUntilUnixMillis != nil && nowMillis > *applicability.ValidUntilUnixMillis {
+		state, reason = epistemics.FreshnessAssessmentStale, "valid-until elapsed"
+	}
+	if applicability.Volatility.HardStaleAfterMillis != nil && age > *applicability.Volatility.HardStaleAfterMillis {
+		state, reason = epistemics.FreshnessAssessmentStale, "hard volatility window elapsed"
+	}
+	if applicability.Volatility.RevalidateAfterMillis != nil && age > *applicability.Volatility.RevalidateAfterMillis && state == epistemics.FreshnessAssessmentCurrent {
+		state, reason = epistemics.FreshnessAssessmentAging, "revalidation window elapsed"
+	}
+	if maximumAgeMillis != nil && age > *maximumAgeMillis {
+		state, reason = epistemics.FreshnessAssessmentStale, "task maximum age exceeded"
+	}
+	if mode == "LIVE_REQUIRED" {
+		state, reason = epistemics.FreshnessAssessmentHistoricalOnly, "live source required"
+	}
+	return epistemics.FreshnessAssessment{SourceKnowledgeRef: "knowledge", TaskRef: "task", State: state, Reason: reason, AgeMillis: age, AssessedAtUnixMillis: nowMillis}
+}

modules/epistemics/domain/freshness_test.go

@@ -0,0 +1,17 @@
+package domain_test
+
+import (
+	"git.cin.su/m/Assistant/contracts/epistemics"
+	"git.cin.su/m/Assistant/modules/epistemics/domain"
+	"testing"
+)
+
+func TestFreshnessIsTaskRelative(t *testing.T) {
+	hard := int64(100)
+	app := epistemics.TemporalApplicability{ObservedAtUnixMillis: 1, Volatility: epistemics.VolatilitySpec{Mode: epistemics.VolatilityVersionBound, HardStaleAfterMillis: &hard}}
+	current := domain.AssessFreshness(app, "ANY", nil, 50)
+	historical := domain.AssessFreshness(app, "LIVE_REQUIRED", nil, 50)
+	if current.State != epistemics.FreshnessAssessmentCurrent || historical.State != epistemics.FreshnessAssessmentHistoricalOnly {
+		t.Fatalf("got %v and %v", current.State, historical.State)
+	}
+}

modules/epistemics/domain/knowledge_v2.go

@@ -0,0 +1,36 @@
+package domain
+
+import (
+	"errors"
+	"git.cin.su/m/Assistant/contracts/epistemics"
+	"git.cin.su/m/Assistant/platform/ids"
+	"strings"
+)
+
+var ErrInvalidKnowledge = errors.New("invalid epistemic knowledge record")
+
+func ValidateProposition(value epistemics.Proposition) error {
+	if value.ID == "" || value.Kind == "" || strings.TrimSpace(value.SubjectRef) == "" || (value.ObjectValue == "" && value.ObjectRef == "" && value.TextFallback == "") {
+		return ErrInvalidKnowledge
+	}
+	return nil
+}
+
+func ValidateBeliefAssessment(value epistemics.BeliefAssessment) error {
+	if value.ID == "" || value.ClaimID == "" || !value.Revision.Valid() || value.State == "" || value.ConfidenceMillis < 0 || value.ConfidenceMillis > 1000 || value.AssessedAtUnixMillis < 1 {
+		return ErrInvalidKnowledge
+	}
+	return nil
+}
+
+func NewBeliefAssessment(claim epistemics.ClaimID, confidence int64, state epistemics.BeliefAssessmentState, evidence []epistemics.EvidenceRef, at int64) (epistemics.BeliefAssessment, error) {
+	id, err := ids.New()
+	if err != nil {
+		return epistemics.BeliefAssessment{}, err
+	}
+	value := epistemics.BeliefAssessment{ID: id, ClaimID: claim, Revision: ids.InitialRevision, State: state, ConfidenceMillis: confidence, EvidenceRefs: append([]epistemics.EvidenceRef(nil), evidence...), AssessedAtUnixMillis: at}
+	if err := ValidateBeliefAssessment(value); err != nil {
+		return epistemics.BeliefAssessment{}, err
+	}
+	return value, nil
+}

modules/epistemics/domain/knowledge_v2_test.go

@@ -0,0 +1,22 @@
+package domain_test
+
+import (
+	"git.cin.su/m/Assistant/contracts/epistemics"
+	"git.cin.su/m/Assistant/modules/epistemics/domain"
+	"testing"
+)
+
+func TestKnowledgeV2SeparatesPropositionAndReassessableBelief(t *testing.T) {
+	p := epistemics.Proposition{ID: "p", Kind: epistemics.PropositionWorldFacet, SubjectRef: "world:database:a", ObjectValue: "1.6.28"}
+	if err := domain.ValidateProposition(p); err != nil {
+		t.Fatal(err)
+	}
+	a, err := domain.NewBeliefAssessment("claim:a", 800, epistemics.BeliefAssessmentCurrent, []epistemics.EvidenceRef{"observation:a"}, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Revision++
+	if err := domain.ValidateBeliefAssessment(a); err != nil {
+		t.Fatal(err)
+	}
+}

modules/world/domain/resolution_test.go

@@ -0,0 +1,30 @@
+package domain_test
+
+import (
+	"testing"
+
+	"git.cin.su/m/Assistant/contracts/world"
+	"git.cin.su/m/Assistant/modules/world/domain"
+)
+
+func TestResolveCandidatesDoesNotAutoMergeAmbiguousPeopleOrSystems(t *testing.T) {
+	decision, candidates := domain.ResolveCandidates([]world.IdentityResolutionCandidate{
+		{ObjectRef: world.SemanticReference{OwnerNamespace: "world", SemanticKind: "person", StableID: "ivan-telegram"}, Confidence: 800},
+		{ObjectRef: world.SemanticReference{OwnerNamespace: "world", SemanticKind: "person", StableID: "ivan-crm"}, Confidence: 800},
+	}, 700)
+	if decision != world.ResolutionUnresolved || len(candidates) != 2 {
+		t.Fatalf("ambiguous result = %s, %#v", decision, candidates)
+	}
+}
+
+func TestVersionAndEnvironmentReferencesAreTyped(t *testing.T) {
+	version := world.SemanticReference{OwnerNamespace: "world", SemanticKind: "version", StableID: "unf-3"}
+	binding := world.VersionBinding{SubjectRef: world.SemanticReference{OwnerNamespace: "world", SemanticKind: "database", StableID: "company-a-unf"}, VersionRef: version, MatchMode: world.VersionExact}
+	if err := binding.Validate(); err != nil {
+		t.Fatal(err)
+	}
+	environment := world.EnvironmentReference{EnvironmentRef: world.SemanticReference{OwnerNamespace: "world", SemanticKind: "environment", StableID: "company-a-prod"}, VersionRef: &version}
+	if err := environment.Validate(); err != nil {
+		t.Fatal(err)
+	}
+}

modules/world/domain/world.go

@@ -2,6 +2,8 @@ package domain
 
 import "git.cin.su/m/Assistant/contracts/world"
 
+import "sort"
+
 func ValidateObject(value world.WorldObject) error { return value.Validate() }
 
 func ValidateKindDefinition(value world.WorldObjectKindDefinition) error { return value.Validate() }
@@ -15,3 +17,18 @@ func ValidateRelationDefinition(value world.RelationDefinition) error { return v
 func ValidateResolution(value world.IdentityResolutionDecisionRecord) error { return value.Validate() }
 
 func ValidateLineage(value world.WorldLineage) error { return value.Validate() }
+
+// ResolveCandidates deliberately refuses to merge an ambiguous result. A
+// caller may persist the returned UNRESOLVED decision and later re-evaluate it
+// with additional evidence.
+func ResolveCandidates(candidates []world.IdentityResolutionCandidate, minimumConfidence int64) (world.ResolutionDecision, []world.IdentityResolutionCandidate) {
+	ordered := append([]world.IdentityResolutionCandidate(nil), candidates...)
+	sort.SliceStable(ordered, func(i, j int) bool { return ordered[i].Confidence > ordered[j].Confidence })
+	if len(ordered) == 0 || ordered[0].Confidence < minimumConfidence {
+		return world.ResolutionUnresolved, ordered
+	}
+	if len(ordered) > 1 && ordered[0].Confidence == ordered[1].Confidence {
+		return world.ResolutionUnresolved, ordered
+	}
+	return world.ResolutionSame, ordered[:1]
+}