pixie-lab 0.1.0__py3-none-any.whl

pixie/deploy/_templates.py

@@ -0,0 +1,153 @@
+"""Deploy artifact templates.
+
+Everything the operator ever reads on a fresh deploy: compose.yml +
+envvars.example + README.md. Kept as Python strings (not Jinja files)
+because the substitutions are trivial and shipping a second templating
+layer for three files reads as ceremony.
+
+The compose file emits ONE service on ``--network=host``. The image
+tag is baked in at generation time so ``pixie-lab init`` on a v0.4.0
+CLI pins the container at ``ghcr.io/safl/pixie:0.4.0``; the operator
+can bump manually to track ``:latest`` if they want to.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_IMAGE_REPO = "ghcr.io/safl/pixie"
+DEFAULT_ADMIN_PASSWORD = "pixie"
+
+# NBD supervisor's default port range base -- kept in lockstep with
+# ``pixie.exports._supervisor.DEFAULT_PORT_BASE``.
+DEFAULT_NBD_PORT_BASE = 10809
+DEFAULT_HTTP_PORT = 8080
+
+COMPOSE_YAML = """\
+# pixie compose deployment. One service, one HTTP port + NBD range,
+# session-auth on write routes gated by ``PIXIE_ADMIN_PASSWORD``.
+#
+# Bring up with:
+#     cp envvars.example envvars
+#     "${{EDITOR:-vi}}" envvars     # set PIXIE_HOST_ADDR + PIXIE_ADMIN_PASSWORD
+#     COMPOSE_ENV_FILES=envvars podman compose up -d
+#
+# ``--network=host`` is the whole point of pixie's one-container
+# shape: udp/69 (once the in-process TFTP router lands), tcp/8080
+# (HTTP), and the NBD port range all reach the LAN without any
+# port-publish hoops. Operators fronting pixie behind a reverse proxy
+# can drop network_mode: host and publish 8080 explicitly.
+services:
+  pixie:
+    image: {image}
+    container_name: pixie
+    restart: unless-stopped
+    network_mode: host
+    environment:
+      PIXIE_ADMIN_PASSWORD: ${{PIXIE_ADMIN_PASSWORD:-{admin_password}}}
+      PIXIE_PUBLIC_HOST: ${{PIXIE_HOST_ADDR:-127.0.0.1}}
+      PIXIE_NBD_PUBLIC_HOST: ${{PIXIE_HOST_ADDR:-127.0.0.1}}
+      # Optional per-target kernel workarounds appended to the
+      # pixie-live-env cmdline. Empty by default. Known-good values
+      # for specific hardware live in the src/pixie/pxe/_routes.py
+      # docstring; set here if any of your PXE targets need one.
+      # Example (GIGABYTE MC12-LE0): pci=realloc=on,nocrs
+      PIXIE_LIVE_ENV_EXTRA_CMDLINE: ${{PIXIE_LIVE_ENV_EXTRA_CMDLINE:-}}
+    volumes:
+      - ./data:/var/lib/pixie:Z
+    # Container HEALTHCHECK is baked in the Containerfile; compose
+    # picks it up automatically.
+"""
+
+ENVVARS_EXAMPLE = """\
+# Fill this in and rename to ``envvars``. Both fields below are
+# REQUIRED for a functional deploy.
+#
+# COMPOSE_ENV_FILES=envvars podman compose up -d
+#
+# PIXIE_HOST_ADDR is the LAN address pixie tells iPXE targets to
+# use. Set it to the address ON YOUR LAN this box answers on; if
+# left unset the plans point at 127.0.0.1 and a target that boots
+# the plan can't reach pixie's HTTP / NBD.
+PIXIE_HOST_ADDR=
+
+# Session-auth password for the operator UI + write routes.
+# Default is public knowledge; set your own.
+PIXIE_ADMIN_PASSWORD={admin_password}
+
+# Per-target kernel workarounds appended to the pixie-live-env
+# cmdline. Empty by default; set on a target-by-target basis.
+#
+# Known-good values:
+#   GIGABYTE MC12-LE0 (Ryzen server board):
+#     PIXIE_LIVE_ENV_EXTRA_CMDLINE=pci=realloc=on,nocrs
+#   That board's BIOS has a ROM BAR overlap defect that leaves no
+#   MMIO space for the Intel i210 NICs; without the workaround the
+#   live env boots with no working network, live-boot never fetches
+#   the squashfs, and boot hangs silently.
+PIXIE_LIVE_ENV_EXTRA_CMDLINE=
+"""
+
+README_MD = """\
+# pixie deploy
+
+Generated by ``pixie-lab init``.
+
+## Layout
+
+* ``compose.yml``     -- compose stack. One service on ``--network=host``.
+* ``envvars.example`` -- environment overrides. Copy to ``envvars`` and edit.
+* ``data/``           -- persistent state (blobs + artifacts + state.db).
+
+## Bring up
+
+```
+cp envvars.example envvars
+# Set PIXIE_HOST_ADDR to the LAN address this box answers on.
+# Set PIXIE_ADMIN_PASSWORD to something other than the default.
+"${{EDITOR:-vi}}" envvars
+
+COMPOSE_ENV_FILES=envvars podman compose up -d
+```
+
+The container's HTTP server binds ``127.0.0.1:{http_port}`` and, when
+targets bind nbdboot, spawns one nbdkit per export starting at TCP
+``{nbd_port}``. ``pixie-lab deploy`` runs the compose bring-up for
+you, filling in envvars if it's empty.
+
+## Tear down
+
+```
+podman compose --env-file envvars down -v
+```
+
+Or ``pixie-lab purge`` from this directory.
+
+## Docs
+
+See ``PLAN.md`` at github.com/safl/pixie for the design rationale
+and roadmap.
+"""
+
+
+def compose_yaml(*, image: str, admin_password: str) -> str:
+    return COMPOSE_YAML.format(image=image, admin_password=admin_password)
+
+
+def envvars_example(*, admin_password: str) -> str:
+    return ENVVARS_EXAMPLE.format(admin_password=admin_password)
+
+
+def readme_md(*, http_port: int = DEFAULT_HTTP_PORT, nbd_port: int = DEFAULT_NBD_PORT_BASE) -> str:
+    return README_MD.format(http_port=http_port, nbd_port=nbd_port)
+
+
+def emitted_files(dest: str, image: str) -> dict[str, Any]:
+    """The three files a fresh ``pixie-lab init`` writes, plus the
+    ``data/`` scaffold. Returned as a dict so tests can assert
+    specific bytes without touching the filesystem."""
+    return {
+        f"{dest}/compose.yml": compose_yaml(image=image, admin_password=DEFAULT_ADMIN_PASSWORD),
+        f"{dest}/envvars.example": envvars_example(admin_password=DEFAULT_ADMIN_PASSWORD),
+        f"{dest}/README.md": readme_md(),
+    }

pixie/disks.py

@@ -0,0 +1,85 @@
+"""Block-device discovery via ``lsblk``.
+
+Pure-data module: returns plain dicts so the result can be JSON-serialised
+or tabulated by ``pixie`` without further translation.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+# Columns we ask ``lsblk`` for. NAME and PATH are both requested because
+# loop/ram devices sometimes lack PATH.
+_LSBLK_COLS = "NAME,PATH,SIZE,TYPE,VENDOR,MODEL,SERIAL,RM,RO,MOUNTPOINTS,TRAN"
+
+# Top-level types we surface. Partitions are a child of "disk" and are
+# not reported as separate entries in the default output.
+_INTERESTING_TYPES = {"disk"}
+
+
+def list_disks() -> list[dict[str, Any]]:
+    """Return interesting block devices on the local system.
+
+    Shells out to ``lsblk -J`` and filters to top-level disks (drops
+    loop, ram, rom, etc.). Each entry is a plain dict with stable keys.
+    """
+    proc = subprocess.run(
+        ["lsblk", "-J", "-o", _LSBLK_COLS],
+        capture_output=True,
+        text=True,
+        check=True,
+        # Bound the call so a stuck IO subsystem (failing disk
+        # responding slowly to udev queries) can't hang ``pixie``
+        # indefinitely. 10s is generous; healthy lsblk returns
+        # in <100ms on every box I've tested.
+        timeout=10,
+    )
+    try:
+        payload = json.loads(proc.stdout)
+    except json.JSONDecodeError as exc:
+        # lsblk exited 0 but emitted non-JSON. ``check=True`` covers a
+        # non-zero exit, but a zero-exit-with-truncated/empty-stdout
+        # (seen on cut-down busybox lsblk builds) would otherwise raise
+        # an uncaught ``ValueError`` and crash disk selection. Surface
+        # it as a SubprocessError so the callers that already guard
+        # lsblk failures (the TUI disk picker, the CLI) degrade to "no
+        # disks discoverable" instead of tracing back.
+        raise subprocess.SubprocessError(f"lsblk returned unparseable JSON: {exc}") from exc
+    devices: list[dict[str, Any]] = payload.get("blockdevices", [])
+
+    out: list[dict[str, Any]] = []
+    for d in devices:
+        if d.get("type") not in _INTERESTING_TYPES:
+            continue
+        out.append(
+            {
+                "path": d.get("path") or f"/dev/{d['name']}",
+                "size": d.get("size"),
+                "type": d.get("type"),
+                "vendor": _strip_or_none(d.get("vendor")),
+                "model": _strip_or_none(d.get("model")),
+                # Some USB enclosures / vendor-firmware report
+                # serials with trailing whitespace; strip for
+                # consistency with vendor / model. ``pixie`` in
+                # auto-flash mode matches the plan's
+                # ``target_disk_serial`` against this value
+                # exactly, so the same strip on both ends keeps
+                # the gate working when the inventory side and
+                # the flash-time side agree on the canonical form.
+                "serial": _strip_or_none(d.get("serial")),
+                "tran": d.get("tran"),
+                "removable": bool(d.get("rm")),
+                "readonly": bool(d.get("ro")),
+                "mountpoints": [m for m in (d.get("mountpoints") or []) if m],
+            }
+        )
+    return out
+
+
+def _strip_or_none(value: str | None) -> str | None:
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None

