alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/subscribers/weave_intent_writer.py

@@ -0,0 +1,608 @@
+"""WeaveIntentWriter - projects intent signals into the weave-intent.jsonl stream.
+
+D-WEAVE-VC-2 §8 items 1 + 2 (S1 + S2).
+
+Owns ``~/.local/share/alter-runtime/weave-intent.jsonl``, writing ``intent.*``
+records with explicit ``ttl_seconds`` + ``expires_at`` fields.
+
+Two producers feed this writer:
+
+(a) **cc-intent.sh hook** (built by a separate agent, NOT this module).
+    The hook runs on PreToolUse Edit|Write inside Claude Code and appends
+    JSONL records of kind ``intent.edit`` directly to ``weave-intent.jsonl``
+    with fields::
+
+        {kind, source, session_id, handle, file_path, anchor, ts (ISO-8601 string), ttl_seconds}
+
+    The writer tails this file for records it did NOT write itself, then
+    enriches them with a ``semantic_unit`` field via the tree-sitter resolver
+    (S2) and re-appends the enriched record.
+
+(b) **WorktreeWatcher bus events** (kind ``"worktree_edit"`` on ``local.signal``).
+    Plain-editor saves with no ``intent.edit`` partner emit a coarse
+    ``worktree_edit`` record — modelled as a dangling edge per D-WEAVE-VC-2
+    §3 degradation.
+
+Ingestion design decision
+--------------------------
+
+The writer must NOT circularly tail the same file it appends to.  The design
+chosen is a ``source`` field sentinel:
+
+1. Records written by THIS writer carry ``"source": "weave_intent_writer"``.
+2. The tailer skips any record whose ``source`` matches this sentinel, so
+   enriched re-appended records are not re-processed.
+3. Hook-originated records carry ``"source": "cc_intent_hook"`` (or omit
+   ``source`` entirely) — the tailer picks those up for enrichment.
+
+This means a single file carries both raw hook records and enriched records.
+Consumers that want only enriched records filter on ``semantic_unit`` presence;
+consumers that want the full audit trail read everything.
+
+Advisory-only invariant
+------------------------
+
+Nothing in this module blocks, leases, or gates a write.  The writer records;
+it never arbitrates.  See D-WEAVE-VC-2 §2 advisory doctrine.
+
+TTL
+---
+
+Default TTL is 900 seconds (15 minutes), configurable via
+``ALTER_RUNTIME_WEAVE_INTENT_TTL`` env var or constructor argument.  Every
+record carries ``ttl_seconds`` (integer) and ``expires_at`` (ISO-8601 UTC
+datetime string) for consumer convenience.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import errno
+import fcntl
+import json
+import logging
+import os
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+# TYPE_CHECKING import for EventBus avoids circular dependency at runtime
+from typing import TYPE_CHECKING, Any
+
+from alter_runtime.config import DaemonConfig, data_dir
+from alter_runtime.daemon import Component
+
+if TYPE_CHECKING:
+    from alter_runtime.subscribers.bus import EventBus
+
+__all__ = [
+    "WEAVE_INTENT_FILENAME",
+    "DEFAULT_TTL_SECONDS",
+    "WRITER_SOURCE_SENTINEL",
+    "WeaveIntentWriter",
+]
+
+logger = logging.getLogger("alter_runtime.subscribers.weave_intent_writer")
+
+#: Filename for the weave-intent JSONL (within ``data_dir()``).
+WEAVE_INTENT_FILENAME: str = "weave-intent.jsonl"
+
+#: Default intent TTL in seconds — 15-minute hypothesis per D-WEAVE-VC-2 §10 Q1.
+#: Override via ALTER_RUNTIME_WEAVE_INTENT_TTL env var.
+DEFAULT_TTL_SECONDS: int = 900
+
+#: Source sentinel written on every record this module appends.
+#: The tailer skips records with this sentinel to avoid circular re-processing.
+WRITER_SOURCE_SENTINEL: str = "weave_intent_writer"
+
+#: How often (seconds) the tailer polls the intent file for new hook records.
+_TAIL_POLL_INTERVAL: float = 0.5
+
+#: Rotation threshold: 5 MiB
+ROTATION_THRESHOLD_BYTES: int = 5 * 1024 * 1024
+
+
+class WeaveIntentWriter(Component):
+    """Subscribes to local.signal worktree_edit events and tails weave-intent.jsonl
+    for cc-intent hook records, writing enriched intent.* records.
+
+    Parameters
+    ----------
+    config:
+        Loaded :class:`DaemonConfig`.
+    bus:
+        Shared :class:`EventBus`. Subscribes to ``local.signal``.
+    intent_path:
+        Override the JSONL path. Tests redirect writes to ``tmp_path``.
+    ttl_seconds:
+        Intent TTL in seconds. Defaults to ``DEFAULT_TTL_SECONDS`` (900s).
+    tail_poll_interval:
+        How often (seconds) to poll the intent file for new hook records.
+    """
+
+    name = "weave_intent_writer"
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        bus: EventBus,
+        *,
+        intent_path: Path | None = None,
+        ttl_seconds: int | None = None,
+        tail_poll_interval: float = _TAIL_POLL_INTERVAL,
+    ) -> None:
+        self._config = config
+        self._bus = bus
+
+        self._intent_path: Path = (
+            intent_path if intent_path is not None else data_dir() / WEAVE_INTENT_FILENAME
+        )
+
+        # TTL: constructor arg > env var > default
+        if ttl_seconds is not None:
+            self._ttl_seconds = int(ttl_seconds)
+        else:
+            env_val = os.environ.get("ALTER_RUNTIME_WEAVE_INTENT_TTL")
+            if env_val:
+                try:
+                    self._ttl_seconds = int(env_val)
+                except (ValueError, TypeError):
+                    logger.warning(
+                        "weave_intent_writer: invalid ALTER_RUNTIME_WEAVE_INTENT_TTL=%r — "
+                        "using default %ds",
+                        env_val,
+                        DEFAULT_TTL_SECONDS,
+                    )
+                    self._ttl_seconds = DEFAULT_TTL_SECONDS
+            else:
+                self._ttl_seconds = DEFAULT_TTL_SECONDS
+
+        self._tail_poll_interval = tail_poll_interval
+        self._shutdown_event = asyncio.Event()
+        self._write_lock = asyncio.Lock()
+        #: Byte offset into the intent file up to which we have already processed
+        #: hook-originated records.
+        self._tail_offset: int = 0
+
+    # ------------------------------------------------------------------
+    # Component lifecycle
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        self._bus.subscribe("local.signal", self._handle_bus_event)
+        logger.info(
+            "weave_intent_writer started path=%s ttl=%ds",
+            self._intent_path,
+            self._ttl_seconds,
+        )
+
+        # Seed the tail offset to the current end-of-file so we don't
+        # re-process records that were written before this daemon started.
+        self._tail_offset = self._current_file_size()
+
+        tail_task = asyncio.create_task(self._tail_loop())
+        try:
+            await self._shutdown_event.wait()
+        except asyncio.CancelledError:
+            raise
+        finally:
+            with contextlib.suppress(Exception):
+                self._bus.unsubscribe("local.signal", self._handle_bus_event)
+            tail_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await tail_task
+            logger.info("weave_intent_writer stopped")
+
+    async def stop(self) -> None:
+        self._shutdown_event.set()
+
+    # ------------------------------------------------------------------
+    # Bus event handler (producer b — WorktreeWatcher)
+    # ------------------------------------------------------------------
+
+    async def _handle_bus_event(self, event: dict[str, Any]) -> None:
+        """Handle local.signal events from the bus."""
+        if not isinstance(event, dict):
+            return
+        if event.get("kind") != "worktree_edit":
+            return
+
+        payload = event.get("payload", {})
+        if not isinstance(payload, dict):
+            return
+
+        file_path = payload.get("file_path", "")
+        rel_path = payload.get("rel_path", "")
+        ts = payload.get("ts") or datetime.now(timezone.utc).isoformat()
+
+        record = self._build_worktree_edit_record(
+            file_path=file_path,
+            rel_path=rel_path,
+            ts=ts,
+        )
+        await self._append_record(record)
+
+    def _build_worktree_edit_record(
+        self,
+        file_path: str,
+        rel_path: str,
+        ts: str,
+    ) -> dict[str, Any]:
+        """Build a coarse worktree_edit intent record (dangling edge)."""
+        expires_at = _compute_expires_at(ts, self._ttl_seconds)
+        return {
+            "kind": "intent.worktree_edit",
+            "file_path": file_path,
+            "rel_path": rel_path,
+            "ts": ts,
+            "ttl_seconds": self._ttl_seconds,
+            "expires_at": expires_at,
+            "source": WRITER_SOURCE_SENTINEL,
+            # Dangling edge — no session_id / handle / anchor from a plain save.
+            # Consumers that need a paired intent.edit record check for presence
+            # of session_id. This coarse record enables file-level advisory even
+            # when the CC hook is not active.
+            "dangling": True,
+        }
+
+    # ------------------------------------------------------------------
+    # Tailer loop (producer a — cc-intent.sh hook records)
+    # ------------------------------------------------------------------
+
+    async def _tail_loop(self) -> None:
+        """Poll the intent file on an interval and process new hook records."""
+        while not self._shutdown_event.is_set():
+            try:
+                await self._process_new_hook_records()
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # pragma: no cover
+                logger.warning("weave_intent_writer: tail loop error: %s", exc)
+
+            try:
+                await asyncio.wait_for(
+                    asyncio.shield(self._shutdown_event.wait()),
+                    timeout=self._tail_poll_interval,
+                )
+                return  # shutdown requested
+            except (TimeoutError, asyncio.TimeoutError):
+                pass  # normal poll interval expiry
+
+    async def _process_new_hook_records(self) -> None:
+        """Read new bytes from the intent file since the last tail offset
+        and process any hook-originated records.
+
+        Circular re-processing is prevented by skipping records whose
+        ``source`` field matches ``WRITER_SOURCE_SENTINEL``.
+        """
+        if not self._intent_path.exists():
+            return
+
+        try:
+            current_size = self._intent_path.stat().st_size
+        except OSError:
+            return
+
+        if current_size <= self._tail_offset:
+            # File shrunk (rotation) — reset to 0
+            if current_size < self._tail_offset:
+                logger.debug(
+                    "weave_intent_writer: file shrunk (rotation?) "
+                    "old_offset=%d new_size=%d — resetting",
+                    self._tail_offset,
+                    current_size,
+                )
+                self._tail_offset = 0
+            return
+
+        try:
+            with open(self._intent_path, "rb") as fh:
+                fh.seek(self._tail_offset)
+                chunk = fh.read(current_size - self._tail_offset)
+        except OSError as exc:
+            logger.warning("weave_intent_writer: tail read failed: %s", exc)
+            return
+
+        self._tail_offset = current_size
+
+        if not chunk:
+            return
+
+        lines = chunk.decode("utf-8", errors="replace").splitlines()
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(record, dict):
+                continue
+
+            # Skip records this writer produced (circular-processing guard)
+            if record.get("source") == WRITER_SOURCE_SENTINEL:
+                continue
+
+            # Only process hook-originated intent.edit records
+            if record.get("kind") not in ("intent.edit", None):
+                # Accept records that lack a kind (legacy hook format) and
+                # explicit intent.edit records.
+                if record.get("kind") is not None:
+                    continue
+
+            try:
+                await self._enrich_and_append(record)
+            except Exception as exc:  # pragma: no cover
+                logger.warning(
+                    "weave_intent_writer: failed to enrich record %r: %s — skipping",
+                    record,
+                    exc,
+                )
+
+    async def _enrich_and_append(self, raw: dict[str, Any]) -> None:
+        """Enrich a raw hook record with semantic_unit (S2) and re-append."""
+        file_path = raw.get("file_path", "")
+        anchor = raw.get("anchor")
+
+        # Normalise ts before any downstream use — accepts ISO string, epoch
+        # int/float, or None.  This is the primary fix for the AttributeError
+        # raised when cc-intent.sh (legacy) emitted ts as an epoch integer and
+        # _compute_expires_at called ts.rstrip("Z") on it.
+        ts = _normalise_ts(raw.get("ts"))
+
+        # S2: resolve semantic unit — must NEVER block or raise into daemon
+        semantic_unit = _resolve_semantic_unit(file_path, anchor)
+
+        # Accept both ttl_seconds (new contract) and ttl (legacy fallback) so
+        # the writer remains resilient to older hook versions in the wild.
+        ttl = raw.get("ttl_seconds", raw.get("ttl", self._ttl_seconds))
+        try:
+            ttl = int(ttl)
+        except (TypeError, ValueError):
+            ttl = self._ttl_seconds
+
+        expires_at = _compute_expires_at(ts, ttl)
+
+        enriched: dict[str, Any] = {
+            "kind": "intent.edit",
+            "session_id": raw.get("session_id"),
+            "handle": raw.get("handle"),
+            "file_path": file_path,
+            "anchor": anchor,
+            "ts": ts,
+            "ttl_seconds": ttl,
+            "expires_at": expires_at,
+            "source": WRITER_SOURCE_SENTINEL,
+        }
+        if semantic_unit is not None:
+            enriched["semantic_unit"] = {
+                "symbol": semantic_unit.symbol,
+                "kind": semantic_unit.kind,
+                "qualified_name": semantic_unit.qualified_name,
+                "file_path": semantic_unit.file_path,
+                "start_line": semantic_unit.start_line,
+                "end_line": semantic_unit.end_line,
+            }
+        else:
+            # Degrade to file-level — record absence explicitly
+            enriched["semantic_unit"] = None
+
+        await self._append_record(enriched)
+
+    # ------------------------------------------------------------------
+    # File operations
+    # ------------------------------------------------------------------
+
+    async def _append_record(self, record: dict[str, Any]) -> None:
+        """Serialise and append one record to the intent JSONL."""
+        async with self._write_lock:
+            line = json.dumps(record, separators=(",", ":"), ensure_ascii=False)
+            try:
+                self._maybe_rotate()
+            except OSError as exc:
+                logger.warning("weave_intent_writer: rotation failed: %s", exc)
+
+            try:
+                self._append_line(line)
+            except OSError as exc:
+                logger.warning("weave_intent_writer: append failed: %s — dropping record", exc)
+
+    def _ensure_parent(self) -> None:
+        parent = self._intent_path.parent
+        if not parent.exists():
+            parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        with contextlib.suppress(OSError):
+            os.chmod(parent, 0o700)
+
+    def _append_line(self, line: str) -> None:
+        self._ensure_parent()
+        flags = os.O_WRONLY | os.O_CREAT | os.O_APPEND
+        fd = os.open(self._intent_path, flags, 0o600)
+        try:
+            with contextlib.suppress(OSError):
+                os.fchmod(fd, 0o600)
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX)
+            except OSError as exc:
+                if exc.errno not in (errno.ENOTSUP, errno.EINVAL):
+                    raise
+            try:
+                os.write(fd, line.encode("utf-8") + b"\n")
+                os.fsync(fd)
+            finally:
+                with contextlib.suppress(OSError):
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+        finally:
+            os.close(fd)
+
+    def _maybe_rotate(self) -> None:
+        try:
+            size = self._intent_path.stat().st_size
+        except FileNotFoundError:
+            return
+        if size <= ROTATION_THRESHOLD_BYTES:
+            return
+        rotated = self._intent_path.parent / (WEAVE_INTENT_FILENAME + ".1")
+        os.replace(self._intent_path, rotated)
+        # Reset tail offset — after rotation the active file starts at 0.
+        self._tail_offset = 0
+        logger.info(
+            "weave_intent_writer: rotated %s -> %s (size=%d)",
+            self._intent_path,
+            rotated,
+            size,
+        )
+
+    def _current_file_size(self) -> int:
+        try:
+            return self._intent_path.stat().st_size
+        except OSError:
+            return 0
+
+    # ------------------------------------------------------------------
+    # Test introspection
+    # ------------------------------------------------------------------
+
+    @property
+    def intent_path(self) -> Path:
+        return self._intent_path
+
+    @property
+    def ttl_seconds(self) -> int:
+        return self._ttl_seconds
+
+
+# ---------------------------------------------------------------------------
+# S2: semantic-unit resolver shim
+# ---------------------------------------------------------------------------
+
+
+def _resolve_semantic_unit(
+    file_path: str,
+    anchor: str | None,
+) -> Any | None:
+    """Call the tree-sitter resolver and return a SemanticUnit or None.
+
+    Resolution failure NEVER blocks or raises — it degrades to None
+    (file-level intent) per the S2 constraint.
+
+    Parameters
+    ----------
+    file_path:
+        Absolute or relative path to the Python source file being edited.
+    anchor:
+        The head of the old_string / Write target from the CC hook.
+        Used to derive an approximate line number when an explicit
+        line_range is not available.  When absent, defaults to line (1, 1)
+        which returns the module-level unit.
+    """
+    try:
+        from alter_runtime.weave.resolver import resolve as _resolve
+
+        # Derive a coarse line range from the anchor text if present.
+        # The anchor is the first line of the CC old_string, so we
+        # search for it in the file and use its 1-based line number.
+        line_range = _anchor_to_line_range(file_path, anchor)
+        return _resolve(file_path, line_range)
+
+    except Exception as exc:  # pragma: no cover
+        logger.debug(
+            "weave_intent_writer: resolve failed for %r: %s — degrading to file-level",
+            file_path,
+            exc,
+        )
+        return None
+
+
+def _anchor_to_line_range(file_path: str, anchor: str | None) -> tuple[int, int]:
+    """Return a best-guess (start, end) line range for the anchor text.
+
+    If the anchor is not present or cannot be found in the file, returns (1, 1)
+    which causes the resolver to return the module-level unit.  This is the
+    correct degradation — a missing anchor gives file-level intent, not an error.
+    """
+    if not anchor or not file_path:
+        return (1, 1)
+
+    try:
+        p = Path(file_path)
+        if not p.exists():
+            return (1, 1)
+
+        # Only scan the first line of the anchor for speed — exact match wins.
+        anchor_first_line = anchor.splitlines()[0].strip() if anchor.strip() else ""
+        if not anchor_first_line:
+            return (1, 1)
+
+        content = p.read_text(encoding="utf-8", errors="replace")
+        for lineno, line in enumerate(content.splitlines(), start=1):
+            if anchor_first_line in line:
+                return (lineno, lineno)
+
+        return (1, 1)
+
+    except Exception:
+        return (1, 1)
+
+
+# ---------------------------------------------------------------------------
+# TTL helper
+# ---------------------------------------------------------------------------
+
+
+def _normalise_ts(value: Any) -> str:
+    """Return an ISO-8601 UTC string from an ISO string, epoch int/float, or None.
+
+    Parameters
+    ----------
+    value:
+        Accepted inputs:
+        - ISO-8601 string (with or without trailing ``Z``): returned as-is
+          after stripping the ``Z`` and re-attaching UTC timezone.
+        - ``int`` or ``float``: treated as a POSIX epoch and converted via
+          ``datetime.fromtimestamp``.
+        - ``None`` or anything unparseable: falls back to now (UTC).
+    """
+    if value is None:
+        return datetime.now(timezone.utc).isoformat()
+
+    if isinstance(value, (int, float)):
+        try:
+            return datetime.fromtimestamp(value, tz=timezone.utc).isoformat()
+        except (OSError, OverflowError, ValueError):
+            return datetime.now(timezone.utc).isoformat()
+
+    if isinstance(value, str):
+        try:
+            ts_stripped = value.rstrip("Z")
+            if "+" in ts_stripped:
+                dt = datetime.fromisoformat(value)
+            else:
+                dt = datetime.fromisoformat(ts_stripped).replace(tzinfo=timezone.utc)
+            return dt.isoformat()
+        except (ValueError, TypeError):
+            return datetime.now(timezone.utc).isoformat()
+
+    # Unknown type — fall back to now
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _compute_expires_at(ts: Any, ttl_seconds: int) -> str:
+    """Return an ISO-8601 UTC datetime string for ``ts + ttl_seconds``.
+
+    Accepts ``ts`` as an ISO-8601 string, an epoch int/float, or None.
+    Falls back to now + ttl_seconds when ``ts`` cannot be parsed.
+    """
+    try:
+        normalised = _normalise_ts(ts)
+        ts_stripped = normalised.rstrip("Z")
+        if "+" in ts_stripped:
+            dt = datetime.fromisoformat(normalised)
+        else:
+            dt = datetime.fromisoformat(ts_stripped).replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError, AttributeError):
+        dt = datetime.now(timezone.utc)
+
+    expires = dt + timedelta(seconds=ttl_seconds)
+    return expires.isoformat()