3tears-agent-audit 0.14.0__tar.gz

3tears_agent_audit-0.14.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Claude Code local state
+.claude/
+
+# prawduct session evidence (local governance artifacts, never shipped)
+.prawduct/
+
+# macOS folder metadata
+.DS_Store

3tears_agent_audit-0.14.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

3tears_agent_audit-0.14.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: 3tears-agent-audit
+Version: 0.14.0
+Summary: unified audit envelope + fire-and-forget publish helper for the 3tears platform
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears-nats
+Requires-Dist: 3tears-observe
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# 3tears-agent-audit
+
+Unified audit envelope + fire-and-forget publish helper for the 3tears platform.
+
+## Purpose
+
+Single `AuditEvent` envelope + single `publish_audit` helper used by every
+domain (workspace, rbac, memory, custom tools) so the audit pipeline is
+one subject tree, one consumer, one table, one admin query API. Replaces
+domain-specific envelopes (`WorkspaceAuditEnvelope`,
+`RbacAuditEnvelope`) that produced slightly-different wire shapes per domain
+and made cross-domain audit queries require a UNION.
+
+The package is pure Python with no NATS consumer code and no Postgres code.
+Publish is the only direction: a consumer-side audit consumer owns
+persistence to the audit events table.
+
+## Public API
+
+```python
+from threetears.agent.audit import AuditEvent, publish_audit
+```
+
+- `AuditEvent` -- pydantic `BaseModel` with `extra='forbid'`, timezone-aware
+  `timestamp` validator, closed `event_type` string family (dotted verb,
+  e.g. `workspace.fs_write`, `rbac.assignment.create`). All common identity
+  fields are typed columns on the envelope; event-type-specific extras live
+  in `details: dict[str, Any]`.
+- `publish_audit(event, nats_client, namespace)` -- fire-and-forget async
+  helper. Serializes the envelope via `model_dump_json()` and awaits one
+  `nats_client.publish` on `{namespace}.audit.{event_type}`. On any publish
+  failure logs at WARN and returns; never raises.
+
+## Design commitments
+
+- **Fire-and-forget.** Audit publish failures must never break the producing
+  call. The helper catches every exception, logs at WARN, and returns.
+- **Typed wire contract.** `extra='forbid'` + timezone-aware validator catch
+  publisher-side drift at construction time, not at the consumer's decode.
+- **No domain-specific envelope types.** Every domain publishes the same
+  model; `event_type` conveys the domain.
+- **No dual-emit.** There is no legacy envelope the consumer still accepts in
+  parallel. Emission sites migrate in the same PR that deletes the legacy
+  envelope module.
+
+## Subject naming
+
+`{namespace}.audit.{event_type}` where `event_type` is the dotted event
+name (e.g. `{namespace}.audit.workspace.fs_write`). The consumer
+subscribes to `{namespace}.audit.>` so new event types route automatically
+without consumer-side changes.

3tears_agent_audit-0.14.0/README.md

