feat(epistemics): persist truth bundles with source provenance

Reviewed-on: #109

adapters/postgres/epistemics_repository.go

@@ -161,3 +161,21 @@ func (r *EpistemicsRepository) SaveReflectionCandidate(ctx context.Context, valu
 		value.Summary, value.EvidenceRefs, value.RequiresCognition, value.RecordedAtUnixMillis, value.Revision)
 	return err
 }
+
+func (r *EpistemicsRepository) SaveTruthBundle(ctx context.Context, value epistemics.TruthBundle, recordedAtUnixMillis int64) error {
+	if value.Source.ID == "" || value.Snapshot.ID == "" || value.Excerpt.ID == "" || value.Claim.ID == "" || value.Belief.ID == "" || value.Citation.ID == "" || recordedAtUnixMillis < 1 {
+		return fmt.Errorf("invalid truth bundle")
+	}
+	_, err := r.pool.Exec(ctx, `INSERT INTO epistemics.truth_bundles (
+		bundle_id,source_id,source_kind,source_locator,source_title,source_publisher,snapshot_id,snapshot_source_id,snapshot_content_digest,snapshot_captured_at_unix_millis,snapshot_freshness,
+		excerpt_id,excerpt_snapshot_id,excerpt_text,excerpt_start,excerpt_end,observation_id,observation_observed_at_unix_millis,claim_id,claim_statement,claim_observation_id,claim_citation_id,claim_verification,
+		belief_id,belief_claim_id,belief_state,citation_id,citation_excerpt_id,citation_evidence,citation_coverage,citation_conflict,citation_resolved_at_unix_millis,recorded_at_unix_millis)
+		VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24,$25,$26,$27,$28,$29,$30,$31,$32,$33)
+		ON CONFLICT (bundle_id) DO UPDATE SET recorded_at_unix_millis=EXCLUDED.recorded_at_unix_millis`,
+		"bundle:"+string(value.Citation.ID), value.Source.ID, value.Source.Kind, value.Source.Locator, value.Source.Title, value.Source.Publisher,
+		value.Snapshot.ID, value.Snapshot.SourceID, value.Snapshot.ContentDigest, value.Snapshot.CapturedAtUnixMillis, value.Snapshot.Freshness,
+		value.Excerpt.ID, value.Excerpt.SnapshotID, value.Excerpt.Text, value.Excerpt.Start, value.Excerpt.End,
+		value.Observation.ID, value.Observation.ObservedAt, value.Claim.ID, value.Claim.Statement, value.Claim.ObservationID, value.Claim.CitationID, value.Claim.Verification,
+		value.Belief.ID, value.Belief.ClaimID, value.Belief.State, value.Citation.ID, value.Citation.ExcerptID, value.Citation.Evidence, value.Citation.Coverage, value.Citation.Conflict, value.Citation.ResolvedAtUnixMillis, recordedAtUnixMillis)
+	return err
+}

cmd/cognitive-worker/main.go

