claude-smart 0.2.46 → 0.2.47

package/plugin/vendor/reflexio/reflexio/server/services/README.md

@@ -52,6 +52,7 @@ strings before deleting old import paths in the same PR.
 | `playbook_optimizer/` | Scenario-based playbook optimization: mature flat package with `optimizer.py`, `scheduler.py`, `rollout.py`, `judge.py`, `models.py`, `scenario_resolver.py`, `gepa_adapter.py`, and `assistant_webhook.py`. See [README](playbook_optimizer/README.md). |
 | `braintrust/` | Braintrust export/sync: `service.py`, `client.py`, `_cron.py`, `_encryption.py`. |
 | `lineage/` | Current-record resolution and tombstone GC: `resolve.py`, `gc_scheduler.py`. |
+| `governance/` | Subject-reference and retention/barrier policy contracts: `config.py`, `service.py`, `subject_refs.py`. Storage and lineage code use these helpers to preserve governance constraints during writes, supersedes, and cleanup. |
 | `pre_retrieval/` | `QueryReformulator` (`_query_reformulator.py`) + `DocumentExpander` (`_document_expander.py`) - query rewrite and doc expansion for recall. Compact by design; see [README](pre_retrieval/README.md). |
 | `tagging/` | `TaggingService` (`service.py`) + deferred `tagging_scheduler.py` - post-generation profile/playbook tagging. Compact by design; see [README](tagging/README.md). |
 | `unified_search_service.py` | `run_unified_search()` — two-phase parallel search across profiles / agent playbooks / user playbooks. |
@@ -61,7 +62,7 @@ strings before deleting old import paths in the same PR.
 
 | Path | Purpose |
 |------|---------|
-| `storage/` | `storage_base/` (`BaseStorage` split by domain, including `_lineage.py`) + `sqlite_storage/` (including lineage/tombstones) + `retention*.py`. Access via `request_context.storage` only. |
+| `storage/` | `storage_base/` (`BaseStorage` split by domain, including `_governance.py` and `_lineage.py`) + `sqlite_storage/` (governance validation, retention barriers, lineage/tombstones) + `governance_validation.py` + `retention*.py`. Access via `request_context.storage` only. |
 | `configurator/` | `DefaultConfigurator` — loads YAML config and creates the storage backend. |
 
 ## Key Rules
@@ -71,3 +72,4 @@ strings before deleting old import paths in the same PR.
 - **ALWAYS use `LiteLLMClient`** for completions/embeddings and `request_context.prompt_manager.render_prompt(...)` for prompts — no hardcoded prompts, no direct OpenAI/Claude clients.
 - **All `_operation_state` writes go through `OperationStateManager`** — don't touch the table directly (it backs locks, bookmarks, progress, and cancellation).
 - **`tool_can_use` lives at root `Config`** — shared by playbook extraction and success evaluation, not per-service.
+- **Preserve governance subject refs/barriers** — route validation through `services/governance/` and `storage/governance_validation.py`; do not bypass retention or subject-write checks in storage implementations.

package/plugin/vendor/reflexio/reflexio/server/services/extraction/resume_worker.py

@@ -484,11 +484,18 @@ class ExtractionResumeWorker:
         raw_profiles = [
             profile.model_dump() for profile in result.output.profiles or []
         ]
+        source_interaction_ids = [
+            interaction.interaction_id
+            for request_model in request_interaction_data_models
+            for interaction in request_model.interactions
+            if interaction.interaction_id
+        ]
         return (
             extractor._convert_raw_to_user_profiles(
                 raw_profiles=raw_profiles,
                 user_id=run.binding.user_id,
                 request_id=run.binding.request_id,
+                source_interaction_ids=source_interaction_ids,
             ),
             result.pending_tool_call_ids,
         )
@@ -698,6 +705,7 @@ class ExtractionResumeWorker:
                 raw_profiles=raw_profiles,
                 user_id=run.binding.user_id,
                 request_id=run.binding.request_id,
+                source_interaction_ids=list(run.binding.source_interaction_ids),
             ),
             run.pending_tool_call_ids,
         )