@@ -0,0 +1,51 @@
+# 3tears-agent-audit
+
+Unified audit envelope + fire-and-forget publish helper for the 3tears platform.
+
+## Purpose
+
+Single `AuditEvent` envelope + single `publish_audit` helper used by every
+domain (workspace, rbac, memory, custom tools) so the audit pipeline is
+one subject tree, one consumer, one table, one admin query API. Replaces
+domain-specific envelopes (`WorkspaceAuditEnvelope`,
+`RbacAuditEnvelope`) that produced slightly-different wire shapes per domain
+and made cross-domain audit queries require a UNION.
+
+The package is pure Python with no NATS consumer code and no Postgres code.
+Publish is the only direction: a consumer-side audit consumer owns
+persistence to the audit events table.
+
+## Public API
+
+```python
+from threetears.agent.audit import AuditEvent, publish_audit
+```
+
+- `AuditEvent` -- pydantic `BaseModel` with `extra='forbid'`, timezone-aware
+  `timestamp` validator, closed `event_type` string family (dotted verb,
+  e.g. `workspace.fs_write`, `rbac.assignment.create`). All common identity
+  fields are typed columns on the envelope; event-type-specific extras live
+  in `details: dict[str, Any]`.
+- `publish_audit(event, nats_client, namespace)` -- fire-and-forget async
+  helper. Serializes the envelope via `model_dump_json()` and awaits one
+  `nats_client.publish` on `{namespace}.audit.{event_type}`. On any publish
+  failure logs at WARN and returns; never raises.
+
+## Design commitments
+
+- **Fire-and-forget.** Audit publish failures must never break the producing
+  call. The helper catches every exception, logs at WARN, and returns.
+- **Typed wire contract.** `extra='forbid'` + timezone-aware validator catch
+  publisher-side drift at construction time, not at the consumer's decode.
+- **No domain-specific envelope types.** Every domain publishes the same
+  model; `event_type` conveys the domain.
+- **No dual-emit.** There is no legacy envelope the consumer still accepts in
+  parallel. Emission sites migrate in the same PR that deletes the legacy
+  envelope module.
+
+## Subject naming
+
+`{namespace}.audit.{event_type}` where `event_type` is the dotted event
+name (e.g. `{namespace}.audit.workspace.fs_write`). The consumer
+subscribes to `{namespace}.audit.>` so new event types route automatically
+without consumer-side changes.

3tears_agent_audit-0.14.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "3tears-agent-audit"
+version = "0.14.0"
+description = "unified audit envelope + fire-and-forget publish helper for the 3tears platform"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [{name = "pace"}]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: System :: Logging",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "3tears-nats",
+    "3tears-observe",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Repository = "https://github.com/pacepace/3tears"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threetears"]
+
+[tool.uv.sources]
+3tears-nats = { workspace = true }
+3tears-observe = { workspace = true }
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+packages = ["threetears.agent.audit"]
+explicit_package_bases = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "integration: integration tests requiring docker or real infra",
+]

3tears_agent_audit-0.14.0/src/threetears/agent/audit/__init__.py

@@ -0,0 +1,38 @@
+"""unified audit envelope + publish helper for the 3tears platform.
+
+single :class:`AuditEvent` + :func:`publish_audit` shared by every
+producing domain (workspace tools, hub rbac endpoints, agent memory,
+custom tools). the hub-side ``unified_audit_consumer`` subscribes to
+``{namespace}.audit.>`` and persists every event to
+``platform_audit.audit_events`` without a domain-specific consumer.
+
+produced by ``audit-task-01``; supersedes
+:class:`threetears.agent.workspace.audit.WorkspaceAuditEnvelope` and
+:class:`threetears.agent.acl.audit.RbacAuditEnvelope` (both deleted in
+the same shard).
+"""
+
+from __future__ import annotations
+
+from threetears.agent.audit.envelope import AuditEvent
+from threetears.agent.audit.publish import publish_audit
+
+# Version derived from pyproject.toml so the metadata is the single
+# source of truth -- a future release that bumps pyproject without
+# updating ``__init__.py`` can't drift the runtime ``__version__``.
+# The except guard handles the rare case where the package isn't
+# installed via importlib.metadata (e.g. running directly from a
+# checked-out source tree without ``uv sync``); the fallback keeps
+# imports working but reports ``unknown`` rather than crashing.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("3tears-agent-audit")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"
+
+__all__ = [
+    "AuditEvent",
+    "publish_audit",
+]

3tears_agent_audit-0.14.0/src/threetears/agent/audit/envelope.py

