feat(runtime): add decision policy governance types

.env.example

@@ -109,6 +109,14 @@ POWERCONTEXT_SERVER_RUNTIME_DREAM_MAX_PENDING_PER_SCOPE=32
 # Memory write gate: opt-in evidence-sufficiency check before a write commits. Disabled by
 # default; when unset no gate runs and no extra model call is made.
 # POWERCONTEXT_SERVER_RUNTIME_MEMORY_WRITE_GATE_ENABLED=true
+# `disabled` does not construct a gate. `shadow` records an internal observation but always lets
+# the Memory write proceed. `advisory` turns an insufficient-evidence result into FLAG, while
+# `enforcing` preserves the visible ACCEPT/FLAG/HOLD outcomes.
+# POWERCONTEXT_SERVER_RUNTIME_MEMORY_WRITE_GATE_MODE=shadow
+# The default makes no decision-model call. Set `local_only` only for an in-process or loopback
+# decision backend controlled by this deployment. `hosted_redacted` is rejected until a shared
+# PowerContext content sanitizer is separately reviewed.
+# POWERCONTEXT_SERVER_RUNTIME_MEMORY_WRITE_GATE_PRIVACY_BOUNDARY=local_only
 # Direction only (which verdict means the cited evidence is insufficient): "yes" or "no".
 # POWERCONTEXT_SERVER_RUNTIME_MEMORY_WRITE_GATE_HOLD_ON=yes
 # Optional confidence floor below which a hold becomes a written-but-annotated change.

docs/en/docs/operate/troubleshoot.md

@@ -267,7 +267,7 @@ so the previous database remains available for recovery:
 
    ```bash
    obloader <connection-options> -D <new-database> --csv \
-      --table 'pc_scopes,pc_source_journal_heads,pc_sources,pc_artifacts,pc_source_cursors,pc_memory_source_windows,pc_artifact_processing_leases,pc_artifact_processing_binding_states,pc_artifact_processing_pending,pc_artifact_processing_auto_wave_targets,pc_artifact_processing_sequences,pc_artifact_processing_intents,pc_topic_memory_processing_targets,pc_artifact_processing_schema,pc_artifact_processing_migration_receipts,pc_topic_memory_work_budgets,pc_topic_memory_retrieval_shape,pc_connector_checkpoints,pc_source_definition_manifests,pc_external_skill_registrations,pc_skill_packages,pc_agent_skill_targets,pc_skill_publications,pc_model_usage_daily,pc_recall_token_daily,pc_receipt_migration_review' \
+      --table 'pc_scopes,pc_source_journal_heads,pc_sources,pc_artifacts,pc_source_cursors,pc_memory_source_windows,pc_artifact_processing_leases,pc_artifact_processing_binding_states,pc_artifact_processing_pending,pc_artifact_processing_auto_wave_targets,pc_artifact_processing_sequences,pc_artifact_processing_intents,pc_topic_memory_processing_targets,pc_artifact_processing_schema,pc_artifact_processing_migration_receipts,pc_topic_memory_work_budgets,pc_topic_memory_retrieval_shape,pc_connector_checkpoints,pc_source_definition_manifests,pc_external_skill_registrations,pc_skill_packages,pc_agent_skill_targets,pc_skill_publications,pc_model_usage_daily,pc_recall_token_daily,pc_receipt_migration_review,pc_decision_observations' \
      -f <export-directory>
    ```
 

docs/zh/docs/operate/troubleshoot.md

@@ -259,7 +259,7 @@ collation，但不会包含数据库 URL 或凭据。
 
    ```bash
    obloader <connection-options> -D <new-database> --csv \
-      --table 'pc_scopes,pc_source_journal_heads,pc_sources,pc_artifacts,pc_source_cursors,pc_memory_source_windows,pc_artifact_processing_leases,pc_artifact_processing_binding_states,pc_artifact_processing_pending,pc_artifact_processing_auto_wave_targets,pc_artifact_processing_sequences,pc_artifact_processing_intents,pc_topic_memory_processing_targets,pc_artifact_processing_schema,pc_artifact_processing_migration_receipts,pc_topic_memory_work_budgets,pc_topic_memory_retrieval_shape,pc_connector_checkpoints,pc_source_definition_manifests,pc_external_skill_registrations,pc_skill_packages,pc_agent_skill_targets,pc_skill_publications,pc_model_usage_daily,pc_recall_token_daily,pc_receipt_migration_review' \
+      --table 'pc_scopes,pc_source_journal_heads,pc_sources,pc_artifacts,pc_source_cursors,pc_memory_source_windows,pc_artifact_processing_leases,pc_artifact_processing_binding_states,pc_artifact_processing_pending,pc_artifact_processing_auto_wave_targets,pc_artifact_processing_sequences,pc_artifact_processing_intents,pc_topic_memory_processing_targets,pc_artifact_processing_schema,pc_artifact_processing_migration_receipts,pc_topic_memory_work_budgets,pc_topic_memory_retrieval_shape,pc_connector_checkpoints,pc_source_definition_manifests,pc_external_skill_registrations,pc_skill_packages,pc_agent_skill_targets,pc_skill_publications,pc_model_usage_daily,pc_recall_token_daily,pc_receipt_migration_review,pc_decision_observations' \
      -f <export-directory>
    ```
 