package/plugin/vendor/reflexio/reflexio/server/services/governance/config.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from reflexio.server.env_utils import env_str, env_truthy
+from reflexio.server.services.governance.subject_refs import (
+    actor_ref,
+    request_ref,
+    subject_ref,
+)
+
+LOCAL_GOVERNANCE_REF_SECRET = "reflexio-local-governance-ref-secret"  # noqa: S105
+_PRODUCTION_DEPLOYMENT_MODES = {"platform", "self_host"}
+_PRODUCTION_ENVS = {"production", "staging"}
+
+
+def _is_local_dev_or_test() -> bool:
+    deployment_mode = env_str("DEPLOYMENT_MODE").lower()
+    reflexio_env = env_str("REFLEXIO_ENV", "development").lower()
+    if env_truthy(env_str("REFLEXIO_TEST_MODE")):
+        return True
+    return (
+        deployment_mode not in _PRODUCTION_DEPLOYMENT_MODES
+        and reflexio_env not in _PRODUCTION_ENVS
+    )
+
+
+def get_governance_ref_secret() -> str:
+    secret = env_str("REFLEXIO_GOVERNANCE_REF_SECRET")
+    if secret:
+        return secret
+    if _is_local_dev_or_test():
+        return LOCAL_GOVERNANCE_REF_SECRET
+    raise RuntimeError("REFLEXIO_GOVERNANCE_REF_SECRET is required")
+
+
+def governance_subject_ref(org_id: str, user_id: str, secret: str) -> str:
+    return subject_ref(f"{org_id}:subject:{user_id}", secret)
+
+
+def governance_request_ref(org_id: str, request_id: str, secret: str) -> str:
+    return request_ref(f"{org_id}:request:{request_id}", secret)
+
+
+def governance_actor_ref(
+    org_id: str,
+    credential_kind: str,
+    principal_or_fingerprint: str,
+    secret: str,
+) -> str:
+    return actor_ref(
+        f"{org_id}:actor:{credential_kind}:{principal_or_fingerprint}",
+        secret,
+    )