@@ -0,0 +1,217 @@
+"""unified audit envelope for every domain on the 3tears platform.
+
+the pre-audit-task-01 world had per-domain envelope types
+(:class:`WorkspaceAuditEnvelope`, :class:`RbacAuditEnvelope`, etc.)
+each on a different NATS subject with a slightly different wire shape.
+cross-domain audit queries paid for this with UNIONs across lightly-
+different schemas and the admin query API had to special-case each
+domain. audit-task-01 collapses all of it into one envelope, one
+publish helper, one subject tree, one consumer, one table.
+
+the envelope below is the single wire contract. every domain
+(:mod:`threetears.agent.workspace.tools.*`, hub rbac endpoints, agent
+memory, user tools) builds an :class:`AuditEvent` and hands it to
+:func:`publish_audit`. the hub-side ``unified_audit_consumer``
+subscribes to ``{namespace}.audit.>`` and persists to
+``platform_audit.audit_events``.
+
+anti-drift guarantees:
+
+- ``model_config`` uses ``extra='forbid'`` -- any stray field on the
+  wire fails parse loudly. a miswired publisher surfaces at construct
+  time rather than silently dropping the field.
+- ``timestamp`` must be timezone-aware UTC; a validator rejects naive
+  datetimes with a clear message.
+- ``event_type`` uses the dotted ``{domain}.{verb}[.{sub_verb}]``
+  convention (e.g. ``workspace.fs_write``, ``rbac.assignment.create``,
+  ``rbac.introspect.explain``). it is an open ``str`` rather than a
+  closed ``Literal``: the envelope intentionally does not gate new
+  event types at the wire layer because new domains (memory, custom
+  tools) must be able to publish without editing this module. per-
+  domain closed enums belong at the producer site, not on the shared
+  envelope.
+- ``details: dict[str, Any]`` is the escape hatch for event-type-
+  specific extras. commonly-queried fields (actor, resource, action,
+  outcome) are typed columns so admin queries don't JSONB-parse on
+  every row.
+
+identity axes on the envelope:
+
+- ``actor_user_id`` -- the human (or service account) whose action
+  triggered the event; the load-bearing "who did this?" field.
+- ``calling_agent_id`` -- the agent whose pod ran the tool. equal to
+  ``owner_agent_id`` for owner-path calls; differs under cross-agent
+  sharing.
+- ``owner_agent_id`` -- the agent that owns the resource being
+  touched. sourced from the resource's namespace row.
+- ``customer_id`` -- the owning customer. ``None`` only for
+  platform-scoped events (e.g. platform role CRUD).
+- ``resource_namespace_id`` -- the resource's namespace row id. every
+  resource on the platform is a namespace post-workspace-task-19, so
+  one column answers "whose data?" across every domain.
+- ``resource_namespace_type`` -- short taxonomy tag (``workspace`` /
+  ``group`` / ``role`` / ``assignment`` / ``introspection`` / ...).
+  matches the ``namespaces.namespace_type`` taxonomy.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+__all__ = ["AuditEvent"]
+
+
+class AuditEvent(BaseModel):
+    """typed wire-format envelope for every platform audit event.
+
+    single canonical envelope shared by every producing domain and
+    the hub-side ``unified_audit_consumer``. built on the producer
+    side (workspace tool, rbac endpoint, memory subsystem, custom
+    tool) and handed to :func:`publish_audit`. decoded on the hub
+    side from ``{namespace}.audit.>`` by the unified consumer.
+
+    :param id: envelope identity (uuid7 time-ordered); doubles as the
+        audit row primary key when the consumer persists it
+    :ptype id: UUID
+    :param timestamp: timezone-aware UTC instant the event occurred
+    :ptype timestamp: datetime
+    :param event_type: dotted event family, e.g. ``workspace.fs_write``,
+        ``rbac.assignment.create``, ``rbac.introspect.explain``. used
+        as the last segment of the NATS subject and as the primary
+        ``event_type`` column on ``audit_events``
+    :ptype event_type: str
+    :param actor_user_id: human / service-account actor; ``None`` for
+        system-triggered events (e.g. scheduled retention)
+    :ptype actor_user_id: UUID | None
+    :param calling_agent_id: agent whose pod ran the tool; ``None`` for
+        events emitted from the hub directly (e.g. rbac admin endpoints)
+    :ptype calling_agent_id: UUID | None
+    :param owner_agent_id: agent that owns the resource being touched;
+        ``None`` for platform-scoped events
+    :ptype owner_agent_id: UUID | None
+    :param customer_id: owning customer; ``None`` only for platform-
+        scoped events (platform role CRUD, platform-scoped groups)
+    :ptype customer_id: UUID | None
+    :param resource_namespace_id: namespace row id of the resource;
+        ``None`` for events whose subject is not a single namespace
+        (introspection queries, cross-resource dry-runs)
+    :ptype resource_namespace_id: UUID | None
+    :param resource_namespace_type: short taxonomy tag matching
+        ``namespaces.namespace_type`` (``workspace`` / ``group`` /
+        ``role`` / ``assignment`` / ``introspection`` / ...). ``None``
+        when ``resource_namespace_id`` is ``None``
+    :ptype resource_namespace_type: str | None
+    :param action: short verb (``read`` / ``write`` / ``create`` /
+        ``update`` / ``delete`` / ``add_member`` / ``remove_member`` /
+        ``explain`` / ...). kept open-set so new domains don't edit
+        the envelope module
+    :ptype action: str
+    :param outcome: one of ``success``, ``failure``, ``error``. tool-
+        dispatch auto-emission stamps this based on the handler return
+        path; explicit emissions pass ``success`` by convention unless
+        they know otherwise
+    :ptype outcome: str
+    :param correlation_id: request / tool-call correlation UUID; used
+        with ``event_type`` as the idempotency key for at-least-once
+        NATS redelivery
+    :ptype correlation_id: UUID
+    :param conversation_id: conversation UUID when the event was
+        emitted on behalf of a user-facing conversation (agent-tools
+        baseline emission, memory writes, context save). ``None`` for
+        platform-scoped events (rbac admin endpoints, scheduled
+        retention) and for hub-direct calls without a conversation.
+        added in data-layer-task-01 sub-task 5: the ``audit_events``
+        table already carries the column (added in v054 partition
+        primitive); the envelope now propagates it from
+        :class:`CallContext` into the persisted row so admin queries
+        can filter audit trails per conversation
+    :ptype conversation_id: UUID | None
+    :param details: event-type-specific structured payload (sha/bytes/
+        version for fs_write; added_member_id for group.member.add;
+        etc.). admin queries must not depend on JSONB fields for hot
+        paths
+    :ptype details: dict[str, Any]
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: UUID
+    timestamp: datetime
+    event_type: str
+    actor_user_id: UUID | None = None
+    calling_agent_id: UUID | None = None
+    owner_agent_id: UUID | None = None
+    customer_id: UUID | None = None
+    resource_namespace_id: UUID | None = None
+    resource_namespace_type: str | None = None
+    action: str
+    outcome: str = "success"
+    correlation_id: UUID
+    conversation_id: UUID | None = None
+    details: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("timestamp")
+    @classmethod
+    def _require_timezone_aware(cls, value: datetime) -> datetime:
+        """reject naive datetimes -- every audit envelope is UTC-aware.
+
+        :param value: parsed datetime
+        :ptype value: datetime
+        :return: the same datetime when it carries a tzinfo
+        :rtype: datetime
+        :raises ValueError: when the input is naive
+        """
+        if value.tzinfo is None:
+            raise ValueError(
+                "AuditEvent.timestamp must be timezone-aware (UTC); received a naive datetime",
+            )
+        return value
+
+    @field_validator("outcome")
+    @classmethod
+    def _require_known_outcome(cls, value: str) -> str:
+        """restrict ``outcome`` to the three recognised values.
+
+        the closed set keeps the admin query API's outcome filter
+        well-defined without forcing a ``Literal[...]`` on the whole
+        envelope (which would break dict-based construction from YAML
+        test fixtures).
+
+        :param value: candidate outcome string
+        :ptype value: str
+        :return: the input value unchanged when valid
+        :rtype: str
+        :raises ValueError: when ``value`` is not success/failure/error
+        """
+        allowed = {"success", "failure", "error"}
+        if value not in allowed:
+            raise ValueError(
+                f"AuditEvent.outcome must be one of {sorted(allowed)}; received {value!r}",
+            )
+        return value
+
+    @field_validator("event_type")
+    @classmethod
+    def _require_dotted_event_type(cls, value: str) -> str:
+        """require the ``{domain}.{verb}`` dotted convention.
+
+        the envelope does not gate the set of event types (new domains
+        must be able to publish without editing this module) but it
+        does require the dotted shape so consumers can parse the
+        leading domain segment reliably.
+
+        :param value: candidate event_type
+        :ptype value: str
+        :return: the input value unchanged when it matches the shape
+        :rtype: str
+        :raises ValueError: when the value is empty or lacks a dot
+        """
+        if not value or "." not in value:
+            raise ValueError(
+                f"AuditEvent.event_type must be dotted '{{domain}}.{{verb}}[.{{sub_verb}}]'; received {value!r}",
+            )
+        return value