@@ -76,9 +76,9 @@ func main() {
 	lifeboatURL := strings.TrimSuffix(strings.TrimRight(envOr("LOCAL_LIFEBOAT_PROVIDER_URL", "http://cognitive-lifeboat:8086/v1"), "/"), "/v1") + "/health"
 	mux.Handle("/readyz", health.ReadinessHandler{Runtime: "cognitive-worker", Probes: []health.Probe{
 		health.HTTPProbe(readinessClient, strings.TrimRight(envOr("CORE_RUNTIME_URL", "http://core-runtime:8080"), "/")+"/healthz"),
-		health.HTTPProbe(readinessClient, strings.TrimRight(envOr("LOCAL_CPU_PROVIDER_URL", "http://docker.cin.su:18082/v1"), "/")+"/models"),
+		health.OptionalHTTPProbe(readinessClient, strings.TrimRight(envOr("LOCAL_CPU_PROVIDER_URL", "http://docker.cin.su:18082/v1"), "/")+"/models"),
 		health.HTTPProbe(readinessClient, lifeboatURL),
-		health.HTTPProbe(readinessClient, strings.TrimRight(envOr("LOCAL_GPU_PROVIDER_URL", "http://192.168.220.91:11434"), "/")+"/api/tags"),
+		health.OptionalHTTPProbe(readinessClient, strings.TrimRight(envOr("LOCAL_GPU_PROVIDER_URL", "http://192.168.220.91:11434"), "/")+"/api/tags"),
 	}})
 	mux.HandleFunc("POST /v1/proposals/deterministic", deterministicProposal)
 	mux.HandleFunc("POST /v1/advisory-policy", gateway.policyHandler)

contracts/epistemics/truth.go

@@ -31,6 +31,9 @@ type Belief struct {
 }
 
 type TruthBundle struct {
+	Source      Source
+	Snapshot    SourceSnapshot
+	Excerpt     SourceExcerpt
 	Observation Observation
 	Claim       Claim
 	Belief      Belief

database/migrations/034_epistemics_truth_bundles.sql

@@ -0,0 +1,49 @@
+BEGIN;
+
+SET ROLE epistemics_role;
+
+CREATE TABLE IF NOT EXISTS epistemics.truth_bundles (
+  bundle_id TEXT PRIMARY KEY,
+  source_id TEXT NOT NULL,
+  source_kind TEXT NOT NULL,
+  source_locator TEXT NOT NULL,
+  source_title TEXT NOT NULL,
+  source_publisher TEXT NOT NULL,
+  snapshot_id TEXT NOT NULL,
+  snapshot_source_id TEXT NOT NULL,
+  snapshot_content_digest TEXT NOT NULL,
+  snapshot_captured_at_unix_millis BIGINT NOT NULL,
+  snapshot_freshness TEXT NOT NULL,
+  excerpt_id TEXT NOT NULL,
+  excerpt_snapshot_id TEXT NOT NULL,
+  excerpt_text TEXT NOT NULL,
+  excerpt_start BIGINT NOT NULL,
+  excerpt_end BIGINT NOT NULL,
+  observation_id TEXT NOT NULL,
+  observation_observed_at_unix_millis BIGINT NOT NULL,
+  claim_id TEXT NOT NULL,
+  claim_statement TEXT NOT NULL,
+  claim_observation_id TEXT NOT NULL,
+  claim_citation_id TEXT NOT NULL,
+  claim_verification TEXT NOT NULL,
+  belief_id TEXT NOT NULL,
+  belief_claim_id TEXT NOT NULL,
+  belief_state TEXT NOT NULL,
+  citation_id TEXT NOT NULL,
+  citation_excerpt_id TEXT NOT NULL,
+  citation_evidence TEXT NOT NULL,
+  citation_coverage TEXT NOT NULL,
+  citation_conflict TEXT NOT NULL,
+  citation_resolved_at_unix_millis BIGINT NOT NULL,
+  recorded_at_unix_millis BIGINT NOT NULL,
+  UNIQUE (snapshot_id, excerpt_id, claim_id),
+  CHECK (bundle_id <> ''), CHECK (source_id <> ''), CHECK (source_locator <> ''),
+  CHECK (excerpt_start >= 0), CHECK (excerpt_end >= excerpt_start),
+  CHECK (recorded_at_unix_millis > 0)
+);
+
+CREATE INDEX IF NOT EXISTS truth_bundles_source_time_idx
+  ON epistemics.truth_bundles (source_id, recorded_at_unix_millis DESC);
+
+RESET ROLE;
+COMMIT;

dev/ACTIVE_TASK.json

@@ -1,5 +1,5 @@
 {
-  "task_file": "dev/tasks/DEV-000115-cognitive-admission-control.json",
-  "task_id": "DEV-000115",
-  "task_revision": 6
+  "task_file": "dev/tasks/DEV-000142-truth-bundle-persistence.json",
+  "task_id": "DEV-000142",
+  "task_revision": 1
 }

dev/tasks/DEV-000141-optional-fleet-readiness.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "DEV-000141",
+  "task_revision": 2,
+  "architecture_revision": "ADR-0018",
+  "base_repo_revision": "38cff16",
+  "risk_tier": "E",
+  "intent": "Keep cognitive readiness available when an optional opportunistic fleet member is unavailable while preserving typed degraded evidence.",
+  "requirement_ids": ["WP-003", "WP-203", "Fleet failover readiness"],
+  "allowed_change_scope": {"modules": ["runtime-health", "cognitive-worker"], "paths": ["runtime/health/**", "cmd/cognitive-worker/main.go", "runtime/health/server_test.go", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000141-optional-fleet-readiness.json"]},
+  "forbidden_change_scope": {"paths": ["architecture/**", "database/**", "deploy/**", "security/**", ".gitea/**"]},
+  "allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 0, "new_third_party_dependencies": 0, "new_database_owner_roles": 0},
+  "contracts": {"consume": ["Existing readiness Probe and typed readiness response"], "may_change": ["Optional dependency probe behavior"]},
+  "semantic_owner": "runtime-health and cognitive-worker",
+  "canonical_state": [],
+  "state_transitions": ["optional provider unavailable -> readiness remains ready with typed degraded check", "required dependency unavailable -> readiness remains degraded"],
+  "side_effects_and_privileges": ["No external mutation; no provider invocation"],
+  "persistence_and_migrations": ["None"],
+  "failure_retry_restart": ["Optional provider can recover on subsequent readiness probe"],
+  "assumptions": ["CPU/Lifeboat remains a qualified fallback when opportunistic GPU is unavailable"],
+  "acceptance_scenarios": ["GPU timeout does not hide degraded evidence or make fallback unavailable", "required dependency failure still returns 503"],
+  "required_tests": ["go test ./...", "go vet ./...", "preflight", "check-diff", "check-architecture", "independent", "git diff --check", "docker compose config"],
+  "terminal_gap_states": ["BLOCKED_BY_SPEC_GAP", "BLOCKED_BY_CONFLICT"]
+}

dev/tasks/DEV-000142-truth-bundle-persistence.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "DEV-000142",
+  "task_revision": 1,
+  "architecture_revision": "ADR-0018",
+  "base_repo_revision": "0b321fe",
+  "risk_tier": "E",
+  "intent": "Persist typed Truth/Research bundles with exact source, snapshot, excerpt and citation provenance in the epistemics owner schema.",
+  "requirement_ids": ["WP-102", "Truth runtime", "Research provenance persistence"],
+  "allowed_change_scope": {"modules": ["epistemics", "database"], "paths": ["contracts/epistemics/truth.go", "modules/epistemics/domain/**", "adapters/postgres/epistemics_repository.go", "database/migrations/034_epistemics_truth_bundles.sql", "tests/research_contracts/**", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000142-truth-bundle-persistence.json"]},
+  "forbidden_change_scope": {"paths": ["architecture/**", "deploy/**", "security/**", "cmd/**", ".gitea/**"]},
+  "allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 1, "new_third_party_dependencies": 0, "new_database_owner_roles": 1},
+  "contracts": {"consume": ["TruthBundle, Source, SourceSnapshot, SourceExcerpt and Citation contracts"], "may_change": ["TruthBundle carries exact source evidence needed for durable provenance"]},
+  "semantic_owner": "epistemics",
+  "canonical_state": ["epistemics.truth_bundles"],
+  "state_transitions": ["compiled truth bundle -> durable append/update by exact citation identity"],
+  "side_effects_and_privileges": ["epistemics_role writes only epistemics.truth_bundles"],
+  "persistence_and_migrations": ["Migration 034; idempotent table/index creation"],
+  "failure_retry_restart": ["bundle write is idempotent by citation-derived bundle id"],
+  "assumptions": ["external connectors remain read-only and are a separate follow-up"],
+  "acceptance_scenarios": ["exact source chain is persisted", "duplicate bundle write is idempotent", "cross-owner schemas are untouched"],
+  "required_tests": ["go test ./...", "go vet ./...", "preflight", "check-diff", "check-architecture", "independent", "git diff --check", "docker compose config"],
+  "terminal_gap_states": ["BLOCKED_BY_SPEC_GAP", "BLOCKED_BY_CONFLICT", "REQUIRES_MIGRATION_DECISION"]
+}

modules/epistemics/domain/research.go

@@ -106,5 +106,5 @@ func compileResearchCandidate(candidate epistemics.ResearchCandidate) (epistemic
 	}
 	observation := epistemics.Observation{ID: epistemics.ObservationID("observation:" + string(candidate.Excerpt.ID)), SourceSnapshot: candidate.Snapshot.ID, Excerpt: candidate.Excerpt.ID, Text: candidate.Excerpt.Text, ObservedAt: candidate.Snapshot.CapturedAtUnixMillis}
 	claim := epistemics.Claim{ID: epistemics.ClaimID("claim:" + string(candidate.Excerpt.ID)), Statement: candidate.Statement, ObservationID: observation.ID, CitationID: citation.ID, Verification: epistemics.VerificationUnverified}
-	return epistemics.TruthBundle{Observation: observation, Claim: claim, Belief: epistemics.Belief{ID: epistemics.BeliefID("belief:" + string(candidate.Excerpt.ID)), ClaimID: claim.ID, State: epistemics.BeliefProvisional}, Citation: citation}, nil
+	return epistemics.TruthBundle{Source: candidate.Source, Snapshot: candidate.Snapshot, Excerpt: candidate.Excerpt, Observation: observation, Claim: claim, Belief: epistemics.Belief{ID: epistemics.BeliefID("belief:" + string(candidate.Excerpt.ID)), ClaimID: claim.ID, State: epistemics.BeliefProvisional}, Citation: citation}, nil
 }

modules/epistemics/domain/truth.go

@@ -23,7 +23,7 @@ func CompileObservedClaim(source epistemics.Source, snapshot epistemics.SourceSn
 	if conflict == epistemics.ConflictPresent || conflict == epistemics.ConflictUnknown {
 		state = epistemics.BeliefConflicted
 	}
-	bundle := epistemics.TruthBundle{Observation: observation, Claim: claim, Belief: epistemics.Belief{ID: epistemics.BeliefID("belief:" + string(excerpt.ID)), ClaimID: claim.ID, State: state}, Citation: citation}
+	bundle := epistemics.TruthBundle{Source: source, Snapshot: snapshot, Excerpt: excerpt, Observation: observation, Claim: claim, Belief: epistemics.Belief{ID: epistemics.BeliefID("belief:" + string(excerpt.ID)), ClaimID: claim.ID, State: state}, Citation: citation}
 	if bundle.Observation.SourceSnapshot != snapshot.ID || bundle.Claim.ObservationID != bundle.Observation.ID || bundle.Claim.CitationID != bundle.Citation.ID || bundle.Belief.ClaimID != bundle.Claim.ID {
 		return epistemics.TruthBundle{}, ErrInvalidTruthBundle
 	}

runtime/health/server.go

@@ -26,8 +26,9 @@ func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 }
 
 type Probe struct {
-	Name  string
-	Check func(context.Context) error
+	Name     string
+	Check    func(context.Context) error
+	Optional bool
 }
 
 type Result struct {
@@ -59,11 +60,13 @@ func (h ReadinessHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 			err := probe.Check(ctx)
 			cancel()
 			if err != nil {
-				ready = false
 				result.State, result.Reason, result.Detail = "DEGRADED", "DEPENDENCY_UNAVAILABLE", err.Error()
+				if !probe.Optional {
+					ready = false
+				}
 			}
 		}
-		if result.State != "READY" {
+		if result.State != "READY" && !probe.Optional {
 			ready = false
 		}
 		results = append(results, result)
@@ -96,6 +99,15 @@ func HTTPProbe(client *http.Client, endpoint string) Probe {
 	}}
 }
 
+// OptionalHTTPProbe reports dependency degradation without making the whole
+// runtime unavailable. This is used for opportunistic fleet members when a
+// qualified local fallback remains available.
+func OptionalHTTPProbe(client *http.Client, endpoint string) Probe {
+	probe := HTTPProbe(client, endpoint)
+	probe.Optional = true
+	return probe
+}
+
 func TCPProbe(name, host, port string) Probe {
 	return Probe{Name: name, Check: func(ctx context.Context) error {
 		connection, err := (&net.Dialer{}).DialContext(ctx, "tcp", net.JoinHostPort(host, port))

runtime/health/server_test.go

@@ -26,3 +26,16 @@ func TestReadinessReturns200WhenAllProbesPass(t *testing.T) {
 		t.Fatalf("readiness response = %d %s", recorder.Code, recorder.Body.String())
 	}
 }
+
+func TestReadinessStaysAvailableWithOptionalDependencyDegraded(t *testing.T) {
+	handler := ReadinessHandler{Runtime: "test", Probes: []Probe{
+		{Name: "lifeboat", Check: func(context.Context) error { return nil }},
+		{Name: "opportunistic-gpu", Optional: true, Check: func(context.Context) error { return errors.New("timeout") }},
+	}}
+	recorder := httptest.NewRecorder()
+	handler.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/readyz", nil))
+	body := recorder.Body.String()
+	if recorder.Code != http.StatusOK || !strings.Contains(body, `"status":"ready"`) || !strings.Contains(body, `"state":"DEGRADED"`) {
+		t.Fatalf("readiness response = %d %s", recorder.Code, body)
+	}
+}

tests/research_contracts/truth_persistence_sql_test.go

@@ -0,0 +1,26 @@
+package research_contracts_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestTruthBundlePersistenceMigrationIsOwnedAndIdempotent(t *testing.T) {
+	payload, err := os.ReadFile("../../database/migrations/034_epistemics_truth_bundles.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	script := string(payload)
+	for _, required := range []string{
+		"SET ROLE epistemics_role",
+		"CREATE TABLE IF NOT EXISTS epistemics.truth_bundles",
+		"UNIQUE (snapshot_id, excerpt_id, claim_id)",
+		"CREATE INDEX IF NOT EXISTS truth_bundles_source_time_idx",
+		"RESET ROLE",
+	} {
+		if !strings.Contains(script, required) {
+			t.Fatalf("migration missing %q", required)
+		}
+	}
+}