feat(runtime): add a decision model seam with opt-in and fail-open

.env.example

@@ -101,6 +101,21 @@ POWERCONTEXT_SERVER_RUNTIME_DREAM_MAX_PENDING_PER_SCOPE=32
 # POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_CANDIDATE_LIMIT=30
 # POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_SCHEDULE_SECONDS=60
 
+# Opt-in decision role for narrow Runtime judgements. Disabled by default; when unset the role
+# is absent and makes no model call.
+# POWERCONTEXT_SERVER_RUNTIME_DECISION_ASSISTANCE_ENABLED=true
+
+# Recall-sufficiency gate. Disabled by default; enabling expands thin recall up to two rounds.
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_ENABLED=true
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_MAX_ROUNDS=2
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_MIN_CANDIDATES=2
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_MIN_TOP_SCORE=0.35
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_MIN_TOP_GAP=0.02
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_MIN_LEXICAL_OVERLAP=0.5
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_ROUND1_MIN_SEMANTIC_SIMILARITY=0.15
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_ROUND2_MIN_SEMANTIC_SIMILARITY=0.10
+# POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_ALLOW_WITH_RERANK=false
+
 # Inference common settings ----------------------------------------------------
 # Generation and Embedding may use different providers; `powercontext config init` configures valid combinations.
 POWERCONTEXT_SERVER_INFERENCE_GENERATION_TIMEOUT_SECONDS=30
@@ -126,6 +141,13 @@ POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS=30
 # POWERCONTEXT_SERVER_INFERENCE_RERANK_MODEL_SETTINGS={"max_tokens":256}
 # POWERCONTEXT_SERVER_INFERENCE_RERANK_TIMEOUT_SECONDS=30
 # POWERCONTEXT_SERVER_INFERENCE_RERANK_MAX_REQUESTS=2
+# The decision role reuses the generation model unless a dedicated model is configured.
+# POWERCONTEXT_SERVER_INFERENCE_DECISION_MODEL=openai-chat:local-decider
+# POWERCONTEXT_SERVER_INFERENCE_DECISION_BASE_URL=http://127.0.0.1:8083/v1
+# POWERCONTEXT_SERVER_INFERENCE_DECISION_HEADERS={"Authorization":"Bearer replace-me"}
+# POWERCONTEXT_SERVER_INFERENCE_DECISION_MODEL_SETTINGS={"max_tokens":256}
+# POWERCONTEXT_SERVER_INFERENCE_DECISION_TIMEOUT_SECONDS=30
+# POWERCONTEXT_SERVER_INFERENCE_DECISION_MAX_REQUESTS=2
 
 # Provider A: OpenAI (enabled). Set OPENAI_API_KEY in the Server shell.
 POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=openai:gpt-4.1-mini

src/powercontext/builtin/runtime/__init__.py

@@ -98,6 +98,12 @@
     InferenceConfig,
     RuntimeConfig,
 )
+from powercontext.builtin.runtime.decision_model import (
+    DecisionModel,
+    DecisionOutcome,
+    DecisionRequest,
+    DecisionResult,
+)
 from powercontext.builtin.runtime.errors import InvalidRuntimeRequestError, TopicMemoryProcessingUnavailableError
 from powercontext.builtin.runtime.models import (
     ApproveArtifactCandidateRequest,
@@ -213,6 +219,10 @@
     "ContextAssemblySection",
     "CreateDreamRunRequest",
     "DatabaseConfig",
+    "DecisionModel",
+    "DecisionOutcome",
+    "DecisionRequest",
+    "DecisionResult",
     "DreamApplication",
     "DreamRun",
     "DreamRunPage",

src/powercontext/builtin/runtime/application.py

@@ -161,6 +161,7 @@
     ScopeCacheObserver,
     ScopeEvictor,
 )
+from powercontext.builtin.runtime.decision_model import DecisionModel
 from powercontext.builtin.runtime.errors import InvalidRuntimeRequestError, TopicMemoryProcessingUnavailableError
 from powercontext.builtin.runtime.models import (
     ApproveArtifactCandidateRequest,
@@ -2969,6 +2970,7 @@ def __init__(
         prompt_service: PromptService | None = None,
         recall_token_estimator: RecallTokenEstimator | None = None,
         recall_effort_sink: RecallEffortSink | None = None,
+        decision_model: DecisionModel | None = None,
         publication_application: ArtifactPublicationApplication | None = None,
         scope_application: ScopeApplication | None = None,
         readiness: RuntimeReadinessChecks | None = None,
@@ -3024,6 +3026,9 @@ def __init__(
         self._prompt_service = prompt_service
         self._recall_token_estimator = recall_token_estimator
         self._recall_effort_sink = recall_effort_sink
+        # Public read-only seam for the cross-family decision role; deterministic Runtime callers
+        # (and tests) read it directly, and it is always fail-open wrapped before it gets here.
+        self.decision_model = decision_model
         self.publications = publication_application
         self.scopes = scope_application
         self._readiness = RuntimeReadinessChecks() if readiness is None else readiness