fred-core 3.4.2__tar.gz → 3.4.3__tar.gz

{fred_core-3.4.2 → fred_core-3.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-core
-Version: 3.4.2
+Version: 3.4.3
 Summary: Core shared utilities for Fred backends (config, storage, security, and runtime helpers).
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/__init__.py

@@ -43,16 +43,15 @@ from fred_core.filesystem.structures import (
     FilesystemResourceInfo,
     FilesystemResourceInfoResult,
 )
+from fred_core.logs.audit_log import emit_audit_log
 from fred_core.logs.base_log_store import BaseLogStore
-from fred_core.logs.log_setup import StoreEmitHandler, log_setup
+from fred_core.logs.log_setup import AUDIT_LOGGER_NAME, StoreEmitHandler, log_setup
+from fred_core.logs.log_store_factory import build_log_store
 from fred_core.logs.log_structures import (
     InMemoryLogStorageConfig,
+    LogCategory,
     LogEventDTO,
-    LogFilter,
-    LogQuery,
-    LogQueryResult,
     LogStorageConfig,
-    TailFileResponse,
 )
 from fred_core.logs.memory_log_store import RamLogStore
 from fred_core.logs.opensearch_log_store import OpenSearchLogStore
@@ -93,6 +92,7 @@ from fred_core.security.rebac.rebac_engine import (
     ORGANIZATION_ID,
     SERVICE_AGENT_ALLOWED_TEAM_PERMISSIONS,
     AgentPermission,
+    CapabilityPermission,
     DocumentPermission,
     OrganizationPermission,
     RebacDisabledResult,
@@ -134,14 +134,14 @@ from .users import (
 
 __all__ = [
     "BaseLogStore",
+    "LogCategory",
     "LogEventDTO",
-    "LogFilter",
-    "LogQuery",
-    "LogQueryResult",
     "OpenSearchLogStore",
+    "AUDIT_LOGGER_NAME",
     "RamLogStore",
     "StoreEmitHandler",
-    "TailFileResponse",
+    "build_log_store",
+    "emit_audit_log",
     "log_setup",
     "LogStorageConfig",
     "InMemoryLogStorageConfig",
@@ -191,6 +191,7 @@ __all__ = [
     "ORGANIZATION_ID",
     "AgentPermission",
     "OrganizationPermission",
+    "CapabilityPermission",
     "RebacPermission",
     "RebacDisabledResult",
     "RebacEngine",

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/common/__init__.py

@@ -21,6 +21,7 @@ from .config_loader import (
 from .env import coerce_bool, read_env_bool
 from .fastapi_handlers import register_exception_handlers
 from .lru_cache import ThreadSafeLRUCache
+from .resilient_sink import ResilientSinkStore
 from .structures import (
     BaseModelWithId,
     DuckdbStoreConfig,
@@ -60,6 +61,7 @@ __all__ = [
     "TeamId",
     "is_personal_team_id",
     "personal_team_id",
+    "ResilientSinkStore",
     "TemporalSchedulerConfig",
     "ThreadSafeLRUCache",
     "coerce_bool",

fred_core-3.4.3/fred_core/common/resilient_sink.py

@@ -0,0 +1,188 @@
+# Copyright Thales 2026
+#
+# 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.
+
+"""
+Resilient sink decorator — bounded queue + circuit breaker (issue #2009).
+
+Why this exists:
+- `BaseLogStore` and `BaseKPIStore` share the same write shape (`index_event`,
+  `bulk_index`) and the same contract note: "must not block or crash the
+  caller on outage." Nothing previously enforced that for the OpenSearch-
+  backed implementations — a down/slow cluster could block the calling
+  thread for a full HTTP timeout on every write, or (for `KPIWriter`, which
+  calls `index_event` synchronously and inline) let the exception propagate
+  into the business request that triggered the metric.
+- This wraps any such store: writes are handed to a single background
+  thread via a bounded queue (never blocks the caller — full queue means
+  drop, not wait) and short-circuited once the wrapped store has failed
+  repeatedly, so a known-down cluster stops being hammered from the hot path.
+
+How to use:
+- `ResilientSinkStore(wrapped_store)` — same write shape as the store it
+  wraps (`ensure_ready`/`index_event`/`bulk_index`), so it's a drop-in
+  decorator. `ensure_ready()` passes straight through: startup provisioning
+  is not this decorator's concern, only the steady-state write path is.
+  `query()` also passes through, best-effort, for wrapped stores that
+  support it (KPI stores do; the log store no longer does since Fred stopped
+  exposing its own log-query surface — OpenSearch Dashboards reads that
+  index directly instead).
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+import time
+from typing import Any, Protocol
+
+logger = logging.getLogger(__name__)
+
+
+# fmt: off
+class _WritableStore(Protocol):
+    def ensure_ready(self) -> None:
+        ...
+
+    def index_event(self, event: Any) -> None:
+        ...
+
+    def bulk_index(self, events: list[Any]) -> None:
+        ...
+# fmt: on
+
+
+class _CircuitBreaker:
+    """Opens after `failure_threshold` consecutive failures; half-opens
+    (allows one trial) after `cooldown_s`; closes again on a trial success."""
+
+    def __init__(self, *, failure_threshold: int, cooldown_s: float) -> None:
+        self._threshold = failure_threshold
+        self._cooldown_s = cooldown_s
+        self._consecutive_failures = 0
+        self._opened_at: float | None = None
+        self._lock = threading.Lock()
+
+    def allow(self) -> bool:
+        with self._lock:
+            if self._opened_at is None:
+                return True
+            return (time.monotonic() - self._opened_at) >= self._cooldown_s
+
+    def record_success(self) -> None:
+        with self._lock:
+            self._consecutive_failures = 0
+            self._opened_at = None
+
+    def record_failure(self) -> None:
+        with self._lock:
+            self._consecutive_failures += 1
+            if (
+                self._consecutive_failures >= self._threshold
+                and self._opened_at is None
+            ):
+                self._opened_at = time.monotonic()
+
+    @property
+    def is_open(self) -> bool:
+        with self._lock:
+            if self._opened_at is None:
+                return False
+            return (time.monotonic() - self._opened_at) < self._cooldown_s
+
+
+class ResilientSinkStore:
+    """Fail-open, non-blocking decorator around a `BaseLogStore`/`BaseKPIStore`.
+
+    Contract with the caller:
+    - `index_event`/`bulk_index` never raise and never block beyond a
+      non-blocking queue put.
+    - A full queue (sink can't keep up) or an open circuit (sink is known
+      down) both mean "drop the event", counted separately for diagnostics.
+    """
+
+    def __init__(
+        self,
+        wrapped: _WritableStore,
+        *,
+        queue_size: int = 1000,
+        failure_threshold: int = 5,
+        cooldown_s: float = 30.0,
+    ) -> None:
+        self._wrapped = wrapped
+        self._queue: queue.Queue[Any] = queue.Queue(maxsize=queue_size)
+        self._breaker = _CircuitBreaker(
+            failure_threshold=failure_threshold, cooldown_s=cooldown_s
+        )
+        self.dropped_queue_full = 0
+        self.dropped_circuit_open = 0
+        self._thread = threading.Thread(
+            target=self._worker, name="resilient-sink-writer", daemon=True
+        )
+        self._thread.start()
+
+    @property
+    def wrapped(self) -> _WritableStore:
+        """The underlying store — exposed read-only for introspection/tests."""
+        return self._wrapped
+
+    # -- passthrough: not this decorator's concern -----------------------------
+    def ensure_ready(self) -> None:
+        self._wrapped.ensure_ready()
+
+    def query(self, q: Any) -> Any:
+        """Best-effort passthrough for wrapped stores that support querying
+        (KPI stores do; the log store no longer does)."""
+        query_fn = getattr(self._wrapped, "query", None)
+        if query_fn is None:
+            raise AttributeError(
+                f"{type(self._wrapped).__name__} does not support query()"
+            )
+        return query_fn(q)
+
+    # -- writes: bounded, non-blocking, fail-open ------------------------------
+    def index_event(self, event: Any) -> None:
+        if not self._breaker.allow():
+            self.dropped_circuit_open += 1
+            return
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:
+            self.dropped_queue_full += 1
+
+    def bulk_index(self, events: list[Any]) -> None:
+        for event in events:
+            self.index_event(event)
+
+    # -- background worker ------------------------------------------------------
+    def _worker(self) -> None:
+        while True:
+            event = self._queue.get()
+            try:
+                if not self._breaker.allow():
+                    self.dropped_circuit_open += 1
+                    continue
+                try:
+                    self._wrapped.index_event(event)
+                    self._breaker.record_success()
+                except Exception:
+                    self._breaker.record_failure()
+                    logger.warning(
+                        "Resilient sink write failed; dropping event", exc_info=True
+                    )
+            finally:
+                self._queue.task_done()
+
+
+__all__ = ["ResilientSinkStore"]

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/kpi/kpi_factory.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 import logging
 from typing import Optional
 
+from fred_core.common.resilient_sink import ResilientSinkStore
 from fred_core.common.structures import KpiObservabilityConfig, OpenSearchStoreConfig
 from fred_core.kpi.base_kpi_store import BaseKPIStore
 from fred_core.kpi.base_kpi_writer import BaseKPIWriter
@@ -65,13 +66,19 @@ def build_kpi_writer(
                 "— falling back to log sink"
             )
         else:
-            base_store = OpenSearchKPIStore(
-                host=opensearch_config.host,
-                username=opensearch_config.username,
-                password=opensearch_config.password,
-                secure=opensearch_config.secure,
-                verify_certs=opensearch_config.verify_certs,
-                index=os_cfg.index,
+            # ResilientSinkStore: writes are handed to a background thread via
+            # a bounded queue and short-circuited on repeated failure, so a
+            # slow/down OpenSearch cluster can never block or fail the
+            # business request that triggered a metric (issue #2009).
+            base_store = ResilientSinkStore(  # type: ignore[assignment]
+                OpenSearchKPIStore(
+                    host=opensearch_config.host,
+                    username=opensearch_config.username,
+                    password=opensearch_config.password,
+                    secure=opensearch_config.secure,
+                    verify_certs=opensearch_config.verify_certs,
+                    index=os_cfg.index,
+                )
             )
 
     if base_store is None and log_cfg.enabled:

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/kpi/kpi_writer.py

@@ -36,10 +36,11 @@ from fred_core.kpi.kpi_writer_structures import (
     Quantities,
     Trace,
 )
+from fred_core.logs.log_setup import KPI_LOGGER_NAME
 from fred_core.security.structure import KeycloakUser
 
 logger = logging.getLogger(__name__)
-summary_logger = logging.getLogger("KPI")
+summary_logger = logging.getLogger(KPI_LOGGER_NAME)
 
 
 @dataclass
@@ -209,7 +210,15 @@ class KPIWriter(BaseKPIWriter):
             trace=(Trace(**trace) if trace else None),
         )
         self._record_summary(event)
-        self.store.index_event(event)
+        # Fail-open: a KPI sink outage (e.g. OpenSearch down) must never break
+        # or propagate into the business request that triggered this metric —
+        # see docs/swift/platform/OBSERVABILITY-AND-AUDIT.md §6.
+        try:
+            self.store.index_event(event)
+        except Exception:
+            logger.warning(
+                "KPI store write failed; dropping event %r", name, exc_info=True
+            )
 
     # ---- simple helpers ------------------------------------------------------
     def count(

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/kpi/log_kpi_store.py

@@ -30,6 +30,7 @@ _STRUCTURED_EVENT_NAMES = frozenset(
         "agent.turn_completed",
         "agent.turn_error_total",
         "agent.tool_failed_total",
+        "agent.tool_latency_ms",
     }
 )
 

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/kpi/prometheus_kpi_store.py

@@ -26,11 +26,46 @@ from fred_core.kpi.kpi_writer_structures import KPIEvent
 
 logger = logging.getLogger(__name__)
 
-PROMETHEUS_HIGH_CARDINALITY_LABELS = frozenset(
+# Explicit allow-list, not a deny-list: Prometheus/Grafana serves platform
+# operators, not team- or user-scoped product analytics (that's OBSERV-02's
+# job, ReBAC-scoped, backed by OpenSearch — see
+# docs/swift/platform/OBSERVABILITY-AND-AUDIT.md §3.1). A deny-list only
+# protects against the specific fields someone remembered to list; any new
+# per-call or per-user dim added to a KPI event later would silently leak
+# into a scraped, platform-wide-visible label unless it's caught here too.
+# An allow-list fails safe: a new dim needs a deliberate decision to appear
+# as a label at all.
+#
+# Deliberately excluded, and why:
+# - user_id, session_id, exchange_id: direct/pseudonymous identity.
+# - team_id, agent_instance_id, agent_instance_name, agent_id: "usage by
+#   team/agent instance" is a product-analytics question already answered,
+#   correctly scoped, by OBSERV-02's presets — duplicating it here would
+#   mean a second, unsynchronized access-control model for the same fact.
+# - trace_id, correlation_id, checkpoint_id, doc_uid, scope_id: unique per
+#   call/resource, no aggregate value as a label, and a pivot vector from a
+#   wide-audience dashboard back into raw logs.
+PROMETHEUS_ALLOWED_LABELS = frozenset(
     {
-        "session_id",
-        "user_id",
-        "exchange_id",
+        "tool_name",
+        "status",
+        "error_code",
+        "exception_type",
+        "http_status",
+        "template_agent_id",
+        "model",
+        "model_name",
+        "finish_reason",
+        "runtime_id",
+        "source_runtime_id",
+        "service",
+        "env",
+        "cluster",
+        "route",
+        "method",
+        "actor_type",
+        "file_type",
+        "agent_step",
     }
 )
 
@@ -54,21 +89,19 @@ def _prometheus_label_dims(event: KPIEvent) -> Dict[str, str]:
     Return the bounded subset of KPI dims that may become Prometheus labels.
 
     Why this exists:
-    - KPI events can carry per-user/per-turn identifiers for structured stores,
-      but Prometheus labels must stay low-cardinality.
+    - KPI events can carry per-user/per-team/per-turn identifiers for
+      structured stores (OpenSearch), but Prometheus labels must stay both
+      low-cardinality and free of anything RGPD-relevant — see
+      PROMETHEUS_ALLOWED_LABELS above for the reasoning per field.
 
     How to use it:
     - call before resolving or emitting Prometheus labels; do not mutate the
       original event because delegates such as OpenSearch still need full dims.
-
-    Example:
-    - `_prometheus_label_dims(event)` drops `session_id`, `user_id`, and
-      `exchange_id` from the label candidate set.
     """
     return {
         k: str(v)
         for k, v in (event.dims or {}).items()
-        if v is not None and k not in PROMETHEUS_HIGH_CARDINALITY_LABELS
+        if v is not None and k in PROMETHEUS_ALLOWED_LABELS
     }
 
 

fred_core-3.4.3/fred_core/logs/audit_log.py

@@ -0,0 +1,66 @@
+# Copyright Thales 2026
+#
+# 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.
+
+"""
+Shared emission primitive for the security/audit logger.
+
+Why this exists:
+- Every audit-worthy event (an authorization decision, a tool invocation) needs
+  to land as one structured line on `AUDIT_LOGGER_NAME`, formatted the same way,
+  so a downstream log pipeline can select the whole family on one field.
+- Application layers may additionally keep their own short-lived view (e.g. an
+  in-memory ring buffer backing an admin UI) — that is layered on top of this,
+  not a replacement for it. This function only ever writes the log line.
+
+How to use it:
+- call with a stable `event_name` (e.g. "agent.tool.invocation.completed") and
+  whatever identifying/correlation fields are available; omit fields that are
+  not, never fabricate them.
+- never pass tool arguments, tool results, prompts, documents, tokens, or any
+  other secret — this channel is audit-grade and is expected to be routed to
+  long-retention storage.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fred_core.logs.log_setup import AUDIT_LOGGER_NAME
+
+
+def emit_audit_log(
+    event_name: str,
+    level: str = "info",
+    /,
+    **fields: object,
+) -> None:
+    """Write one structured line to the shared security/audit logger.
+
+    `event_name` and `level` are positional-only so that spreading a caller's
+    dims dict via `**fields` (see ContextAwareTool._emit_tool_call_audit) can
+    never collide with — or be mistaken by a type checker for — these two
+    fixed parameters.
+
+    `fields` becomes the JSON payload's `extra` object once CompactJsonFormatter
+    formats the record (see log_setup.py). `None` values are dropped rather than
+    serialized, so a caller can pass every optional field unconditionally.
+    """
+    payload: dict[str, object] = {"audit_event": event_name}
+    payload.update({k: v for k, v in fields.items() if v is not None})
+    logger = logging.getLogger(AUDIT_LOGGER_NAME)
+    log_fn = getattr(logger, level)
+    log_fn("[SECURITY] %s", event_name, extra=payload)
+
+
+__all__ = ["emit_audit_log", "AUDIT_LOGGER_NAME"]

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/logs/base_log_store.py

@@ -22,8 +22,9 @@ Why this exists in Fred:
 - We want **one emission API** (logging handler / writer) that can plug into
   **many backends** (OpenSearch, in-memory ring for dev, CSV for tests, etc.).
 - Backends differ in capabilities and SLOs; we keep the interface minimal but
-  sufficient: readiness, single-event ingest, bulk ingest, and a *best-effort*
-  query API for the monitoring UI.
+  sufficient: readiness, single-event ingest, and bulk ingest. Reading these
+  logs back is done directly against the backing store (OpenSearch Dashboards),
+  not through Fred — this module is write-path only.
 
 Key ideas:
 - `BaseLogStore` is a `Protocol` (static duck-typing) → implementations don’t
@@ -35,14 +36,14 @@ from __future__ import annotations
 
 from typing import Protocol
 
-from fred_core.logs.log_structures import LogEventDTO, LogQuery, LogQueryResult
+from fred_core.logs.log_structures import LogEventDTO
 
 
 class BaseLogStore(Protocol):
-    """Abstract Log store API used by the logging pipeline and monitoring UI.
+    """Abstract Log store API used by the logging pipeline.
 
     Architectural role:
-    - Decouple **log emission** from **physical storage & query**.
+    - Decouple **log emission** from **physical storage**.
     - Keep the contract intentionally small so backends remain easy to implement.
     - Allow services to boot even if the store is slow to initialize
       (callers may handle failures without crashing business logic).
@@ -50,8 +51,6 @@ class BaseLogStore(Protocol):
     Implementation notes:
     - `index_event` must be non-blocking or bounded in latency (hot paths).
     - `bulk_index` is for throughput (batching) when the caller can coalesce.
-    - `query` is intentionally lightweight: time range + simple filters
-      for the built-in console; not meant to replace a full SIEM.
     """
 
     def ensure_ready(self) -> None:
@@ -80,12 +79,3 @@ class BaseLogStore(Protocol):
         - Caller decides batching cadence; store optimizes the write path.
         """
         ...
-
-    def query(self, q: LogQuery) -> LogQueryResult:
-        """Run a best-effort query over stored logs.
-
-        Design:
-        - Used by the Fred monitoring UI (time window, filters, limit/order).
-        - Implementations may support a subset of filters; document trade-offs.
-        """
-        ...

{fred_core-3.4.2 → fred_core-3.4.3}/fred_core/logs/log_setup.py

@@ -23,6 +23,7 @@ import threading
 from typing import Any, Optional
 
 from fred_core.logs.base_log_store import BaseLogStore, LogEventDTO
+from fred_core.logs.log_structures import LogCategory
 
 try:
     from rich.logging import RichHandler
@@ -31,12 +32,33 @@ except Exception:  # optional in prod images
 
 logger = logging.getLogger(__name__)
 
+# Single source of truth for the security/audit logger name — shared by
+# log_setup() (which gives it its dedicated JSON stdout path, see below) and
+# every call site that emits an audit event (authz decisions, tool-call
+# invocations), so both sides can never drift out of sync on the string.
+AUDIT_LOGGER_NAME = "fred.security.audit"
+
+# Single source of truth for the reserved KPI-summary logger name — shared by
+# StoreEmitHandler (which derives LogEventDTO.category from it) and
+# kpi_writer.py's periodic rollup lines, so both sides can never drift out of
+# sync on the string (mirrors AUDIT_LOGGER_NAME above).
+KPI_LOGGER_NAME = "KPI"
+
 LEVEL_MAP = {
     "DETAIL": "DEBUG",
     "TRACE": "DEBUG",
 }
 
 
+# Attributes a fresh LogRecord carries by default — anything else on a record's
+# __dict__ came from a caller's `extra={...}` and should be surfaced, not dropped.
+# Introspected from a throwaway record instead of hand-maintained so it tracks
+# whatever the running Python version's logging module actually sets.
+_STANDARD_LOG_RECORD_ATTRS = frozenset(
+    vars(logging.LogRecord("", 0, "", 0, "", (), None)).keys()
+) | {"message", "asctime"}
+
+
 # --- JSON formatter kept tiny and portable ---
 class CompactJsonFormatter(logging.Formatter):
     def __init__(self, service_name: str):
@@ -55,7 +77,14 @@ class CompactJsonFormatter(logging.Formatter):
             "service": self.service,
             "msg": record.getMessage(),
         }
-        return json.dumps(base, ensure_ascii=False)
+        extra = {
+            k: v
+            for k, v in record.__dict__.items()
+            if k not in _STANDARD_LOG_RECORD_ATTRS
+        }
+        if extra:
+            base["extra"] = extra
+        return json.dumps(base, ensure_ascii=False, default=str)
 
 
 # --- Minimal handler that pushes to a BaseLogStore (or a lazy getter) ---
@@ -71,6 +100,13 @@ class StoreEmitHandler(logging.Handler):
         self._tls = threading.local()
 
     def emit(self, record: logging.LogRecord) -> None:
+        # Hard drop, independent of the audit logger's own propagate=False:
+        # real security/audit events (fred.security.audit) must never land in
+        # the generic app-log store, even if a future refactor accidentally
+        # reattaches a handler or flips propagate to True (see
+        # docs/swift/platform/OBSERVABILITY-AND-AUDIT.md §6).
+        if record.name == AUDIT_LOGGER_NAME:
+            return
         if getattr(self._tls, "in_emit", False):
             return
         self._tls.in_emit = True
@@ -88,6 +124,15 @@ class StoreEmitHandler(logging.Handler):
             else:
                 mapped_level = record.levelname
 
+            # Closed, structural classification — derived from the LogRecord's
+            # own logger identity, never from message text (a message that
+            # happens to contain "[KPI]" does not become that category; only
+            # a record actually emitted on the reserved KPI logger does). See
+            # docs/swift/platform/OBSERVABILITY-AND-AUDIT.md §6.
+            category: LogCategory = (
+                "kpi" if record.name == KPI_LOGGER_NAME else "application"
+            )
+
             e = LogEventDTO(
                 ts=payload.get("ts", record.created) if payload else record.created,
                 level=mapped_level,  # type: ignore
@@ -101,6 +146,7 @@ class StoreEmitHandler(logging.Handler):
                 if payload
                 else self.service,
                 extra=payload.get("extra") if payload else None,
+                category=category,
             )
 
             # Never block the app on logging:
@@ -230,8 +276,13 @@ def log_setup(
 
     # 1) Human console (Rich or plain)
     formatter = logging.Formatter(
-        # Include process ID, task name, and thread name for concurrency diagnostics.
-        fmt="%(asctime)s | %(levelname)s | [pid=%(process)d %(threadName)s/%(task_name)s] | %(message)s",
+        # Include process ID, task name, thread name, and the logger's own
+        # dotted module name for concurrency diagnostics *and* provenance —
+        # %(name)s is why a message needs no hand-invented [TAG] to say where
+        # it came from. Reserve bracket prefixes in message text for the two
+        # real routed channels ([SECURITY] via emit_audit_log, [KPI] via
+        # logging.getLogger("KPI")); everything else should rely on this.
+        fmt="%(asctime)s | %(levelname)s | [pid=%(process)d %(threadName)s/%(task_name)s] | %(name)s | %(message)s",
         datefmt="%Y-%m-%d %H:%M:%S",
     )
     if use_rich and RichHandler is not None:
@@ -306,4 +357,19 @@ def log_setup(
             lg.propagate = True  # forward to our root handlers
         logging.getLogger("uvicorn.error").addFilter(UvicornWebsocketNoiseFilter())
 
+    # 5) Dedicated single-line JSON path for the security/audit logger.
+    # Structured audit events (authz decisions, tool-call invocations) must
+    # reach stdout as valid, self-contained JSON so a platform-native log
+    # pipeline (Cloud Logging or equivalent) can parse and route them without
+    # scraping free text — the human-readable console formatter above is not
+    # JSON. propagate=False keeps an audit line from also printing through
+    # that console handler.
+    audit_logger = logging.getLogger(AUDIT_LOGGER_NAME)
+    audit_logger.handlers.clear()
+    audit_handler = logging.StreamHandler()
+    audit_handler.setFormatter(CompactJsonFormatter(service_name))
+    audit_logger.addHandler(audit_handler)
+    audit_logger.setLevel(log_level.upper())
+    audit_logger.propagate = False
+
     setattr(root, marker, True)