src/powercontext/builtin/artifacts/memory/protocols.py

@@ -19,7 +19,7 @@
 from contextlib import AbstractAsyncContextManager
 from dataclasses import dataclass
 from enum import StrEnum
-from typing import Protocol
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 from pydantic import BaseModel, ConfigDict
 
@@ -39,6 +39,18 @@
 from powercontext.builtin.tags import TagFilter
 from powercontext.sources import Source
 
+if TYPE_CHECKING:
+    from powercontext.builtin.decision_observations import DecisionObservation
+
+
+class MemoryWriteObservationSink(Protocol):
+    """Accept a bounded decision sidecar without owning the Memory write."""
+
+    async def record(self, observation: DecisionObservation, /) -> None:
+        """Store one decision observation after the gate has made its judgement."""
+
+        ...
+
 
 class MemoryCandidateRequest(BaseModel):
     """Canonical evidence and bounded current entries offered to a pipeline."""
@@ -110,6 +122,11 @@ class MemoryWriteGateRequest:
     candidates: tuple[str, ...]
     evidence: tuple[str, ...]
     expected_revision: int | None = None
+    scope_id: str = "unscoped"
+    operation_id: str | None = None
+    subject_refs: tuple[str, ...] = ()
+    evidence_refs: tuple[str, ...] = ()
+    observation_sink: MemoryWriteObservationSink | None = None
 
 
 class MemoryWriteGate(Protocol):
@@ -127,6 +144,18 @@ async def assess(self, request: MemoryWriteGateRequest, /) -> MemoryWriteAssessm
         ...
 
 
+@runtime_checkable
+class MemoryWriteGatePreflight(Protocol):
+    """Optionally map a deterministic service-side preflight rejection through a gate policy."""
+
+    async def assess_preflight(
+        self, request: MemoryWriteGateRequest, rejection: MemoryWriteAssessment, /
+    ) -> MemoryWriteAssessment:
+        """Return the mode-aware decision for a bounded preflight rejection."""
+
+        ...
+
+
 class MemoryWritePlan(BaseModel):
     """A side-effect-free result that can be committed in an outer transaction."""
 

src/powercontext/builtin/artifacts/memory/service.py

@@ -92,7 +92,9 @@
     MemorySearchRequest,
     MemoryWriteAssessment,
     MemoryWriteGate,
+    MemoryWriteGatePreflight,
     MemoryWriteGateRequest,
+    MemoryWriteObservationSink,
     MemoryWritePlan,
     MemoryWriteRejectionCode,
     MemoryWriteVerdict,