package/plugin/vendor/reflexio/reflexio/server/services/governance/service.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+from contextlib import suppress
+from typing import Any, Literal, TypedDict
+
+from reflexio.models.api_schema.domain.governance import (
+    AuditEvent,
+    PurgeOperationTarget,
+    SubjectWriteBarrier,
+    UserEraseResult,
+    UserExportResult,
+)
+from reflexio.server.services.governance.config import (
+    get_governance_ref_secret,
+    governance_request_ref,
+    governance_subject_ref,
+)
+from reflexio.server.services.governance.subject_refs import stable_id
+
+_DELETE_TARGET_NAME_TO_RESULT_KEY = {
+    "interaction": "interactions",
+    "user_playbook": "user_playbooks",
+    "profile": "profiles",
+    "request": "requests",
+    "agent_success_evaluation_result": "agent_success_evaluation_results",
+    "profile_purge": "purged_profiles",
+    "user_playbook_purge": "purged_user_playbooks",
+}
+_REQUIRED_DELETE_TARGET_NAMES = tuple(_DELETE_TARGET_NAME_TO_RESULT_KEY)
+_USER_PLAYBOOK_PAGE_SIZE = 1000
+
+
+class GovernanceActorContext(TypedDict):
+    actor_type: Literal["api_token", "jwt", "system"]
+    actor_ref: str | None
+
+
+class GovernanceService:
+    def __init__(self, *, storage: Any, org_id: str, ref_secret: str) -> None:
+        self.storage = storage
+        self.org_id = org_id
+        self.ref_secret = ref_secret
+
+    def export_user(
+        self,
+        *,
+        user_id: str,
+        request_id: str,
+        actor_context: GovernanceActorContext | None = None,
+    ) -> UserExportResult:
+        self._assert_storage_ref_secret_matches()
+        subref = governance_subject_ref(self.org_id, user_id, self.ref_secret)
+        reqref = governance_request_ref(self.org_id, request_id, self.ref_secret)
+        export_id = stable_id("export", f"{self.org_id}:export:{subref}:{reqref}")
+        actor_type = actor_context["actor_type"] if actor_context else "system"
+        actor_ref = actor_context["actor_ref"] if actor_context else None
+        requests, sessions = self._load_user_requests_and_sessions(user_id)
+        bundle: dict[str, Any] = {
+            "profiles": [
+                profile.model_dump()
+                for profile in self.storage.get_user_profile(user_id)
+            ],
+            "interactions": [
+                interaction.model_dump()
+                for interaction in self.storage.get_user_interaction(user_id)
+            ],
+            "requests": [request.model_dump() for request in requests],
+            "sessions": sessions,
+            "user_playbooks": [
+                playbook.model_dump() for playbook in self._iter_user_playbooks(user_id)
+            ],
+        }
+        self.storage.append_audit_event(
+            AuditEvent(
+                org_id=self.org_id,
+                actor_type=actor_type,
+                actor_ref=actor_ref,
+                operation="EXPORT",
+                entity_type="request",
+                subject_ref=subref,
+                request_ref=reqref,
+                idempotency_key=export_id,
+                detail={"count": sum(len(items) for items in bundle.values())},
+            )
+        )
+        return UserExportResult(subject_ref=subref, export_id=export_id, bundle=bundle)
+
+    def erase_user(
+        self,
+        *,
+        user_id: str,
+        request_id: str,
+        actor_context: GovernanceActorContext | None = None,
+    ) -> UserEraseResult:
+        self._assert_storage_ref_secret_matches()
+        subref = governance_subject_ref(self.org_id, user_id, self.ref_secret)
+        reqref = governance_request_ref(self.org_id, request_id, self.ref_secret)
+        actor_type = actor_context["actor_type"] if actor_context else "system"
+        actor_ref = actor_context["actor_ref"] if actor_context else None
+        idempotency_key = stable_id(
+            "idem",
+            f"{self.org_id}:user_erasure:{subref}:{reqref}",
+        )
+        purge_id = stable_id("purge", idempotency_key)
+        purge = self.storage.begin_purge_operation(
+            purge_id=purge_id,
+            idempotency_key=idempotency_key,
+            operation_type="user_erasure",
+            scope_type="user",
+            subject_ref=subref,
+            request_ref=reqref,
+        )
+        if purge.status == "complete":
+            barrier = self._completed_barrier_for_retry(
+                subject_ref=subref, purge_id=purge_id
+            )
+            if barrier.status != "erased":
+                raise ValueError(
+                    "Completed purge retry requires an erased subject barrier"
+                )
+            return UserEraseResult(
+                subject_ref=subref,
+                purge_id=purge_id,
+                status="complete",
+                deleted_counts=self._deleted_counts_from_targets(purge_id),
+                rebuilt_agent_playbook_ids=(
+                    self._rebuilt_agent_playbook_ids_from_targets(purge_id)
+                ),
+            )
+        try:
+            self.storage.begin_subject_erasure_barrier(subref, purge_id)
+            if not self.storage.purge_targets_prepared(purge_id):
+                self.storage.prepare_governance_erase_targets(
+                    purge_id,
+                    user_id,
+                )
+
+            if not self._delete_targets_complete(purge_id):
+                self.storage.apply_governance_user_data_delete(purge_id, user_id)
+            deleted_counts = self._deleted_counts_from_targets(purge_id)
+
+            rebuilt_agent_playbook_ids: list[int] = []
+            completed = self.storage.complete_subject_erasure_barrier_after_empty_check(
+                purge_id,
+                AuditEvent(
+                    org_id=self.org_id,
+                    actor_type=actor_type,
+                    actor_ref=actor_ref,
+                    operation="ERASE",
+                    entity_type="request",
+                    subject_ref=subref,
+                    request_ref=reqref,
+                    idempotency_key=purge_id,
+                    detail={
+                        "deleted_counts": deleted_counts,
+                        "rebuilt_agent_playbook_ids": rebuilt_agent_playbook_ids,
+                    },
+                ),
+            )
+        except Exception as exc:
+            with suppress(Exception):
+                self.storage.fail_subject_erasure_barrier(
+                    subref,
+                    purge_id,
+                    error_code="governance_erase_failed",
+                    error_detail=type(exc).__name__,
+                )
+            with suppress(Exception):
+                self.storage.fail_purge_operation(
+                    purge_id,
+                    error_code="governance_erase_failed",
+                    error_detail=type(exc).__name__,
+                )
+            raise
+        return UserEraseResult(
+            subject_ref=subref,
+            purge_id=purge_id,
+            status=completed.status,
+            deleted_counts=deleted_counts,
+            rebuilt_agent_playbook_ids=rebuilt_agent_playbook_ids,
+        )
+
+    def _assert_storage_ref_secret_matches(self) -> None:
+        storage_secret = get_governance_ref_secret()
+        if storage_secret != self.ref_secret:
+            raise RuntimeError(
+                "GovernanceService ref_secret must match REFLEXIO_GOVERNANCE_REF_SECRET "
+                "for governance operations"
+            )
+
+    def _completed_barrier_for_retry(
+        self, *, subject_ref: str, purge_id: str
+    ) -> SubjectWriteBarrier:
+        barrier = self.storage.get_subject_write_barrier(subject_ref)
+        if barrier is None or barrier.purge_id != purge_id:
+            raise ValueError(
+                "Completed purge retry requires the matching subject barrier"
+            )
+        return barrier
+
+    def _load_user_requests_and_sessions(
+        self, user_id: str
+    ) -> tuple[list[Any], list[dict[str, Any]]]:
+        requests: list[Any] = []
+        sessions_by_id: dict[str, list[str]] = {}
+        offset = 0
+        page_size = 1000
+
+        while True:
+            grouped_sessions = self.storage.get_sessions(
+                user_id=user_id,
+                top_k=page_size,
+                offset=offset,
+            )
+            returned_rows = 0
+            for session_id, rows in grouped_sessions.items():
+                returned_rows += len(rows)
+                request_ids = sessions_by_id.setdefault(session_id, [])
+                for row in rows:
+                    if row.request is None:
+                        continue
+                    requests.append(row.request)
+                    request_ids.append(row.request.request_id)
+            if returned_rows < page_size:
+                break
+            offset += page_size
+
+        sessions = [
+            {"session_id": session_id, "request_ids": request_ids}
+            for session_id, request_ids in sessions_by_id.items()
+        ]
+        return requests, sessions
+
+    def _iter_user_playbooks(self, user_id: str) -> list[Any]:
+        playbooks: list[Any] = []
+        offset = 0
+        while True:
+            page = self.storage.get_user_playbooks(
+                user_id=user_id,
+                limit=_USER_PLAYBOOK_PAGE_SIZE,
+                offset=offset,
+            )
+            playbooks.extend(page)
+            if len(page) < _USER_PLAYBOOK_PAGE_SIZE:
+                break
+            offset += _USER_PLAYBOOK_PAGE_SIZE
+        return playbooks
+
+    def _delete_targets_complete(self, purge_id: str) -> bool:
+        delete_targets = {
+            target.target_name: target
+            for target in self.storage.list_purge_targets(purge_id, phase="delete")
+        }
+        return all(
+            delete_targets.get(target_name) is not None
+            and delete_targets[target_name].status == "complete"
+            for target_name in _REQUIRED_DELETE_TARGET_NAMES
+        )
+
+    def _deleted_counts_from_targets(self, purge_id: str) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for target in self.storage.list_purge_targets(purge_id, phase="delete"):
+            result_key = _DELETE_TARGET_NAME_TO_RESULT_KEY.get(target.target_name)
+            if result_key is None:
+                continue
+            counts[result_key] = int(target.deleted_count)
+        return counts
+
+    def _rebuilt_agent_playbook_ids_from_targets(self, purge_id: str) -> list[int]:
+        return [
+            int(target.target_ref)
+            for target in self.storage.list_purge_targets(
+                purge_id,
+                phase="rebuild_without_erased_sources",
+            )
+            if (
+                target.target_name == "agent_playbook"
+                and target.target_ref
+                and target.status == "complete"
+            )
+        ]
+
+    def _rebuild_agent_playbooks(self, purge_id: str) -> list[int]:
+        rebuilt_ids: list[int] = []
+        for target in self.storage.list_purge_targets(
+            purge_id,
+            phase="rebuild_without_erased_sources",
+        ):
+            if target.target_name != "agent_playbook" or not target.target_ref:
+                continue
+            agent_playbook_id = int(target.target_ref)
+            if target.status == "complete":
+                rebuilt_ids.append(agent_playbook_id)
+                continue
+            remaining_source_windows = self._remaining_source_windows(target)
+            rebuild_fields = self._build_rebuilt_agent_playbook_fields(
+                remaining_source_windows
+            )
+            self.storage.apply_governance_agent_playbook_rebuild(
+                purge_id=purge_id,
+                agent_playbook_id=agent_playbook_id,
+                remaining_source_windows=remaining_source_windows,
+                content=rebuild_fields["content"],
+                trigger=rebuild_fields["trigger"],
+                rationale=rebuild_fields["rationale"],
+                blocking_issue=rebuild_fields["blocking_issue"],
+                expanded_terms=rebuild_fields["expanded_terms"],
+                tags=rebuild_fields["tags"],
+            )
+            rebuilt_ids.append(agent_playbook_id)
+        return rebuilt_ids
+
+    def _remaining_source_windows(
+        self,
+        target: PurgeOperationTarget,
+    ) -> list[dict[str, object]]:
+        detail = target.detail or {}
+        remaining = detail.get("remaining_source_windows", [])
+        if not isinstance(remaining, list):
+            raise ValueError("remaining_source_windows must be a list")
+        return remaining
+
+    def _build_rebuilt_agent_playbook_fields(
+        self,
+        remaining_source_windows: list[dict[str, object]],
+    ) -> dict[str, Any]:
+        user_playbook_ids: list[int] = []
+        for window in remaining_source_windows:
+            raw_user_playbook_id = window.get("user_playbook_id")
+            if isinstance(raw_user_playbook_id, int):
+                user_playbook_ids.append(raw_user_playbook_id)
+        playbooks_by_id = {
+            playbook.user_playbook_id: playbook
+            for playbook in self.storage.get_user_playbooks_by_ids_any_user(
+                user_playbook_ids
+            )
+            if playbook.user_playbook_id
+        }
+        remaining_playbooks = [
+            playbooks_by_id[user_playbook_id]
+            for user_playbook_id in user_playbook_ids
+            if user_playbook_id in playbooks_by_id
+        ]
+        return {
+            "content": self._join_non_empty_strings(
+                playbook.content for playbook in remaining_playbooks
+            ),
+            "trigger": self._join_non_empty_strings(
+                playbook.trigger for playbook in remaining_playbooks
+            ),
+            "rationale": self._join_non_empty_strings(
+                playbook.rationale for playbook in remaining_playbooks
+            ),
+            "blocking_issue": next(
+                (
+                    playbook.blocking_issue.model_dump()
+                    for playbook in remaining_playbooks
+                    if playbook.blocking_issue is not None
+                ),
+                None,
+            ),
+            "expanded_terms": self._join_non_empty_strings(
+                playbook.expanded_terms for playbook in remaining_playbooks
+            ),
+            "tags": self._merge_tags(remaining_playbooks),
+        }
+
+    def _join_non_empty_strings(self, values: Any) -> str | None:
+        joined = "\n".join(value for value in values if value)
+        return joined or None
+
+    def _merge_tags(self, playbooks: list[Any]) -> list[str] | None:
+        merged_tags: list[str] = []
+        for playbook in playbooks:
+            for tag in playbook.tags or []:
+                if tag not in merged_tags:
+                    merged_tags.append(tag)
+        return merged_tags or None