3tears_agent_audit-0.14.0/src/threetears/agent/audit/publish.py

@@ -0,0 +1,81 @@
+"""fire-and-forget audit publish helper.
+
+:func:`publish_audit` is the single publish path for every domain.
+serializes the :class:`AuditEvent` via pydantic, awaits one
+:meth:`NatsClient.publish` on ``{namespace}.audit.{event_type}``, and
+swallows every exception at WARN. tool-call success must never depend
+on audit infrastructure availability; this invariant is load-bearing.
+
+the hub-side ``unified_audit_consumer`` subscribes to
+``{namespace}.audit.>`` so new event types route automatically without
+a consumer-side change.
+"""
+
+from __future__ import annotations
+
+from threetears.nats import NatsClient, Subject
+from threetears.observe import get_logger
+
+from threetears.agent.audit.envelope import AuditEvent
+
+__all__ = ["publish_audit"]
+
+
+log = get_logger(__name__)
+
+
+async def publish_audit(
+    event: AuditEvent,
+    *,
+    nats_client: NatsClient | None,
+    namespace: str,
+) -> None:
+    """
+    publish one audit envelope on ``{namespace}.audit.{event_type}``.
+
+    fire-and-forget: any exception during publish is caught and logged
+    at WARN; no exception propagates to the caller. when
+    ``nats_client`` is ``None`` the call is an explicit no-op (useful
+    in tests and bootstrap windows before NATS wiring is complete).
+
+    the subject is built with the explicit ``namespace`` argument
+    rather than reading the :class:`Subjects` ContextVar so callers
+    that route audit traffic on a per-call namespace (multi-tenant
+    test fixtures, in-process audit consumers under explicit prefix
+    control) get the namespace they passed regardless of which
+    ContextVar value happens to be bound on the calling task.
+    ``event.event_type`` carries dots verbatim (e.g.
+    ``workspace.fs_write``); they form the subject hierarchy and are
+    NOT sanitized.
+
+    :param event: typed audit envelope to publish
+    :ptype event: AuditEvent
+    :param nats_client: connected canonical
+        :class:`threetears.nats.NatsClient` wrapper; ``None`` is a no-op
+    :ptype nats_client: NatsClient | None
+    :param namespace: NATS subject namespace (environment-scoped
+        prefix from ``THREETEARS_NATS_SUBJECT_NAMESPACE``)
+    :ptype namespace: str
+    :return: nothing
+    :rtype: None
+    """
+    if nats_client is None:
+        # bootstrap / test scenario; explicit no-op
+        return
+    subject = Subject.raw(f"{namespace}.audit.{event.event_type}")
+    try:
+        await nats_client.publish(subject=subject, message=event)
+    # NOSILENT: audit publish is fire-and-forget; failures log at WARN
+    # so the producing call path is never blocked by audit health.
+    except Exception as exc:
+        log.warning(
+            "audit publish failed",
+            extra={
+                "extra_data": {
+                    "subject": subject.path,
+                    "event_type": event.event_type,
+                    "namespace": namespace,
+                    "error": str(exc),
+                },
+            },
+        )

