@deftai/directive-content 0.55.2 → 0.56.1

package/scripts/_events.py

@@ -0,0 +1,514 @@
+"""_events.py -- behavioral-event emit helper for framework events (#635).
+
+Lands the 4 behavioral events from ``events/registry.json`` (the unified
+registry, post-#706 unification per the Repair Authority [AXIOM] proposal
+in #709 + the data-file-convention follow-up in #710): paired
+``session:interrupted`` / ``session:resumed``, ``plan:approved``, and
+``legacy:detected``. The 5 sibling detection-bound events live in the
+same registry under ``category: detection-bound`` and are emitted via
+``scripts/_event_detect.py`` instead -- both helpers consume the same
+data file but enforce different category boundaries so behavioral and
+detection-bound emission paths remain semantically distinct.
+
+Why a structural helper: per the canonical #642 workflow comment locked
+decisions and the Rule Authority [AXIOM] block in ``main.md``, framework
+events are a STRUCTURAL artifact, not prose. The emit helper + JSONL
+append-only log are the deterministic encoding form; ``events/registry.json``
+describes the contract.
+
+Storage
+-------
+Events are appended to ``.deft-cache/events.jsonl`` under the project
+root. The log lives under ``.deft-cache/`` (already covered by the
+canonical gitignore deposit) rather than ``.deft/`` because, since #11
+made the ``.deft/core/`` payload a committed artifact, ``.deft/`` is no
+longer blanket-gitignored. The old #401-era assumption that ``.deft/``
+was gitignored went stale, so a default log under ``.deft/`` leaked as an
+untracked file in consumers (#1465). The file is project-local and
+ephemeral. Tests inject a temp path to keep tests hermetic.
+
+Pairing
+-------
+``session:interrupted`` / ``session:resumed`` MUST be co-emitted: every
+resumed event carries an ``interrupted_id`` referencing the open
+interrupt. ``validate_pairing`` returns the list of orphan resumed
+records; an empty list means the pair invariant holds. The vBRIEF
+acceptance criterion (3) is enforced via this helper.
+
+CLI
+---
+Agents emit by invoking::
+
+    python -m scripts._events emit <name> --payload '<json>'
+    python -m scripts._events emit session:interrupted \
+        --session-id <s> --reason context-window-shift
+    python -m scripts._events emit session:resumed \
+        --session-id <s> --interrupted-id <id>
+    python -m scripts._events emit plan:approved \
+        --plan-ref <url> --approver <login> --approval-phrase yes
+    python -m scripts._events validate-pairing
+
+Handlers
+--------
+v0 of this surface is emit-only. The behavioral vBRIEF explicitly defers
+downstream consumer effects (what plan:approved triggers, what action
+legacy:detected drives) to follow-up work. This module exposes
+``read_events`` so consumers can be written in subsequent PRs without
+churning the emit contract.
+
+Issue: #635 (epic), #642 (workflow umbrella), #634 (determinism ladder),
+#709 (Repair Authority [AXIOM] -- the rule motivating the registry
+unification), #710 (data-file-convention check follow-up).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import secrets
+import sys
+import time
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _content_root import content_root  # noqa: E402
+
+# Default event log location (project-local). Lives under ``.deft-cache/``
+# -- which the canonical gitignore deposit already covers -- rather than
+# ``.deft/``, which is no longer blanket-gitignored now that ``.deft/core/``
+# is a committed payload (#11). The prior ``.deft/events.jsonl`` default
+# leaked as an untracked file in consumers (#1465).
+DEFAULT_EVENT_LOG: Path = Path(".deft-cache") / "events.jsonl"
+
+# Path to the unified events registry (data file). Resolved relative to
+# this module so tests and direct script invocations both find it without
+# depending on cwd.
+_REGISTRY_PATH: Path = (
+    content_root(Path(__file__).resolve().parent.parent) / "events" / "registry.json"
+)
+
+# Behavioral event category enum value -- this helper only emits events
+# that carry ``category: "behavioral"`` in the unified registry. Sibling
+# detection-bound events are emitted via ``scripts/_event_detect.py``.
+_BEHAVIORAL_CATEGORY: str = "behavioral"
+
+
+@lru_cache(maxsize=1)
+def _load_behavioral_registry() -> tuple[
+    frozenset[str], dict[str, tuple[str, ...]]
+]:
+    """Return ``(KNOWN_EVENTS, REQUIRED_PAYLOAD)`` from the unified registry.
+
+    Reads ``events/registry.json`` once per process and filters to events
+    whose ``category`` matches ``_BEHAVIORAL_CATEGORY``. Required payload
+    fields are derived from a hard-coded contract (per-event tuples below)
+    rather than the registry's free-form payload-description map -- the
+    registry's payload field describes shape and intent for humans/schema
+    consumers, but the emit-time required-field gate is a code contract
+    that the unified registry's free-form descriptions don't encode
+    losslessly. The hard-coded ``_REQUIRED_BEHAVIORAL_PAYLOAD`` below is
+    the single source of truth for emit-time payload validation.
+    """
+    data = json.loads(_REGISTRY_PATH.read_text(encoding="utf-8"))
+    behavioral_names = frozenset(
+        event["name"]
+        for event in data.get("events", [])
+        if isinstance(event, dict)
+        and event.get("category") == _BEHAVIORAL_CATEGORY
+        and "name" in event
+    )
+    return behavioral_names, dict(_REQUIRED_BEHAVIORAL_PAYLOAD)
+
+
+# Per-event required payload fields. Single source of truth for the
+# emit-time required-field gate. Mirrors the canonical payload contracts
+# documented in events/registry.json under category=behavioral.
+_REQUIRED_BEHAVIORAL_PAYLOAD: dict[str, tuple[str, ...]] = {
+    "session:interrupted": ("session_id", "reason"),
+    "session:resumed": ("session_id", "interrupted_id"),
+    "plan:approved": ("plan_ref", "approver"),
+    "legacy:detected": ("title", "source", "range", "size_bytes"),
+}
+
+
+def _registered_behavioral_names() -> frozenset[str]:
+    return _load_behavioral_registry()[0]
+
+
+def _required_payload_map() -> dict[str, tuple[str, ...]]:
+    return _load_behavioral_registry()[1]
+
+
+def clear_registry_cache() -> None:
+    """Reset the in-process registry cache. Used by tests."""
+    _load_behavioral_registry.cache_clear()
+
+
+class _LazyKnownEvents:
+    """Lazy proxy for ``KNOWN_EVENTS`` that hits the unified registry.
+
+    Read-only ``frozenset``-compatible accessor so existing test code
+    using ``KNOWN_EVENTS == frozenset({...})`` and ``name in KNOWN_EVENTS``
+    continues to work unchanged. Resolves on every access so a test that
+    points the registry at a fixture path can still re-read after
+    ``clear_registry_cache()``.
+    """
+
+    def _resolved(self) -> frozenset[str]:
+        return _registered_behavioral_names()
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._resolved()
+
+    def __iter__(self):
+        return iter(self._resolved())
+
+    def __len__(self) -> int:
+        return len(self._resolved())
+
+    def __eq__(self, other: object) -> bool:
+        return self._resolved() == other
+
+    def __hash__(self) -> int:
+        return hash(self._resolved())
+
+    def __repr__(self) -> str:
+        return repr(self._resolved())
+
+
+class _LazyRequiredPayload:
+    """Lazy proxy for ``REQUIRED_PAYLOAD`` -- behaves like a read-only dict."""
+
+    def _resolved(self) -> dict[str, tuple[str, ...]]:
+        return _required_payload_map()
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._resolved()
+
+    def __getitem__(self, key: str) -> tuple[str, ...]:
+        return self._resolved()[key]
+
+    def get(
+        self, key: str, default: tuple[str, ...] = ()
+    ) -> tuple[str, ...]:
+        return self._resolved().get(key, default)
+
+    def __iter__(self):
+        return iter(self._resolved())
+
+    def __len__(self) -> int:
+        return len(self._resolved())
+
+    def items(self):
+        return self._resolved().items()
+
+    def keys(self):
+        return self._resolved().keys()
+
+    def values(self):
+        return self._resolved().values()
+
+    def __eq__(self, other: object) -> bool:
+        return self._resolved() == other
+
+    def __repr__(self) -> str:
+        return repr(self._resolved())
+
+
+# Public lazy module-level constants. Existing callers (tests, CLI, the
+# migrator's _legacy_event_emitter) keep their existing import shape:
+#   from _events import KNOWN_EVENTS, REQUIRED_PAYLOAD
+# but the values now resolve from events/registry.json on each access
+# rather than a hard-coded frozenset.
+KNOWN_EVENTS: _LazyKnownEvents = _LazyKnownEvents()
+REQUIRED_PAYLOAD: _LazyRequiredPayload = _LazyRequiredPayload()
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def _resolve_log_path(log_path: Path | str | None) -> Path:
+    if log_path is not None:
+        return Path(log_path)
+    env_path = os.environ.get("DEFT_EVENT_LOG")
+    if env_path:
+        return Path(env_path)
+    return DEFAULT_EVENT_LOG
+
+
+def _new_event_id() -> str:
+    """Return a sortable, collision-resistant event id.
+
+    Format: ``<unix-ns>-<8-hex-rand>``. Sortable by emission time so the
+    log can be diffed cleanly; rand suffix prevents collision when two
+    emissions land in the same nanosecond (rare but possible on Windows).
+    """
+    return f"{time.time_ns()}-{secrets.token_hex(4)}"
+
+
+def emit(
+    name: str,
+    payload: dict[str, Any],
+    *,
+    log_path: Path | str | None = None,
+    detected_at: str | None = None,
+) -> dict[str, Any]:
+    """Append an event record to the JSONL log and return it.
+
+    ``name`` MUST be a registered event from ``KNOWN_EVENTS``. ``payload``
+    MUST contain the required fields for that event per
+    ``REQUIRED_PAYLOAD``. ``detected_at`` defaults to the current UTC
+    timestamp (ISO 8601, second precision).
+
+    Raises ``ValueError`` for an unknown event name or a missing required
+    payload field.
+    """
+    behavioral_names = _registered_behavioral_names()
+    if name not in behavioral_names:
+        raise ValueError(
+            f"unknown event {name!r}; expected one of "
+            f"{sorted(behavioral_names)}"
+        )
+    required = _required_payload_map().get(name, ())
+    missing = [k for k in required if k not in payload]
+    if missing:
+        raise ValueError(
+            f"event {name!r} payload missing required fields: {missing}"
+        )
+
+    record: dict[str, Any] = {
+        "event": name,
+        "id": _new_event_id(),
+        "detected_at": detected_at
+        or datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "payload": dict(payload),
+    }
+
+    target = _resolve_log_path(log_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(record, ensure_ascii=False, sort_keys=True)
+    with target.open("a", encoding="utf-8") as fh:
+        fh.write(line)
+        fh.write("\n")
+    return record
+
+
+def read_events(
+    log_path: Path | str | None = None,
+) -> list[dict[str, Any]]:
+    """Return all events from the log in emission order.
+
+    Missing log returns an empty list. Malformed lines are skipped (the
+    log is append-only; a partial last line could survive a crash).
+    """
+    target = _resolve_log_path(log_path)
+    if not target.exists():
+        return []
+    out: list[dict[str, Any]] = []
+    with target.open("r", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return out
+
+
+def validate_pairing(
+    events: Iterable[dict[str, Any]] | None = None,
+    *,
+    log_path: Path | str | None = None,
+) -> list[dict[str, Any]]:
+    """Return the list of orphan ``session:resumed`` records.
+
+    A ``session:resumed`` is an orphan if its ``interrupted_id`` does not
+    match the ``id`` of any prior, *unconsumed* ``session:interrupted``
+    in the same log. Each interrupt id satisfies at most one resumed
+    event -- a second ``session:resumed`` referencing the same
+    ``interrupted_id`` is treated as an orphan (1:1 pairing per the
+    vBRIEF "co-emitted" semantics, Greptile #706 P2).
+
+    Pass ``events`` explicitly to validate an in-memory stream; otherwise
+    the helper reads the configured log path.
+    """
+    if events is None:
+        events = read_events(log_path=log_path)
+    open_interrupts: set[str] = set()
+    orphans: list[dict[str, Any]] = []
+    for record in events:
+        name = record.get("event")
+        if name == "session:interrupted":
+            event_id = record.get("id")
+            if isinstance(event_id, str):
+                open_interrupts.add(event_id)
+        elif name == "session:resumed":
+            payload = record.get("payload") or {}
+            ref = payload.get("interrupted_id")
+            if isinstance(ref, str) and ref in open_interrupts:
+                # 1:1 pairing: consume the interrupt id so a second
+                # session:resumed referencing the same id is reported
+                # as an orphan.
+                open_interrupts.discard(ref)
+            else:
+                orphans.append(record)
+    return orphans
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def _parse_payload_args(args: argparse.Namespace) -> dict[str, Any]:
+    """Build the payload dict from the parsed CLI args.
+
+    The ``--payload`` JSON arg, when present, is the seed; named flags
+    overlay on top so agents can mix structured input with one-off
+    fields.
+    """
+    payload: dict[str, Any] = {}
+    if args.payload:
+        try:
+            data = json.loads(args.payload)
+        except json.JSONDecodeError as exc:
+            raise SystemExit(f"--payload is not valid JSON: {exc}") from exc
+        if not isinstance(data, dict):
+            raise SystemExit("--payload must be a JSON object")
+        payload.update(data)
+
+    # Named overlays (only set if provided).
+    name_to_field = {
+        "session_id": args.session_id,
+        "reason": args.reason,
+        "interrupted_id": args.interrupted_id,
+        "plan_ref": args.plan_ref,
+        "approver": args.approver,
+        "approval_phrase": args.approval_phrase,
+        "pr_number": args.pr_number,
+        "detail": args.detail,
+        "title": args.title,
+        "source": args.source,
+        "range": args.range_,
+        "size_bytes": args.size_bytes,
+        "inline": args.inline,
+        "sidecar": args.sidecar,
+        "flagged": args.flagged,
+    }
+    for k, v in name_to_field.items():
+        if v is not None:
+            payload[k] = v
+    return payload
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m scripts._events",
+        description="Emit and inspect structural framework events.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    emit_p = sub.add_parser("emit", help="Append an event to the log.")
+    emit_p.add_argument("name", choices=sorted(_registered_behavioral_names()))
+    emit_p.add_argument("--payload", help="JSON object with the payload.")
+    emit_p.add_argument("--log", dest="log", help="Override event log path.")
+    # Convenience flags. Using --range- on the dest avoids shadowing the
+    # builtin ``range``.
+    emit_p.add_argument("--session-id")
+    emit_p.add_argument("--reason")
+    emit_p.add_argument("--interrupted-id")
+    emit_p.add_argument("--plan-ref")
+    emit_p.add_argument("--approver")
+    emit_p.add_argument("--approval-phrase")
+    emit_p.add_argument("--pr-number", type=int)
+    emit_p.add_argument("--detail")
+    emit_p.add_argument("--title")
+    emit_p.add_argument("--source")
+    emit_p.add_argument("--range", dest="range_")
+    emit_p.add_argument("--size-bytes", type=int)
+    emit_p.add_argument(
+        "--inline",
+        type=lambda s: s.lower() in {"1", "true", "yes"},
+        default=None,
+    )
+    emit_p.add_argument("--sidecar")
+    emit_p.add_argument(
+        "--flagged",
+        type=lambda s: s.lower() in {"1", "true", "yes"},
+        default=None,
+    )
+
+    list_p = sub.add_parser("list", help="Print events as JSON lines.")
+    list_p.add_argument("--log", dest="log", help="Override event log path.")
+
+    pair_p = sub.add_parser(
+        "validate-pairing",
+        help="Exit non-zero if any session:resumed is orphan.",
+    )
+    pair_p.add_argument("--log", dest="log", help="Override event log path.")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_arg_parser()
+    args = parser.parse_args(argv)
+
+    if args.cmd == "emit":
+        payload = _parse_payload_args(args)
+        try:
+            record = emit(args.name, payload, log_path=args.log)
+        except ValueError as exc:
+            sys.stderr.write(f"emit failed: {exc}\n")
+            return 2
+        sys.stdout.write(json.dumps(record, ensure_ascii=False))
+        sys.stdout.write("\n")
+        return 0
+
+    if args.cmd == "list":
+        for record in read_events(log_path=args.log):
+            sys.stdout.write(
+                json.dumps(record, ensure_ascii=False, sort_keys=True)
+            )
+            sys.stdout.write("\n")
+        return 0
+
+    if args.cmd == "validate-pairing":
+        orphans = validate_pairing(log_path=args.log)
+        if orphans:
+            sys.stderr.write(
+                f"orphan session:resumed records ({len(orphans)}): "
+                f"{[r.get('id') for r in orphans]}\n"
+            )
+            return 1
+        sys.stdout.write("ok\n")
+        return 0
+
+    parser.print_help()
+    return 2
+
+
+__all__ = [
+    "DEFAULT_EVENT_LOG",
+    "KNOWN_EVENTS",
+    "REQUIRED_PAYLOAD",
+    "clear_registry_cache",
+    "emit",
+    "main",
+    "read_events",
+    "validate_pairing",
+]
+
+
+if __name__ == "__main__":  # pragma: no cover - thin CLI shim
+    raise SystemExit(main())