@@ -259,7 +261,9 @@ def __init__(
         artifact_resolver: _ArtifactResolver | None = None,
         id_factory: IdFactory | None = None,
         prompt_context: ScopedPrompts | None = None,
+        scope_id: str = "unscoped",
         write_gate: MemoryWriteGate | None = None,
+        write_gate_observation_sink: MemoryWriteObservationSink | None = None,
         capacity_budget: MemoryCapacityBudget | None = None,
         compaction: MemoryCompactionPolicy | None = None,
         max_history_revisions: int = 100,
@@ -268,6 +272,8 @@ def __init__(
         self._prompt_context = prompt_context
         self._candidate_pipeline = candidate_pipeline
         self._write_gate = write_gate
+        self._write_gate_observation_sink = write_gate_observation_sink
+        self._scope_id = scope_id
         self._embedding_model = embedding_model
         if rerank_candidate_limit < 1:
             raise _InvalidMemoryOperationError("search-limit")
@@ -1375,17 +1381,23 @@ async def _assess_write(
         if self._write_gate is None:
             return None
         projection = await self._gate_evidence(base, candidates, evidence, current_entries)
+        request = MemoryWriteGateRequest(
+            candidates=tuple(candidate.text for candidate in candidates),
+            evidence=projection.entries,
+            expected_revision=None if base is None else base.revision,
+            scope_id=self._scope_id,
+            operation_id=_gate_operation_id(base),
+            subject_refs=_gate_subject_refs(candidates),
+            evidence_refs=tuple(_gate_evidence_ref(entry) for entry in projection.entries),
+            observation_sink=self._write_gate_observation_sink,
+        )
         if projection.rejection is not None:
+            if isinstance(self._write_gate, MemoryWriteGatePreflight):
+                return await self._write_gate.assess_preflight(request, projection.rejection)
             _log_gate_assessment(projection.rejection)
             return projection.rejection
         try:
-            return await self._write_gate.assess(
-                MemoryWriteGateRequest(
-                    candidates=tuple(candidate.text for candidate in candidates),
-                    evidence=projection.entries,
-                    expected_revision=None if base is None else base.revision,
-                )
-            )
+            return await self._write_gate.assess(request)
         except Exception:
             return MemoryWriteAssessment(
                 verdict=MemoryWriteVerdict.ACCEPT,
@@ -1839,6 +1851,25 @@ def _candidate_gate_identity(candidate_index: int, identity: str) -> str:
     return f"candidate:{candidate_index} {identity}"
 
 
+def _gate_operation_id(base: Memory | None) -> str:
+    if base is None:
+        return "memory-write:new"
+    return f"memory-write:{base.artifact_id}@{base.revision + 1}"
+
+
+def _gate_subject_refs(candidates: tuple[MemoryEntryInput, ...]) -> tuple[str, ...]:
+    return tuple(
+        f"candidate:{index}"
+        if candidate.entry is None
+        else f"entry:{candidate.entry.entry_id}@{candidate.entry.entry_version_id}"
+        for index, candidate in enumerate(candidates, start=1)
+    )
+
+
+def _gate_evidence_ref(value: str) -> str:
+    return value.partition("\n")[0]
+
+
 def _source_gate_content(source: Source, resolver: _SourceResolver | None) -> str | None:
     content = getattr(source, "content", None)
     if isinstance(content, str):

src/powercontext/builtin/decision_observations.py

@@ -0,0 +1,159 @@
+# Copyright (c) 2026 OceanBase.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Runtime-independent contracts for bounded decision-policy sidecars."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Annotated
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator
+
+from powercontext.builtin.inference import InferenceUsage
+
+
+class DecisionPolicyMode(StrEnum):
+    """Runtime mode for one versioned decision policy."""
+
+    DISABLED = "disabled"
+    SHADOW = "shadow"
+    ADVISORY = "advisory"
+    ENFORCING = "enforcing"
+
+
+class DecisionFailurePolicy(StrEnum):
+    """How a consumer treats backend failure when it owns a domain action."""
+
+    FAIL_OPEN = "fail_open"
+    FAIL_CLOSED = "fail_closed"
+
+
+class DecisionPrivacyBoundary(StrEnum):
+    """Content boundary declared by a policy before backend calls."""
+
+    LOCAL_ONLY = "local_only"
+    HOSTED_REDACTED = "hosted_redacted"
+    REFERENCES_ONLY = "references_only"
+    NO_EXTERNAL_CALL = "no_external_call"
+
+
+class DecisionCoverage(StrEnum):
+    """Whether a policy evaluation actually judged the supplied content."""
+
+    ADJUDICATED = "adjudicated"
+    UNADJUDICATED = "unadjudicated"
+
+
+class DecisionVerdict(StrEnum):
+    """Domain-neutral verdict before an owning service maps it to an action."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    REVIEW = "review"
+    UNKNOWN = "unknown"
+
+
+class DecisionAssessmentSource(StrEnum):
+    """The source that produced the assessment's substantive judgement."""
+
+    LOCAL_RULE = "local_rule"
+    DECISION_MODEL = "decision_model"
+    NONE = "none"
+
+
+class _StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class DecisionPolicy(_StrictModel):
+    """Versioned, reviewable policy manifest for one bounded runtime question."""
+
+    policy_id: Annotated[str, Field(min_length=1, max_length=256)]
+    decision_kind: Annotated[str, Field(min_length=1, max_length=128)]
+    version: Annotated[str, Field(min_length=1, max_length=64)]
+    consumer: Annotated[str, Field(min_length=1, max_length=128)]
+    mode: DecisionPolicyMode
+    failure_policy: DecisionFailurePolicy
+    privacy_boundary: DecisionPrivacyBoundary
+    local_rules: tuple[Annotated[str, Field(min_length=1, max_length=128)], ...] = ()
+    question: Annotated[str, Field(min_length=1, max_length=8192)]
+    subject_selector: Annotated[str, Field(min_length=1, max_length=512)]
+    evidence_selector: Annotated[str, Field(min_length=1, max_length=512)]
+    outcome_mapping: Mapping[str, Annotated[str, Field(min_length=1, max_length=128)]] = Field(default_factory=dict)
+    promotion_criteria: tuple[Annotated[str, Field(min_length=1, max_length=512)], ...] = ()
+
+
+class DecisionAssessment(_StrictModel):
+    """Policy-level assessment before domain-specific action mapping."""
+
+    policy_id: Annotated[str, Field(min_length=1, max_length=256)]
+    policy_version: Annotated[str, Field(min_length=1, max_length=64)]
+    mode: DecisionPolicyMode
+    coverage: DecisionCoverage
+    verdict: DecisionVerdict
+    source: DecisionAssessmentSource
+    reason: Annotated[str | None, Field(min_length=1, max_length=4096)] = None
+    confidence: Annotated[float | None, Field(ge=0.0, le=1.0)] = None
+    used_fallback: bool = False
+    usage: InferenceUsage = Field(default_factory=lambda: InferenceUsage(requests=0))
+    latency_ms: Annotated[float | None, Field(ge=0.0, allow_inf_nan=False)] = None
+
+    @model_validator(mode="after")
+    def validate_fallback_coverage(self) -> DecisionAssessment:
+        if self.used_fallback and self.coverage is not DecisionCoverage.UNADJUDICATED:
+            raise ValueError("fallback assessments must be unadjudicated")  # noqa: TRY003
+        return self
+
+
+class DecisionObservation(_StrictModel):
+    """Audit/replay sidecar for one policy evaluation attempt."""
+
+    observation_id: Annotated[str, Field(min_length=1, max_length=128)] = Field(
+        default_factory=lambda: f"decision-observation-{uuid4().hex}"
+    )
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    operation_id: Annotated[str, Field(min_length=1, max_length=256)]
+    scope_id: Annotated[str, Field(min_length=1, max_length=256)]
+    consumer: Annotated[str, Field(min_length=1, max_length=128)]
+    policy_id: Annotated[str, Field(min_length=1, max_length=256)]
+    policy_version: Annotated[str, Field(min_length=1, max_length=64)]
+    mode: DecisionPolicyMode
+    subject_refs: tuple[Annotated[str, Field(min_length=1, max_length=512)], ...] = ()
+    evidence_refs: tuple[Annotated[str, Field(min_length=1, max_length=512)], ...] = ()
+    privacy_boundary: DecisionPrivacyBoundary
+    privacy_outcome: Annotated[str | None, Field(min_length=1, max_length=128)] = None
+    provider_id: Annotated[str | None, Field(min_length=1, max_length=128)] = None
+    backend_model_id: Annotated[str | None, Field(min_length=1, max_length=256)] = None
+    model_policy_id: Annotated[str | None, Field(min_length=1, max_length=256)] = None
+    assessment: DecisionAssessment
+    final_action: Annotated[str, Field(min_length=1, max_length=128)]
+    fallback_reason: Annotated[str | None, Field(min_length=1, max_length=256)] = None
+    metadata: Mapping[str, JsonValue] = Field(default_factory=dict)
+
+
+__all__ = [
+    "DecisionAssessment",
+    "DecisionAssessmentSource",
+    "DecisionCoverage",
+    "DecisionFailurePolicy",
+    "DecisionObservation",
+    "DecisionPolicy",
+    "DecisionPolicyMode",
+    "DecisionPrivacyBoundary",
+    "DecisionVerdict",
+]

src/powercontext/builtin/persistence/__init__.py

@@ -22,6 +22,7 @@
 from powercontext.builtin.persistence.candidates import CandidateRepository
 from powercontext.builtin.persistence.connectors import ConnectorCheckpointRepository
 from powercontext.builtin.persistence.database import AsyncDatabase
+from powercontext.builtin.persistence.decision_observations import DecisionObservationRepository
 from powercontext.builtin.persistence.errors import (
     ArtifactProcessingLeadershipLostError,
     ArtifactProcessingWaveIncompleteError,
@@ -78,6 +79,7 @@
     "CompositeTopicMemoryIndex",
     "ConnectorCheckpointRepository",
     "DatabaseClosedError",
+    "DecisionObservationRepository",
     "ExternalSkillRepository",
     "GenerationConflictError",
     "IdentityMismatchError",