package/plugin/vendor/reflexio/reflexio/server/services/governance/subject_refs.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def _hmac_ref(prefix: str, raw: str, secret: str) -> str:
+    if not raw:
+        raise ValueError("raw value must be non-empty")
+    if not secret:
+        raise ValueError("secret must be non-empty")
+    digest = hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest()[:32]
+    return f"{prefix}_v1_{digest}"
+
+
+def subject_ref(raw: str, secret: str) -> str:
+    return _hmac_ref("subref", raw, secret)
+
+
+def actor_ref(raw: str, secret: str) -> str:
+    return _hmac_ref("actref", raw, secret)
+
+
+def request_ref(raw: str, secret: str) -> str:
+    return _hmac_ref("reqref", raw, secret)
+
+
+def stable_id(prefix: str, material: str) -> str:
+    if not prefix:
+        raise ValueError("prefix must be non-empty")
+    if not material:
+        raise ValueError("material must be non-empty")
+    digest = hashlib.sha256(material.encode()).hexdigest()[:32]
+    return f"{prefix}_{digest}"

package/plugin/vendor/reflexio/reflexio/server/services/lineage/gc_scheduler.py

@@ -1,10 +1,12 @@
 """Process-local scheduler for lineage tombstone garbage collection.
 
-The scheduler is per-org and config-gated: each tick it discovers every org,
-reads that org's ``lineage_gc`` config, and — if enabled — hard-deletes
-tombstone rows older than the configured grace window.  One org's failure
-never stalls the loop; errors are captured as Sentry anomalies and the
-scheduler continues to the next org.
+Startup is gated on ``lineage_gc.enabled`` (default on). Each tick evaluates
+every org independently and hard-deletes expired tombstones per that org's
+``lineage_gc`` config. One org's failure never stalls the loop; errors are
+captured as Sentry anomalies and the loop continues to the next org.
+
+Governance-retention reclamation is a premium concern handled by the enterprise
+GovernanceRetentionCapability (reflexio_ext), not here.
 """
 
 from __future__ import annotations
