feat(web/db): observations table + repo + bus prefix (BEHAVE-INTEGRATION Phase 1)

Additive Phase 1 of BEHAVE-INTEGRATION.md. Lays the storage layer
the BEHAVE-SHELL extractor (DEBT-050) will write into. Nothing
breaks; SessionProfile coexists for now and is dropped in the
follow-up commit.

decnet/web/db/models/observations.py — new ObservationRow SQLModel
mirroring the BEHAVE Observation envelope field-for-field
(core/decnet_behave_core/spec/envelope.py). ``id`` is a hex-string
UUID (matching BEHAVE), not a typed UUID column. ``identity_ref``
is str | None — written by the future attribution engine, NULL
until then. ``attacker_uuid`` is the one DECNET-side
denormalisation; FK'd to attackers.uuid for cheap AttackerDetail
joins. ``evidence_ref`` is NOT NULL for DECNET emissions even
though the upstream envelope makes it optional — the worker's
"already profiled?" check keys on it. UniqueConstraint(evidence_ref,
primitive) enforces idempotency at the schema level so re-running
the extractor on the same shard+sid produces a DB-side conflict
the upsert path resolves deterministically. Class is named
``ObservationRow`` (not ``Observation``) to avoid colliding with
the BEHAVE Pydantic envelope at sites that import both.

decnet/web/db/sqlmodel_repo/observations.py — ObservationsMixin.
Three public methods backing the canonical queries from
BEHAVE-INTEGRATION.md §"Storage": ``upsert_observation`` (idempotent
on the natural key), ``latest_observation_per_primitive`` (per-
primitive MAX(ts) subquery, portable across SQLite and MySQL — no
DISTINCT ON), ``observations_time_series`` (asc-by-ts). Plus
``has_observations_for_evidence`` for the worker's session-already-
profiled check.

decnet/bus/topics.py — ATTACKER_OBSERVATION_PREFIX = "observation"
constant + ``attacker_observation(primitive)`` builder. Full topic
shape ``attacker.observation.<primitive>`` matches what BEHAVE's
spec.event_adapter.event_topic_for produces upstream. Documentation
+ pattern matching only — bus auth is socket file perms (DEBT-029
§2), not topic-level.

decnet/web/db/repository.py — abstract ``upsert_observation``,
``latest_observation_per_primitive``, ``observations_time_series``
on BaseRepository.

tests/db/test_observations.py — 11 tests covering upsert round-trip,
idempotency under the unique constraint, latest-per-primitive
ordering across multiple sessions, time-series asc-ordering, empty-
attacker contract, every BEHAVE ValueKind round-tripping through
the JSON column, and the has_observations_for_evidence check.

tests/db/test_base_repo.py — DummyRepo gains the three new abstract
overrides so its coverage suite still instantiates.
This commit is contained in:
2026-05-03 07:25:10 -04:00
parent 11f474556c
commit 0972325527
8 changed files with 683 additions and 0 deletions

View File

@@ -313,6 +313,44 @@ class BaseRepository(ABC):
"""Retrieve the keystroke-dynamics profile row for a session."""
pass
# ─── BEHAVE-SHELL observations ─────────────────────────────────────
# See development/BEHAVE-INTEGRATION.md §"Storage" for the full
# schema rationale. Every observation envelope emitted by the
# BEHAVE-SHELL extractor lands in the ``observations`` table; this
# is the abstract surface the worker calls.
@abstractmethod
async def upsert_observation(self, data: dict[str, Any]) -> str:
"""Insert or update an ``ObservationRow`` keyed on
``(evidence_ref, primitive)``.
``data`` MUST carry the BEHAVE envelope fields (``primitive``,
``value``, ``confidence``, ``window_start_ts``,
``window_end_ts``, ``source``, ``evidence_ref``,
``envelope_v``, ``ts``) plus the DECNET-side ``attacker_uuid``
denorm. Returns the row ``id``.
"""
raise NotImplementedError
@abstractmethod
async def latest_observation_per_primitive(
self, attacker_uuid: str,
) -> dict[str, dict[str, Any]]:
"""Return the latest observation per primitive for one attacker.
Empty dict when the attacker has no observations. Backs the
AttackerDetail "current state" panel.
"""
raise NotImplementedError
@abstractmethod
async def observations_time_series(
self, attacker_uuid: str, primitive: str,
) -> list[dict[str, Any]]:
"""Every observation of ``primitive`` for ``attacker_uuid``,
ordered by ``ts`` ASC. Empty list when none."""
raise NotImplementedError
async def upsert_observed_attachment(
self,
*,