fix(cognitive): resolve providers by stable instance identity

docs(runtime): record local fallback gateway evidence

cmd/cognitive-worker/gateway.go

@@ -298,12 +298,21 @@ func fallbackEligible(reason cognitive.FinishReason) bool {
 }
 
 func (g cognitiveGateway) provider(selected capability.ResolvedCognitiveBinding) advisoryProvider {
+	var byStableID advisoryProvider
 	for _, registration := range g.providers[selected.Provider.Kind] {
 		if registration.EndpointRef == selected.Provider.EndpointRef && registration.CredentialRef == selected.Provider.CredentialRef {
 			return registration.Provider
 		}
+		// Capability revisions can legitimately retain an older credential
+		// reference while the protected runtime has rotated or reloaded the
+		// current credential. ProviderInstanceID is the stable owner identity;
+		// use it after exact metadata matching so stale non-secret metadata does
+		// not force an unnecessary builtin fallback.
+		if byStableID == nil && registration.ProviderInstanceID == selected.Provider.ID && registration.Kind == selected.Provider.Kind {
+			byStableID = registration.Provider
+		}
 	}
-	return nil
+	return byStableID
 }
 
 func writeGatewayResponse(w http.ResponseWriter, response cognitive.GatewayAdvisoryResponse) {

cmd/cognitive-worker/gateway_registry_test.go

@@ -88,6 +88,19 @@ func TestActiveRegistryBindingReachesProviderAdapter(t *testing.T) {
 	}
 }
 