3tears_agent_audit-0.14.0/tests/unit/test_envelope.py

@@ -0,0 +1,184 @@
+"""unit tests for :class:`threetears.agent.audit.AuditEvent`.
+
+covers the envelope's anti-drift guarantees (``extra='forbid'``,
+timezone-aware ``timestamp``, closed ``outcome``, dotted
+``event_type``) and round-trip ``model_dump_json`` /
+``model_validate_json`` semantics used by the NATS publisher +
+consumer.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID, uuid7
+
+import pytest
+from pydantic import ValidationError
+
+from threetears.agent.audit import AuditEvent
+
+
+def _base_kwargs() -> dict[str, object]:
+    """
+    build a baseline valid kwargs dict for :class:`AuditEvent`.
+
+    :return: kwargs dict populated with a consistent set of field
+        values; individual tests mutate one key to exercise a
+        specific validator
+    :rtype: dict[str, object]
+    """
+    return {
+        "id": uuid7(),
+        "timestamp": datetime.now(UTC),
+        "event_type": "workspace.fs_write",
+        "actor_user_id": uuid7(),
+        "calling_agent_id": uuid7(),
+        "owner_agent_id": uuid7(),
+        "customer_id": uuid7(),
+        "resource_namespace_id": uuid7(),
+        "resource_namespace_type": "workspace",
+        "action": "write",
+        "outcome": "success",
+        "correlation_id": uuid7(),
+        "details": {"sha256": "abc123", "bytes": 42},
+    }
+
+
+def test_constructs_with_all_required_fields() -> None:
+    """envelope builds cleanly when every field is supplied."""
+    envelope = AuditEvent(**_base_kwargs())  # type: ignore[arg-type]
+
+    assert envelope.event_type == "workspace.fs_write"
+    assert envelope.action == "write"
+    assert envelope.outcome == "success"
+
+
+def test_optional_identity_fields_default_none() -> None:
+    """envelope builds with only the required scalar axes populated."""
+    envelope = AuditEvent(
+        id=uuid7(),
+        timestamp=datetime.now(UTC),
+        event_type="platform.role.create",
+        action="create",
+        correlation_id=uuid7(),
+    )
+
+    assert envelope.actor_user_id is None
+    assert envelope.calling_agent_id is None
+    assert envelope.owner_agent_id is None
+    assert envelope.customer_id is None
+    assert envelope.resource_namespace_id is None
+    assert envelope.resource_namespace_type is None
+    assert envelope.conversation_id is None
+    assert envelope.outcome == "success"
+    assert envelope.details == {}
+
+
+def test_conversation_id_field_round_trips() -> None:
+    """data-layer-task-01 sub-task 5: conversation_id propagates.
+
+    the ``audit_events`` table already carries the column; the
+    envelope now propagates it from CallContext into the persisted
+    row so admin queries can filter audit trails per conversation.
+    """
+    conv_id = uuid7()
+    envelope = AuditEvent(
+        id=uuid7(),
+        timestamp=datetime.now(UTC),
+        event_type="tool.call",
+        action="call",
+        correlation_id=uuid7(),
+        conversation_id=conv_id,
+    )
+    assert envelope.conversation_id == conv_id
+    wire = envelope.model_dump_json()
+    decoded = AuditEvent.model_validate_json(wire)
+    assert decoded.conversation_id == conv_id
+
+
+def test_naive_timestamp_rejected() -> None:
+    """``timestamp`` must carry a tzinfo; a naive datetime raises."""
+    kwargs = _base_kwargs()
+    kwargs["timestamp"] = datetime(2026, 1, 1, 12, 0, 0)
+
+    with pytest.raises(ValidationError):
+        AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+
+def test_unknown_outcome_rejected() -> None:
+    """``outcome`` is closed to success/failure/error."""
+    kwargs = _base_kwargs()
+    kwargs["outcome"] = "partial"
+
+    with pytest.raises(ValidationError):
+        AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+
+@pytest.mark.parametrize("outcome", ["success", "failure", "error"])
+def test_every_declared_outcome_accepted(outcome: str) -> None:
+    """each recognised outcome string constructs the envelope."""
+    kwargs = _base_kwargs()
+    kwargs["outcome"] = outcome
+
+    envelope = AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+    assert envelope.outcome == outcome
+
+
+def test_non_dotted_event_type_rejected() -> None:
+    """``event_type`` must be dotted ``{domain}.{verb}``."""
+    kwargs = _base_kwargs()
+    kwargs["event_type"] = "justaword"
+
+    with pytest.raises(ValidationError):
+        AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+
+def test_empty_event_type_rejected() -> None:
+    """an empty ``event_type`` string is rejected."""
+    kwargs = _base_kwargs()
+    kwargs["event_type"] = ""
+
+    with pytest.raises(ValidationError):
+        AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+
+def test_extra_fields_rejected() -> None:
+    """``extra='forbid'`` rejects any field not declared on the envelope."""
+    kwargs = _base_kwargs()
+    kwargs["mystery_field"] = "oops"
+
+    with pytest.raises(ValidationError):
+        AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+
+def test_round_trip_preserves_every_field() -> None:
+    """JSON round trip preserves UUID, datetime, and details shape."""
+    kwargs = _base_kwargs()
+    envelope = AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+    wire = envelope.model_dump_json()
+    decoded = AuditEvent.model_validate_json(wire)
+
+    assert decoded == envelope
+    assert decoded.details == envelope.details
+
+
+def test_details_defaults_to_empty_dict() -> None:
+    """omitting ``details`` yields an empty dict (not None)."""
+    kwargs = _base_kwargs()
+    del kwargs["details"]
+
+    envelope = AuditEvent(**kwargs)  # type: ignore[arg-type]
+
+    assert envelope.details == {}
+
+
+def test_id_round_trips_as_uuid() -> None:
+    """``id`` is a UUID object, not a string, after JSON round trip."""
+    kwargs = _base_kwargs()
+    envelope = AuditEvent(**kwargs)  # type: ignore[arg-type]
+    decoded = AuditEvent.model_validate_json(envelope.model_dump_json())
+
+    assert isinstance(decoded.id, UUID)
+    assert decoded.id == envelope.id

3tears_agent_audit-0.14.0/tests/unit/test_publish.py

@@ -0,0 +1,163 @@
+"""unit tests for :func:`threetears.agent.audit.publish_audit`.
+
+covers subject-naming, payload-shape, and the fire-and-forget
+invariant: every publish failure logs at WARN and returns cleanly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from uuid import uuid7
+
+import pytest
+from pydantic import BaseModel
+
+from threetears.agent.audit import AuditEvent, publish_audit
+from threetears.nats import Subject, set_default_namespace
+
+
+@dataclass
+class _FakeWrapper:
+    """minimal fake :class:`threetears.nats.NatsClient` recording each publish.
+
+    matches the wrapper's :meth:`publish` shape (kw-only ``subject`` +
+    ``message``) so tests exercise the same call surface production
+    code uses. payload bytes are derived from the recorded
+    :class:`BaseModel` to keep round-trip assertions intact.
+    """
+
+    publish_calls: list[tuple[Subject, BaseModel]] = field(default_factory=list)
+    raise_on_publish: BaseException | None = None
+
+    async def publish(
+        self,
+        *,
+        subject: Subject,
+        message: BaseModel,
+        reply_to: Subject | None = None,
+    ) -> None:
+        """record the publish invocation or raise when configured to."""
+        del reply_to  # unused in audit publish
+        self.publish_calls.append((subject, message))
+        if self.raise_on_publish is not None:
+            raise self.raise_on_publish
+
+
+@pytest.fixture(autouse=True)
+def _bind_namespace(request: pytest.FixtureRequest) -> None:
+    """bind a known default namespace for each test.
+
+    individual tests override via the ``namespace`` parameter on
+    :func:`publish_audit` (passed through for diagnostic logging) and
+    by calling :func:`set_default_namespace` directly to control the
+    subject that :class:`Subjects.audit_event` produces.
+    """
+    set_default_namespace("3tears")
+
+
+def _build_event(event_type: str = "workspace.fs_write") -> AuditEvent:
+    """build a valid envelope for the publish-helper tests."""
+    return AuditEvent(
+        id=uuid7(),
+        timestamp=datetime.now(UTC),
+        event_type=event_type,
+        actor_user_id=uuid7(),
+        calling_agent_id=uuid7(),
+        owner_agent_id=uuid7(),
+        customer_id=uuid7(),
+        resource_namespace_id=uuid7(),
+        resource_namespace_type="workspace",
+        action="write",
+        correlation_id=uuid7(),
+        details={"bytes": 42},
+    )
+
+
+async def test_publish_posts_to_namespace_dot_audit_dot_event_type() -> None:
+    """subject is ``{namespace}.audit.{event_type}`` verbatim."""
+    nats = _FakeWrapper()
+    event = _build_event("workspace.fs_write")
+
+    await publish_audit(event, nats_client=nats, namespace="dev")
+
+    assert len(nats.publish_calls) == 1
+    subject, _ = nats.publish_calls[0]
+    assert subject.path == "dev.audit.workspace.fs_write"
+
+
+async def test_publish_emits_typed_audit_event() -> None:
+    """recorded message is the same :class:`AuditEvent` instance round-trippable to JSON."""
+    nats = _FakeWrapper()
+    event = _build_event("rbac.assignment.create")
+
+    await publish_audit(event, nats_client=nats, namespace="staging")
+
+    _, message = nats.publish_calls[0]
+    assert isinstance(message, AuditEvent)
+    assert message == event
+    # round-trip the wire form to confirm the typed payload survives serialization
+    decoded = AuditEvent.model_validate_json(message.model_dump_json())
+    assert decoded == event
+
+
+async def test_publish_failure_is_swallowed_not_raised() -> None:
+    """publish failure must NOT propagate -- audit is fire-and-forget."""
+    nats = _FakeWrapper(raise_on_publish=RuntimeError("nats down"))
+    event = _build_event()
+
+    # must NOT raise; tool-call success never depends on audit health
+    await publish_audit(event, nats_client=nats, namespace="dev")
+
+
+async def test_publish_none_client_is_noop() -> None:
+    """``nats_client=None`` is an explicit no-op (bootstrap / tests)."""
+    event = _build_event()
+
+    # must NOT raise; no-op
+    await publish_audit(event, nats_client=None, namespace="dev")
+
+
+@pytest.mark.parametrize(
+    "event_type",
+    [
+        "workspace.fs_write",
+        "workspace.fs_edit",
+        "rbac.group.create",
+        "rbac.assignment.delete",
+        "rbac.introspect.explain",
+        "memory.retrieve",
+        "custom.tool.call",
+    ],
+)
+async def test_publish_preserves_dotted_event_type_in_subject(
+    event_type: str,
+) -> None:
+    """every dotted event_type appears verbatim in the subject."""
+    nats = _FakeWrapper()
+    event = _build_event(event_type)
+
+    await publish_audit(event, nats_client=nats, namespace="prod")
+
+    subject, _ = nats.publish_calls[0]
+    assert subject.path == f"prod.audit.{event_type}"
+
+
+async def test_publish_serialization_error_does_not_raise() -> None:
+    """a mid-publish exception is caught and logged."""
+
+    class _BrokenWrapper:
+        async def publish(
+            self,
+            *,
+            subject: Subject,
+            message: BaseModel,
+            reply_to: Subject | None = None,
+        ) -> None:
+            del subject, message, reply_to
+            raise TimeoutError("publish timeout")
+
+    event = _build_event()
+
+    # must NOT raise
+    await publish_audit(event, nats_client=_BrokenWrapper(), namespace="dev")