@@ -30,7 +32,7 @@ _ENTITY_TYPES = ("user_playbook", "agent_playbook", "profile")
 
 
 class LineageGCScheduler:
-    """Polling daemon that garbage-collects expired lineage tombstones per org."""
+    """Polling daemon that hard-deletes expired tombstones per org."""
 
     def __init__(
         self,
@@ -96,33 +98,32 @@ class LineageGCScheduler:
                 break
             try:
                 ctx = self.request_context_factory(org_id)
+                if ctx.storage is None:
+                    continue
                 cfg = ctx.configurator.get_config()
                 if not cfg.lineage_gc.enabled:
                     continue
-                if ctx.storage is None:
-                    continue
                 older_than_epoch = (
                     int(time.time())
                     - cfg.lineage_gc.tombstone_grace_window_days * 86400
                 )
-                total_deleted = 0
+                tombstone_deleted = 0
                 for entity_type in _ENTITY_TYPES:
-                    count = ctx.storage.gc_expired_tombstones(
+                    tombstone_deleted += ctx.storage.gc_expired_tombstones(
                         entity_type=entity_type,
                         older_than_epoch=older_than_epoch,
                     )
-                    total_deleted += count
-                if total_deleted:
+                if tombstone_deleted:
                     logger.info(
-                        "event=lineage_gc_tick org_id=%s deleted=%d",
+                        "event=lineage_gc_tick org_id=%s tombstone_deleted=%d",
                         org_id,
-                        total_deleted,
+                        tombstone_deleted,
                     )
-                if total_deleted > _HIGH_VOLUME_THRESHOLD:
+                if tombstone_deleted > _HIGH_VOLUME_THRESHOLD:
                     capture_anomaly(
                         "lineage.gc.high_volume",
                         org_id=org_id,
-                        count=total_deleted,
+                        count=tombstone_deleted,
                     )
             except Exception:
                 capture_anomaly("lineage.gc.run_failed", org_id=org_id)
@@ -147,10 +148,11 @@ def maybe_start_lineage_gc(
     *,
     bootstrap_org_id: str,
 ) -> LineageGCScheduler | None:
-    """Start the GC scheduler only when the bootstrap-org config enables it.
+    """Start the scheduler only when bootstrap config enables tombstone GC.
 
-    Off by default. Enablement criteria (must ALL hold before enabling for a
-    production org):
+    Startup requires bootstrap-org config to enable tombstone GC via
+    ``lineage_gc.enabled``. Tombstone-GC enablement criteria (must
+    ALL hold before enabling for a production org):
 
     1. **Mechanism**: GC ages tombstones by ``retired_at`` (the INTEGER epoch
        written at every tombstone write-path).  Rows with ``retired_at = NULL``
@@ -175,6 +177,30 @@ def maybe_start_lineage_gc(
     try:
         ctx = request_context_factory(bootstrap_org_id)
         cfg = ctx.configurator.get_config()
+
+        # Dead-knob warning: audit-event retention is an ENTERPRISE-only feature
+        # (handled by reflexio_ext GovernanceRetentionCapability). In an OSS-only
+        # deployment the knob is accepted but does nothing — warn loudly. Detected
+        # via the configurator class: enterprise swaps in EnterpriseConfigurator at
+        # construction, so the OSS DefaultConfigurator means "no enterprise here".
+        from reflexio.server.services.configurator.configurator import (  # noqa: PLC0415
+            DefaultConfigurator,
+            get_configurator_class,
+        )
+
+        gr = getattr(cfg, "governance_retention", None)
+        if (
+            gr is not None
+            and getattr(gr, "audit_events_retention_enabled", False)
+            and get_configurator_class() is DefaultConfigurator
+        ):
+            logger.warning(
+                "event=governance_retention_knob_ignored "
+                "audit_events_retention_enabled=True but this is an OSS-only "
+                "deployment — audit-event retention is an enterprise-only feature "
+                "and will NOT run here."
+            )
+
         if not cfg.lineage_gc.enabled:
             return None
     except Exception as exc:

package/plugin/vendor/reflexio/reflexio/server/services/playbook/README.md

@@ -16,7 +16,7 @@ Description: Playbook extraction, aggregation, and consolidation pipeline
 |------|---------|
 | `playbook_service_constants.py` | Prompt IDs for all playbook operations |
 | `playbook_service_utils.py` | Request dataclasses, Pydantic output schemas, message construction utilities |
-| `user_detail_stripping.py` | Optional aggregation-boundary interfaces and helpers for prompt-only user-detail normalization |
+| `aggregation_prompt_processing.py` | Optional aggregation-boundary interfaces and helpers for prompt preprocessing, contextual prompt guidance, and output post-processing |
 
 ## Architecture
 
@@ -49,6 +49,14 @@ Triggered manually via `/api/run_playbook_aggregation`. Clusters user playbooks
 **Key Methods**:
 - `get_clusters(user_playbooks, config)` - HDBSCAN/Agglomerative clustering on embeddings
 - `aggregate()` - Full aggregation pipeline with LLM-based consolidation
+
+**Optional prompt processing**: deployments can register an
+`AggregationPromptProcessor` via the `AGGREGATION_PROMPT_PROCESSOR` ServiceKey
+(`register_service`). The aggregator applies the processor only at the
+aggregation prompt boundary, carries an opaque per-cluster processing context,
+injects extra prompt guidance only when preprocessing changed prompt input, and
+post-processes generated outputs before storage or model-response logging.
+
 **Change Log**: The legacy `playbook_aggregation_change_logs` table is retired (Track B, 2026-06-24) — the aggregator no longer writes it. The change-log view is reconstructed on demand from `lineage_event` via `reconstruct_playbook_aggregation_change_log` (`lib/_agent_playbook.py`): each run emits `op=aggregate` events (the "added" side) and `status_change→superseded` events from the supersede calls (the "removed" side), grouped by the run's `request_id`. Per-row `updated` pairing is not reconstructed (`updated_agent_playbooks=[]`, a tolerated parity delta).
 
 **Clustering**: Embeds user playbooks -> HDBSCAN clustering -> falls back to Agglomerative if too few clusters