+func TestProviderUsesStableInstanceWhenCredentialMetadataIsStale(t *testing.T) {
+	provider := &stubAdvisoryProvider{}
+	gateway := cognitiveGateway{providers: map[capability.ProviderKind][]providerRegistration{
+		"provider-kind-1": {{ProviderInstanceID: "provider-1", Kind: "provider-kind-1", EndpointRef: "current-endpoint", CredentialRef: "current-credential", Provider: provider}},
+	}}
+	selected := gatewaySelection()
+	selected.Provider.EndpointRef = "old-endpoint"
+	selected.Provider.CredentialRef = ""
+	if got := gateway.provider(selected); got != provider {
+		t.Fatalf("stable provider identity was not used for stale metadata")
+	}
+}
+
 func TestCanaryFlagIsForwardedToCapabilityResolver(t *testing.T) {
 	registry := &registryStub{err: errors.New("stop after resolve")}
 	gateway := cognitiveGateway{resolver: registry, providers: map[capability.ProviderKind][]providerRegistration{}, now: time.Now, allowCanary: true}

dev/ACTIVE_TASK.json

@@ -1,5 +1,5 @@
 {
-  "task_file": "dev/tasks/DEV-000237-ui-authenticated-section-smoke.json",
-  "task_id": "DEV-000237",
+  "task_file": "dev/tasks/DEV-000239-stable-provider-resolution.json",
+  "task_id": "DEV-000239",
   "task_revision": 1
 }

dev/tasks/DEV-000238-local-fallback-evidence.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "DEV-000238",
+  "task_revision": 1,
+  "architecture_revision": "ADR-0018",
+  "base_repo_revision": "0609561dfefb6dce302f56d50bb56bd5a222fb64",
+  "risk_tier": "E",
+  "intent": "Record a bounded live proof that the advisory gateway keeps a local lifeboat path when the normal model route cannot be used.",
+  "requirement_ids": ["Agent Execution local recovery", "model fleet fallback", "false completion prevention"],
+  "allowed_change_scope": {"modules": ["evidence"], "paths": ["docs/evidence/local-fallback-gateway-live-2026-08-23-v1.json", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000238-local-fallback-evidence.json"]},
+  "forbidden_change_scope": {"paths": ["architecture/**", "security/**", "database/**", "deploy/**", "LLM-local/**", "modules/work/secrets/**", "contracts/**"]},
+  "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": ["creator advisory gateway", "durable cognitive usage observation"], "may_change": []},
+  "semantic_owner": "Evidence only",
+  "canonical_state": ["no runtime state mutation; read-only evidence capture"],
+  "state_transitions": ["normal route unavailable or not eligible -> builtin local lifeboat response"],
+  "side_effects_and_privileges": ["bounded local advisory request; no external egress and no secret exposure"],
+  "persistence_and_migrations": ["existing cognitive usage observation only"],
+  "failure_retry_restart": ["live request is bounded and idempotent in effect"],
+  "assumptions": ["the production database observation is the authoritative route attribution"],
+  "acceptance_scenarios": ["local response is COMPLETED", "usage evidence identifies builtin-local-lifeboat-v1", "no claim of external bridge or multi-model failover"],
+  "required_tests": ["go test ./cmd/core-runtime/...", "go vet ./cmd/core-runtime/...", "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-diff -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-architecture", "git diff --check", "independent", "CI", "production health smoke"],
+  "terminal_gap_states": ["BLOCKED_BY_MISSING_CAPABILITY", "BLOCKED_BY_SPEC_GAP"]
+}

dev/tasks/DEV-000239-stable-provider-resolution.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "DEV-000239",
+  "task_revision": 1,
+  "architecture_revision": "ADR-0018",
+  "base_repo_revision": "6061eb5c13e46cec1e60fc104b022394f0d94dee",
+  "risk_tier": "E",
+  "intent": "Resolve a registered provider by its stable instance identity when a persisted Capability revision contains stale non-secret endpoint credential metadata, while preserving exact metadata matching first.",
+  "requirement_ids": ["model fleet/failover", "credential rotation compatibility", "local fallback attribution"],
+  "allowed_change_scope": {"modules": ["cognitive-worker"], "paths": ["cmd/cognitive-worker/gateway.go", "cmd/cognitive-worker/gateway_registry_test.go", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000239-stable-provider-resolution.json"]},
+  "forbidden_change_scope": {"paths": ["architecture/**", "security/**", "database/**", "deploy/**", "LLM-local/**", "modules/work/secrets/**", "contracts/**"]},
+  "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": ["Capability ResolvedCognitiveBinding", "protected provider registration"], "may_change": ["internal provider lookup fallback order"]},
+  "semantic_owner": "Cognitive worker provider adapter boundary",
+  "canonical_state": ["no new durable state"],
+  "state_transitions": ["exact provider metadata match -> stable provider identity match -> no provider"],
+  "side_effects_and_privileges": ["provider lookup only; secret values remain in protected runtime"],
+  "persistence_and_migrations": ["none"],
+  "failure_retry_restart": ["missing provider remains explicit and uses existing builtin fallback"],
+  "assumptions": ["ProviderInstanceID is the stable Capability-owned provider identity"],
+  "acceptance_scenarios": ["stale credential metadata still reaches current registered adapter", "exact metadata match retains priority", "no provider remains nil"],
+  "required_tests": ["go test ./cmd/cognitive-worker/...", "go vet ./cmd/cognitive-worker/...", "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-diff -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-architecture", "git diff --check", "independent", "CI", "production health smoke"],
+  "terminal_gap_states": ["BLOCKED_BY_MISSING_CAPABILITY", "BLOCKED_BY_SPEC_GAP"]
+}

docs/evidence/local-fallback-gateway-live-2026-08-23-v1.json

@@ -0,0 +1,12 @@
+{
+  "evidence_id": "local-fallback-gateway-live-2026-08-23-v1",
+  "observed_at": "2026-08-23",
+  "production_revision": "0609561dfefb6dce302f56d50bb56bd5a222fb64",
+  "request": {"surface": "internal cognitive-worker advisory gateway", "data_policy": "LOCAL_ONLY", "max_output_bytes": 128, "prompt_class": "bounded readiness response"},
+  "http_result": {"status": 200, "finish_reason": "COMPLETED", "output_observed": true, "output_content": "готов"},
+  "durable_usage_observation": {"provider_instance_id": "builtin-local-lifeboat-v1", "model_descriptor_id": "builtin-local-model-v1", "result_class": "COMPLETED", "failure_type": null, "latency_millis": 665},
+  "status": "LOCAL_FALLBACK_LIVE_PASS",
+  "proves": ["local lifeboat path can answer when normal route is not eligible", "completion is durably attributed to the local fallback"],
+  "does_not_prove": ["external Agent Execution bridge", "multi-model failover between validated provider bindings", "GPU quality or promotion", "long-running recovery"],
+  "secrets_exposed": false
+}