pixie/events/__init__.py

@@ -0,0 +1,28 @@
+"""Append-only event log.
+
+Every write path in pixie emits one row: fetch started, fetch failed,
+machine bound, export registered, TFTP started. Rows live on the
+shared ``state.db``; there is one bus for the whole process, not one
+per module.
+
+Consumers:
+
+* Operator UI (``/ui/events``): scrollable timeline the operator
+  glances at to see what pixie has done recently.
+* JSON API (``GET /events``): programmatic access + filtering by
+  subject/kind/since.
+
+Rows are immutable; a mis-emitted event is not corrected in place, a
+follow-up event is emitted describing the correction. Simpler audit
+trail, no back-dated writes.
+
+Hard-forked from bty's ``_events_log.py`` (see
+``docs/audit.md#bty``) 2026-07-13.
+"""
+
+from __future__ import annotations
+
+from pixie.events._kinds import KNOWN_EVENT_KINDS
+from pixie.events._log import EventsLog, UnknownEventKind
+
+__all__ = ["KNOWN_EVENT_KINDS", "EventsLog", "UnknownEventKind"]

pixie/events/_kinds.py

@@ -0,0 +1,203 @@
+"""Closed registry of event kinds pixie emits.
+
+Every mutation carries an event with a well-defined identifier from
+this module. Callers import the constant and pass it to
+:meth:`EventsLog.emit`; the emit call rejects any string not in
+:data:`KNOWN_EVENT_KINDS`. A new mutation site adds a constant here
+first (with a docstring explaining what state changed and what
+``subject_kind`` / ``subject_id`` / ``details`` carry), then wires it
+into the call site -- never the other way around.
+
+Naming convention: ``<subject>.<verb>[.<outcome>]`` in lower kebab
+form. ``<subject>`` matches the ``subject_kind`` field on the row
+so filtering ``kind LIKE 'catalog.%'`` and ``subject_kind =
+'entry'`` gives roughly the same slice. ``<outcome>`` distinguishes
+async terminal states (``.started`` / ``.done`` / ``.failed``);
+synchronous verbs skip it.
+"""
+
+from __future__ import annotations
+
+# ---------- catalog + fetch pipeline ---------------------------------
+#
+# Every catalog-store mutation emits one of these. ``subject_kind`` is
+# always ``"entry"``; ``subject_id`` is the catalog entry name.
+
+CATALOG_ENTRY_ADDED = "catalog.entry.added"
+"""A new row landed via POST /catalog/entries, POST /ui/catalog/add,
+or one of the entries in POST /ui/catalog/import. ``details.src``
+carries the source URL so an operator can grep the log by URL."""
+
+CATALOG_ENTRY_DELETED = "catalog.entry.deleted"
+"""Row deleted via POST /ui/catalog/delete or DELETE /catalog/entries.
+On-disk bytes are NOT touched here (see ``catalog.blob.deleted``)."""
+
+CATALOG_ENTRY_UPDATED = "catalog.entry.updated"
+"""A catalog entry's metadata was overwritten (Import overwrote an
+existing name; a future edit-entry form lands here too). Fetch is
+tracked separately via the ``catalog.fetch.*`` triple."""
+
+CATALOG_FETCH_STARTED = "catalog.fetch.started"
+"""Fetch pipeline kicked off. ``details`` carries the source URL +
+whether this is an initial Fetch (``update = False``) or an Update
+on an already-fetched entry."""
+
+CATALOG_FETCH_DONE = "catalog.fetch.done"
+"""Fetch pipeline finished successfully. ``details.content_sha256``
++ ``details.size_bytes`` name the new bytes."""
+
+CATALOG_FETCH_FAILED = "catalog.fetch.failed"
+"""Fetch pipeline errored. ``details.error`` carries the message."""
+
+CATALOG_FETCH_UNCHANGED = "catalog.fetch.unchanged"
+"""Update click on an already-fetched entry whose blob is still
+present -- nothing to download. The operator's request is
+acknowledged (an event fires + the UI shows a short-lived "already
+at latest" pill) rather than silently flickering the fetching
+badge for a millisecond. ``details.content_sha256`` names the
+still-current bytes."""
+
+CATALOG_BLOB_DELETED = "catalog.blob.deleted"
+"""On-disk bytes for an entry dropped via POST /ui/catalog/delete-blob.
+Row stays with content_sha256 cleared so a subsequent Fetch re-runs
+the pipeline. ``details.forced`` is True when the operator confirmed
+through the in-use warning banner."""
+
+CATALOG_IMPORT_OK = "catalog.import.ok"
+"""POST /ui/catalog/import fetched a catalog.toml and upserted every
+entry. ``details.url`` + ``details.count`` + ``details.new``
+summarise the result; individual ``catalog.entry.added`` /
+``.updated`` events fire per entry."""
+
+CATALOG_IMPORT_FAILED = "catalog.import.failed"
+"""POST /ui/catalog/import could not reach the URL or parse the TOML.
+``details.error`` carries the exception message."""
+
+# ---------- exports + NBD supervisor ---------------------------------
+#
+# ``subject_kind`` is always ``"export"``; ``subject_id`` is the export
+# name (``pixie-<sha12>.img`` shape).
+
+EXPORT_REGISTERED = "export.registered"
+"""New export row via POST /exports; carries ``details.content_sha256``
++ ``details.nbd_port``."""
+
+EXPORT_DELETED = "export.deleted"
+"""Export row + running nbdkit torn down via DELETE /exports/<name>
+or POST /ui/exports/delete."""
+
+EXPORT_NBDKIT_SPAWNED = "export.nbdkit.spawned"
+"""Supervisor spawned an nbdkit subprocess (fresh spawn or the
+startup-time respawn walk). ``details.pid`` + ``details.nbd_port``."""
+
+EXPORT_NBDKIT_EXITED = "export.nbdkit.exited"
+"""Supervisor observed an nbdkit subprocess died out of band
+(``_refresh_row`` noticed no live proc for a ``running`` row).
+``details.previous_port`` + ``details.error`` explain."""
+
+# ---------- machines + PXE ------------------------------------------
+#
+# ``subject_kind`` is always ``"machine"``; ``subject_id`` is the
+# canonical MAC address.
+
+MACHINE_DISCOVERED = "machine.discovered"
+"""First-ever GET /pxe/<mac> for a MAC pixie has not seen before.
+Emitted from ``machines_store.touch_seen`` when a new row is
+created; subsequent hits do NOT emit (they update ``last_seen_at``
+via the ``pxe.plan.rendered`` event instead)."""
+
+MACHINE_BOUND = "machine.bound"
+"""First bind for a MAC: PUT /machines/<mac> or POST
+/ui/machines/bind. ``details.boot_mode`` +
+``details.image_content_sha256`` capture the target state."""
+
+MACHINE_BINDING_CHANGED = "machine.binding.changed"
+"""Existing machine's ``boot_mode`` or ``image_content_sha256``
+changed via the same route. Distinct from ``.bound`` so an
+operator can filter for "any change" vs "first bind ever"."""
+
+MACHINE_DELETED = "machine.deleted"
+"""Row deleted via DELETE /machines/<mac> or POST
+/ui/machines/delete."""
+
+MACHINE_INVENTORY_UPDATED = "machine.inventory.updated"
+"""POST /pxe/<mac>/inventory landed a new hardware inventory blob
+from the live-env pixie CLI."""
+
+# ---------- PXE plan render + status --------------------------------
+#
+# The renderer fires exactly one of ``pxe.plan.rendered`` /
+# ``pxe.plan.unavailable`` per GET /pxe/<mac>. Status POSTs from the
+# target's live env / nbdboot initrd flow through ``pxe.status.received``.
+
+PXE_PLAN_RENDERED = "pxe.plan.rendered"
+"""GET /pxe/<mac> emitted a bootable iPXE plan for a known
+boot_mode. ``details.boot_mode`` names which mode; ``subject_kind``
+= ``machine``, ``subject_id`` = mac."""
+
+PXE_PLAN_UNAVAILABLE = "pxe.plan.unavailable"
+"""GET /pxe/<mac> fell back to unavailable.j2 (missing binding,
+missing bundle, missing live-env media, unknown mode).
+``details.reason`` carries the human-readable explanation the
+plan comment carries."""
+
+PXE_STATUS_RECEIVED = "pxe.status.received"
+"""POST /pxe/<mac>/status from the target initrd or live env.
+``details.status`` is the raw status token
+(``ramboot.up``, ``ramboot.nbd_connect_failed``, ``ramboot.die``, ...)."""
+
+# ---------- TFTP subprocess supervisor ------------------------------
+#
+# No subject (``subject_kind`` = "") -- the TFTP process is per-pixie,
+# not per-resource. Useful for the operator to prove udp/69 came up.
+
+TFTP_STARTED = "tftp.started"
+"""``pixie.tftp.TftpServer.start`` succeeded and ``in.tftpd`` is
+listening on the resolved bind:port."""
+
+TFTP_STOPPED = "tftp.stopped"
+"""The tftp supervisor tore its subprocess down on shutdown."""
+
+# ---------- auth ----------------------------------------------------
+#
+# ``subject_kind`` = "" (single-tenant; no per-operator identity).
+
+AUTH_LOGIN_SUCCEEDED = "auth.login.succeeded"
+"""POST /ui/login with the correct admin password."""
+
+AUTH_LOGIN_FAILED = "auth.login.failed"
+"""POST /ui/login with a wrong admin password."""
+
+
+# The canonical closed set. Every kind above is registered here; the
+# ``EventsLog.emit`` call rejects anything not in this frozenset.
+KNOWN_EVENT_KINDS: frozenset[str] = frozenset(
+    {
+        CATALOG_ENTRY_ADDED,
+        CATALOG_ENTRY_DELETED,
+        CATALOG_ENTRY_UPDATED,
+        CATALOG_FETCH_STARTED,
+        CATALOG_FETCH_DONE,
+        CATALOG_FETCH_FAILED,
+        CATALOG_FETCH_UNCHANGED,
+        CATALOG_BLOB_DELETED,
+        CATALOG_IMPORT_OK,
+        CATALOG_IMPORT_FAILED,
+        EXPORT_REGISTERED,
+        EXPORT_DELETED,
+        EXPORT_NBDKIT_SPAWNED,
+        EXPORT_NBDKIT_EXITED,
+        MACHINE_DISCOVERED,
+        MACHINE_BOUND,
+        MACHINE_BINDING_CHANGED,
+        MACHINE_DELETED,
+        MACHINE_INVENTORY_UPDATED,
+        PXE_PLAN_RENDERED,
+        PXE_PLAN_UNAVAILABLE,
+        PXE_STATUS_RECEIVED,
+        TFTP_STARTED,
+        TFTP_STOPPED,
+        AUTH_LOGIN_SUCCEEDED,
+        AUTH_LOGIN_FAILED,
+    }
+)

pixie/events/_log.py

@@ -0,0 +1,210 @@
+"""Events table + append/list operations.
+
+Events are (kind, subject_kind, subject_id, summary, details, ts)
+tuples. ``kind`` is a dotted string (e.g. ``catalog.fetch.started``)
+that operators grep on. ``subject_kind`` + ``subject_id`` scope the
+event to a specific resource: ``machine``/<mac>, ``export``/<name>,
+``entry``/<catalog-name>.
+
+All time in ISO-8601 UTC (``now_iso`` from the shared util).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sqlite3
+import threading
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pixie._util import now_iso
+from pixie.events._kinds import KNOWN_EVENT_KINDS
+
+_DB_WRITE_LOCK = threading.Lock()
+
+
+class UnknownEventKind(ValueError):
+    """Raised by :meth:`EventsLog.emit` when the caller passed a
+    ``kind`` string not in :data:`pixie.events.KNOWN_EVENT_KINDS`.
+
+    Every action pixie takes must land in the event log with a
+    well-defined identifier from ``pixie.events._kinds``; the closed
+    set is enforced (not advisory) so a new mutation site cannot slip
+    through without an operator seeing it. Add the constant to
+    ``_kinds.py`` first, then wire the call site.
+    """
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS events (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts            TEXT NOT NULL,
+    kind          TEXT NOT NULL,
+    subject_kind  TEXT NOT NULL DEFAULT '',
+    subject_id    TEXT NOT NULL DEFAULT '',
+    summary       TEXT NOT NULL DEFAULT '',
+    details_json  TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_kind ON events(kind);
+CREATE INDEX IF NOT EXISTS idx_events_subject
+    ON events(subject_kind, subject_id);
+CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts);
+"""
+
+
+@dataclass
+class Event:
+    ts: str
+    kind: str
+    subject_kind: str = ""
+    subject_id: str = ""
+    summary: str = ""
+    details: dict[str, Any] = field(default_factory=dict)
+    id: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "id": self.id,
+            "ts": self.ts,
+            "kind": self.kind,
+            "summary": self.summary,
+        }
+        if self.subject_kind:
+            out["subject_kind"] = self.subject_kind
+        if self.subject_id:
+            out["subject_id"] = self.subject_id
+        if self.details:
+            out["details"] = self.details
+        return out
+
+
+class EventsLog:
+    """Repository over the ``events`` table. Append-only + query."""
+
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = Path(db_path)
+        self._ensure_schema()
+
+    def _ensure_schema(self) -> None:
+        with self._conn() as conn:
+            conn.executescript(_SCHEMA)
+
+    @contextlib.contextmanager
+    def _conn(self) -> Generator[sqlite3.Connection]:
+        conn = sqlite3.connect(str(self.db_path))
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+            conn.commit()
+        finally:
+            conn.close()
+
+    def emit(
+        self,
+        kind: str,
+        *,
+        subject_kind: str = "",
+        subject_id: str = "",
+        summary: str = "",
+        details: dict[str, Any] | None = None,
+    ) -> Event:
+        """Append one row.
+
+        ``kind`` MUST be one of the constants declared in
+        :mod:`pixie.events._kinds`; anything else raises
+        :class:`UnknownEventKind`. Every pixie mutation carries an
+        event log entry with a well-defined identifier, and the
+        closed set is enforced so a new mutation site cannot slip in
+        without an operator noticing. Register the constant in
+        ``_kinds.py`` first, then wire the call site.
+        """
+        if kind not in KNOWN_EVENT_KINDS:
+            raise UnknownEventKind(
+                f"event kind {kind!r} is not registered in "
+                f"pixie.events._kinds.KNOWN_EVENT_KINDS. Add a constant "
+                f"there first (with a docstring) before emitting from a "
+                f"new site."
+            )
+        row = Event(
+            ts=now_iso(),
+            kind=kind,
+            subject_kind=subject_kind,
+            subject_id=subject_id,
+            summary=summary,
+            details=details or {},
+        )
+        with _DB_WRITE_LOCK, self._conn() as conn:
+            cur = conn.execute(
+                "INSERT INTO events (ts, kind, subject_kind, subject_id, summary, details_json) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (
+                    row.ts,
+                    row.kind,
+                    row.subject_kind,
+                    row.subject_id,
+                    row.summary,
+                    json.dumps(row.details),
+                ),
+            )
+            row.id = int(cur.lastrowid) if cur.lastrowid is not None else None
+        return row
+
+    def list(
+        self,
+        *,
+        kind: str = "",
+        subject_kind: str = "",
+        subject_id: str = "",
+        since_id: int = 0,
+        limit: int = 100,
+    ) -> list[Event]:
+        """Reverse-chronological (newest first) with optional filters.
+
+        ``since_id`` is exclusive (>) so operators can build a poll
+        loop off ``max(id)`` without dedup. Filters are ANDed; empty
+        strings match anything.
+        """
+        clauses: list[str] = []
+        params: list[Any] = []
+        if kind:
+            clauses.append("kind = ?")
+            params.append(kind)
+        if subject_kind:
+            clauses.append("subject_kind = ?")
+            params.append(subject_kind)
+        if subject_id:
+            clauses.append("subject_id = ?")
+            params.append(subject_id)
+        if since_id > 0:
+            clauses.append("id > ?")
+            params.append(since_id)
+        sql = "SELECT * FROM events"
+        if clauses:
+            sql += " WHERE " + " AND ".join(clauses)
+        sql += " ORDER BY id DESC LIMIT ?"
+        params.append(max(1, min(limit, 1000)))
+        with self._conn() as conn:
+            rows = conn.execute(sql, params).fetchall()
+        return [_row(r) for r in rows]
+
+
+def _row(r: sqlite3.Row) -> Event:
+    try:
+        details = json.loads(r["details_json"] or "{}")
+        if not isinstance(details, dict):
+            details = {}
+    except json.JSONDecodeError:
+        details = {}
+    return Event(
+        id=r["id"],
+        ts=r["ts"],
+        kind=r["kind"],
+        subject_kind=r["subject_kind"],
+        subject_id=r["subject_id"],
+        summary=r["summary"],
+        details=details,
+    )