alissa-tools-github-devloop 0.8.13__tar.gz → 0.8.14__tar.gz

{alissa_tools_github_devloop-0.8.13/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.13
+Version: 0.8.14
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.14}/src/main/alissa/tools/github/devloop/__main__.py

@@ -282,6 +282,26 @@ def build_parser() -> argparse.ArgumentParser:
         "(two overlapping instances can then both spawn on one item)",
     )
 
+    loop_events = over.add_mutually_exclusive_group()
+    loop_events.add_argument(
+        "--loop-events",
+        dest="loop_events_enabled",
+        action="store_true",
+        default=None,
+        help="push one idempotent batch of loop events (spawns, defers, "
+        "cap-outs, stalls, hand-offs, reaps, escalations) per poll pass to "
+        "Studio's POST /v1/loop-events on the alissa endpoint — best-effort, "
+        "never fatal. ALISSA_DEV_LOOP_EVENTS_ENABLED (non-blank) overrides "
+        "even this flag",
+    )
+    loop_events.add_argument(
+        "--no-loop-events",
+        dest="loop_events_enabled",
+        action="store_false",
+        help="never push loop telemetry, even if the config enables it "
+        "(the default: the push is opt-in)",
+    )
+
     janitor = over.add_mutually_exclusive_group()
     janitor.add_argument(
         "--janitor",
@@ -386,6 +406,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "orphan_sweep_enabled": args.orphan_sweep_enabled,
         "orphan_grace_minutes": args.orphan_grace_minutes,
         "activity_claims_enabled": args.activity_claims_enabled,
+        "loop_events_enabled": args.loop_events_enabled,
         "janitor_enabled": args.janitor_enabled,
         "janitor_grace_minutes": args.janitor_grace_minutes,
         "janitor_interval_minutes": args.janitor_interval_minutes,
@@ -500,6 +521,13 @@ def log_effective_config(config: Config, login: str) -> None:
         config.cache_cap_mb,
         config.disk_warn_percent,
     )
+    log.info(
+        "loop_events=%s%s",
+        config.loop_events_enabled,
+        f" (one batch per pass → POST {config.alissa_endpoint}"
+        f"/v1/loop-events, best-effort)"
+        if config.loop_events_enabled else "",
+    )
     log.debug("hub_template: %s", config.hub_template)
     log.debug(
         "cache_paths: %s",

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.14}/src/main/alissa/tools/github/devloop/alissa_client.py

@@ -22,7 +22,12 @@ already authenticates — the same transport, endpoints and taxonomy orcloop's
 `urllib` only: the distribution ships no third-party runtime dependency, and
 this must not be the change that adds one.
 
-Endpoints, both verified against the live API:
+Since issue #101 the adapter also carries the daemon's ONE write —
+``POST /v1/loop-events`` (`post_loop_events`), the loop-telemetry push — over
+the same transport, token and taxonomy, so the daemon still reads and writes
+Alissa through a single REST idiom.
+
+Endpoints, the reads both verified against the live API:
 
 ``GET /v1/ping``
     ``{"pong", "timestamp", "userId", "actorId", "displayName"}`` — the
@@ -141,22 +146,32 @@ class AlissaClient:
         self._token = token if token is not None else os.environ.get(ENV_TOKEN)
         self._timeout = timeout
 
-    def _request(self, path: str) -> object:
-        """One GET. Every failure leaves as a taxonomy exception — the caller
-        never sees a raw urllib error or an HTTP status."""
+    def _request(
+        self, path: str, *, method: str = "GET", body: object = None
+    ) -> object:
+        """One call. Every failure leaves as a taxonomy exception — the caller
+        never sees a raw urllib error or an HTTP status. `body`, when given,
+        is JSON-serialised and sent with the matching Content-Type (the shape
+        every write on this API takes)."""
         if not self._token:
             # No token at all is an auth condition, not a transport one: the
             # operator must set the env var. Fail the way a 401 would, so the
             # boot path treats it as permanent rather than retrying forever.
             raise AlissaAuthError(0, f"{ENV_TOKEN} is not set")
 
+        headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._token}",
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
         req = urllib.request.Request(
             f"{self.base}{path}",
-            method="GET",
-            headers={
-                "Accept": "application/json",
-                "Authorization": f"Bearer {self._token}",
-            },
+            method=method,
+            data=data,
+            headers=headers,
         )
         try:
             with urllib.request.urlopen(req, timeout=self._timeout) as resp:
@@ -226,6 +241,27 @@ class AlissaClient:
             display_name=str(row.get("displayName") or ""),
         )
 
+    def post_loop_events(self, events: "list[dict]") -> "dict":
+        """Push one batch of loop-telemetry events (issue #101).
+
+        ``POST /v1/loop-events`` (fahera-mx/studio.alissa.app, `API.md` →
+        "Loop telemetry — ingest"): 1–200 events per call, idempotent on the
+        caller's `dedupeKey` — a repeated key is a silent duplicate, never an
+        error — and any shape error fails the WHOLE batch with a 400 naming
+        the offending index. The batch bound and the event shapes are the
+        CALLER's contract (`loop_events.py` derives and splits); this method
+        is just the transport, returning the server's
+        ``{"accepted": n, "duplicates": m}`` verbatim.
+
+        Failures leave as the taxonomy like every other call here. The one
+        caller is best-effort by design — it catches AlissaError, warns once
+        and moves on — so nothing extra is softened at this layer.
+        """
+        payload = self._request(
+            "/v1/loop-events", method="POST", body={"events": list(events)}
+        )
+        return payload if isinstance(payload, dict) else {}
+
     def list_bodies_of_work(self) -> "list[BodyOfWork]":
         """Every Body of Work this actor owns OR collaborates on — ONE call.
 

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.14}/src/main/alissa/tools/github/devloop/config.py

@@ -21,6 +21,8 @@ var > `--repos-source` > the config key. A BLANK env var means "not set" here
 (unlike ALISSA_DEV_REVIEWERS, where empty is a meaningful answer): an unset
 platform variable reference renders as the empty string, and that must fall
 through to the config rather than fail the daemon's boot on a mode of `''`.
+`loop_events_enabled` rides the same shape of rail through
+`ALISSA_DEV_LOOP_EVENTS_ENABLED`, with the same blank-falls-through rule.
 """
 
 from __future__ import annotations
@@ -88,6 +90,18 @@ ENV_REPOS_SOURCE = "ALISSA_DEV_REPOS_SOURCE"
 # `alissa_endpoint` so one deployment can point both daemons at one API.
 DEFAULT_ALISSA_ENDPOINT = "https://api.alissa.app"
 
+# The loop-telemetry rail (issue #101): `loop_events_enabled` ridden the way
+# ALISSA_DEV_REPOS_SOURCE rides repos_source — a NON-BLANK value here wins
+# over the CLI and the file alike, and a blank one falls through (an unset
+# platform variable reference renders as "", which must not decide anything).
+# Accepted spellings are 1/true/0/false, case-insensitive; anything else is a
+# config error at boot — a typo silently read as false would leave an operator
+# staring at a variable that does nothing.
+ENV_LOOP_EVENTS = "ALISSA_DEV_LOOP_EVENTS_ENABLED"
+
+_ENV_BOOL_TRUE = frozenset(("1", "true"))
+_ENV_BOOL_FALSE = frozenset(("0", "false"))
+
 # What an Alissa actor id looks like: a 32-character opaque handle of
 # lower-case letters and digits (`j5706fv7xe5jy1k5wdwzacab9s8axcd2`). Every id
 # the API mints has this shape, and `bow_owners` is checked against it so a
@@ -138,6 +152,7 @@ CONFIG_KEYS = (
     "orphan_sweep_enabled",
     "orphan_grace_minutes",
     "activity_claims_enabled",
+    "loop_events_enabled",
     "janitor_enabled",
     "janitor_grace_minutes",
     "janitor_interval_minutes",
@@ -499,6 +514,18 @@ class Config:
     # that would rather not pay the extra comments fetch.
     activity_claims_enabled: bool = True
 
+    # The loop-telemetry push (issue #101): at the end of each poll pass,
+    # POST one idempotent batch of the ledger-derived loop events — spawns,
+    # defers, cap-outs, stalls, hand-offs, reaps, escalations — to Studio's
+    # /v1/loop-events on `alissa_endpoint`, over the same REST client and
+    # token `bows` mode reads with. Best-effort and never fatal: a failed
+    # push warns once and the pass completes, and deterministic dedupe keys
+    # make re-emission harmless. Default OFF — the push writes to an external
+    # service on every pass, so it is the operator's to opt into; disabled,
+    # no request is ever made. ALISSA_DEV_LOOP_EVENTS_ENABLED (non-blank)
+    # wins over the CLI and the file, repos_source's rail exactly.
+    loop_events_enabled: bool = False
+
     # The workspace janitor (issue #74): the filesystem sibling of the session
     # reaper. Every worker session materializes a per-task workspace under its
     # repo's hub (a `TASK-<n>-<DESC>` worktree plus whatever its lane installs
@@ -759,6 +786,28 @@ class Config:
                 + (f" (from {ENV_REPOS_SOURCE})" if env_source else "")
             )
 
+        # The loop-telemetry rail, repos_source's shape exactly: a NON-BLANK
+        # ALISSA_DEV_LOOP_EVENTS_ENABLED wins over the CLI and the file, and
+        # blank falls through. Validated by NAME like the enums — a typo read
+        # as false would silently disable a push the operator asked for.
+        loop_events = bool(
+            raw.get("loop_events_enabled", cls.loop_events_enabled)
+        )
+        env_loop_events = (os.environ if environ is None else environ).get(
+            ENV_LOOP_EVENTS, ""
+        ).strip()
+        if env_loop_events:
+            lowered = env_loop_events.casefold()
+            if lowered in _ENV_BOOL_TRUE:
+                loop_events = True
+            elif lowered in _ENV_BOOL_FALSE:
+                loop_events = False
+            else:
+                raise ValueError(
+                    f"{ENV_LOOP_EVENTS} must be one of 1/true/0/false "
+                    f"(case-insensitive), got {env_loop_events!r}"
+                )
+
         bow_owners = normalize_bow_owners(raw.get("bow_owners", cls.bow_owners))
 
         refresh_polls = int(
@@ -961,6 +1010,7 @@ class Config:
             activity_claims_enabled=bool(
                 raw.get("activity_claims_enabled", cls.activity_claims_enabled)
             ),
+            loop_events_enabled=loop_events,
             janitor_enabled=bool(raw.get("janitor_enabled", cls.janitor_enabled)),
             janitor_grace_minutes=janitor_grace,
             janitor_interval_minutes=janitor_interval,

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.14}/src/main/alissa/tools/github/devloop/loop.py

@@ -405,7 +405,9 @@ from pathlib import Path
 from typing import Callable
 
 from . import janitor
+from . import loop_events as loop_events_mod
 from .alissa import Alissa
+from .alissa_client import AlissaClient
 from .bows import BowRepoSource
 from .config import (
     FOREIGN_IGNORE,
@@ -1916,6 +1918,18 @@ class Decision:
     session: str | None = None
     task_ref: str | None = None
     round: int | None = None
+    # True on a SPAWNED decision whose directive was a RESUME (issue or fix
+    # edge). Observational like the three above -- the loop-events emitter
+    # reads it to stamp `data.resume` on the spawn's telemetry event; nothing
+    # in the decision logic does.
+    resume: bool = False
+    # The coarse defer-reason token (loop_events.DEFER_*) on a decision that
+    # is a genuine DEFERRAL -- the external-claim hold and the stale-but-
+    # possibly-alive holds that ride Action.IN_FLIGHT. None on ordinary
+    # progress (a fresh attempt in flight is the loop working, not a defer)
+    # and on the capacity valve, whose Action.DEFERRED already says it.
+    # Observational like `resume`: only the loop-events emitter reads it.
+    defer_token: str | None = None
 
 
 def _oldest_first(found: list) -> list:
@@ -2410,6 +2424,7 @@ class DevWatcher:
         state: State | None = None,
         envelope_verdict: "Callable[[str, str, int], str | None] | None" = None,
         repo_source: "BowRepoSource | None" = None,
+        loop_events: "loop_events_mod.LoopEventEmitter | None" = None,
     ):
         self.config = config
         self.github = github or GitHub(config.developer_login)
@@ -2428,6 +2443,18 @@ class DevWatcher:
         self.repo_source = repo_source or (
             BowRepoSource(config) if config.repos_source == REPOS_BOWS else None
         )
+        # The loop-telemetry push (issue #101), or None when
+        # loop_events_enabled is off -- in which case no client is built and
+        # no request is ever made. Rides the same REST endpoint and token the
+        # bows feed reads (`alissa_endpoint`), and is injectable so a test
+        # never opens a socket.
+        self.loop_events = loop_events or (
+            loop_events_mod.LoopEventEmitter(
+                self.state, AlissaClient(base=config.alissa_endpoint)
+            )
+            if config.loop_events_enabled
+            else None
+        )
         # The reaper's name-slug -> (owner, repo) index (see `_anchor_repo`),
         # rebuilt only when the allowlist itself changes rather than per
         # session per sweep.
@@ -2615,6 +2642,7 @@ class DevWatcher:
                         f"not respawning",
                         attempts,
                         session=session_name(issue, attempts),
+                        defer_token=loop_events_mod.DEFER_IN_FLIGHT,
                     )
             else:
                 # No linked open PR: the IMPLEMENT phase, before the session
@@ -2681,6 +2709,7 @@ class DevWatcher:
                         f"still be running",
                         attempts,
                         session=live_session,
+                        defer_token=loop_events_mod.DEFER_IN_FLIGHT,
                     )
 
         # Never spawn attempt cap+1. Escalate ONCE; `escalated()` dedupes, and
@@ -2804,6 +2833,7 @@ class DevWatcher:
                 f"PR {resume_pr.url}",
                 attempt - 1,
                 session=dead_session,
+                defer_token=loop_events_mod.DEFER_IN_FLIGHT,
             )
 
         hub, problem = self._ensure_hub(issue.owner, issue.repo)
@@ -2948,6 +2978,7 @@ class DevWatcher:
             attempt,
             session=name,
             task_ref=task_ref,
+            resume=resume_pr is not None,
         )
 
     def _resumable_pr(
@@ -3552,6 +3583,7 @@ class DevWatcher:
                         attempts,
                         session=fix_session_name(pr, round_, attempts),
                         round=round_,
+                        defer_token=loop_events_mod.DEFER_IN_FLIGHT,
                     )
 
         # The per-round budget ran dry: stop and page the operator ON the
@@ -5024,6 +5056,7 @@ class DevWatcher:
                 attempt - 1,
                 session=dead_session,
                 round=round_,
+                defer_token=loop_events_mod.DEFER_IN_FLIGHT,
             )
 
         hub, problem = self._ensure_hub(pr.owner, pr.repo)
@@ -5110,6 +5143,7 @@ class DevWatcher:
             attempt,
             session=name,
             round=round_,
+            resume=dead_session is not None,
         )
 
     # -- the maintenance edge (operator-labeled PRs) ------------------------
@@ -5533,6 +5567,7 @@ class DevWatcher:
             attempts,
             session=claim.session,
             round=round_,
+            defer_token=loop_events_mod.DEFER_CLAIM,
         )
 
     def _log_deferral(
@@ -7292,8 +7327,111 @@ class DevWatcher:
             counts,
             duration_ms=int((time.monotonic() - started) * 1000),
         )
+        self._emit_loop_events(
+            issue_results, pr_results, maintain_results, sweep
+        )
         return results
 
+    def _emit_loop_events(
+        self,
+        issue_results: "list[tuple[str, Decision]]",
+        pr_results: "list[tuple[str, Decision]]",
+        maintain_results: "list[tuple[str, Decision]]",
+        sweep: Sweep,
+    ) -> None:
+        """The pass's loop-telemetry push (issue #101): hand the emitter the
+        pass observations the ledgers do not carry -- which spawns were
+        RESUMEs, which candidates deferred and why, which sessions the reaper
+        killed -- then let it derive the ledger events and POST one batch.
+        A no-op when the feature is off, and under dry_run: the push writes
+        to an external service, and a dry pass takes no side effects (the
+        ledgers it would derive from are not written under dry_run either,
+        so a dry pass's batch would misreport the pass as empty anyway).
+        Best-effort end to end -- emit_pass never raises."""
+        if self.loop_events is None or self.config.dry_run:
+            return
+        deferrals: "list[dict]" = []
+        for edge, results in (
+            ("issue", issue_results),
+            ("fix", pr_results),
+            ("maintain", maintain_results),
+        ):
+            for slug, decision in results:
+                repo, _, tail = slug.partition("#")
+                number = int(tail[2:] if tail.startswith("pr") else tail)
+                token = self._defer_token(decision)
+                if token is not None:
+                    deferrals.append({
+                        "repo": repo,
+                        "edge": edge,
+                        "number": number,
+                        "token": token,
+                        "reason": decision.reason,
+                    })
+                if decision.action is Action.SPAWNED and decision.resume:
+                    if edge == "issue":
+                        key = loop_events_mod.issue_spawn_key(
+                            repo, number, decision.attempt or 0
+                        )
+                    else:
+                        key = loop_events_mod.fix_spawn_key(
+                            repo, number, decision.round or 0,
+                            decision.attempt or 0,
+                        )
+                    self.loop_events.note_resume(key)
+        self.loop_events.emit_pass(
+            deferrals=deferrals,
+            reaps=self._reap_records(sweep.names),
+            now_ms=int(time.time() * 1000),
+        )
+
+    @staticmethod
+    def _defer_token(decision: Decision) -> "str | None":
+        """The coarse defer-reason token of one decision, or None when the
+        decision is not a deferral. DEFERRED is the capacity valve by
+        construction; the deferral flavours of IN_FLIGHT (the external-claim
+        hold, the stale-but-possibly-alive holds) carry their token on the
+        decision itself (`Decision.defer_token`, stamped where each deferral
+        is decided) -- a FRESH in-flight attempt carries none, because normal
+        progress is not a defer. Everything else -- spawns, skips, caps,
+        escalations -- emits nothing here."""
+        if decision.action is Action.DEFERRED:
+            return loop_events_mod.DEFER_CAPACITY
+        return decision.defer_token
+
+    def _reap_records(self, names: "set[str]") -> "list[dict]":
+        """The sweep's kills as the emitter's reap records: session name, the
+        anchor evidence the kill line carried, and -- when the name resolves
+        on this ledger -- the repo and number. A name outside devloop's own
+        grammar is a foreign kill: no anchor exists, so the record says so
+        and carries neither repo nor number (both optional on the ingest
+        contract). Sorted for a deterministic batch order."""
+        records: "list[dict]" = []
+        for name in sorted(names):
+            worker = parse_worker_session(name)
+            if worker is None:
+                records.append({"session": name, "anchor": "foreign session"})
+                continue
+            record: "dict" = {
+                "session": name,
+                "edge": "issue" if worker.is_issue else "pr",
+                "number": worker.number,
+                "anchor": worker.anchor,
+            }
+            if worker.is_issue:
+                row = self.state.spawn_for_session(name)
+            elif worker.edge == EDGE_FIX:
+                row = self.state.fix_spawn_for_session(name)
+            else:
+                row = self.state.maintain_spawn_for_session(name)
+            if row is not None:
+                # The ledger's slug, not the name's: the name slug is lossy
+                # (`a/b-c` and `a-b/c` both squash to `a-b-c`), so only a
+                # ledger row can say which repo the kill belonged to.
+                record["repo"] = row["repo_slug"]
+            records.append(record)
+        return records
+
     def _stage_record(
         self, edge: str, slug: str, decision: Decision
     ) -> "dict":

alissa_tools_github_devloop-0.8.14/src/main/alissa/tools/github/devloop/loop_events.py

@@ -0,0 +1,532 @@
+"""Loop-event telemetry — the Studio push (issue #101).
+
+Devloop's history lives in the local `.devloop/state.db` ledgers, on a volume
+that follows the active deployment; the Factory console needs a DURABLE record
+of what the developer seat did — attempts per issue, fix rounds per PR,
+cap-outs, stalls, hand-offs. Studio ingests loop telemetry over
+``POST /v1/loop-events`` (fahera-mx/studio.alissa.app, `API.md` → "Loop
+telemetry — ingest"), idempotent on the caller's `dedupeKey`. This module is
+the writer: it derives events FROM THE LEDGER ROWS the daemon already keeps,
+so every event's identity is the ledger primary key and its clock is the
+ledger timestamp — the same rows, re-read, always derive the same events.
+
+Design rules, all downstream of that idempotency:
+
+* **Deterministic keys, no retry queue.** Every event's `dedupeKey` is
+  derived from its ledger primary key (or, for the pass-observed events, from
+  the observation's own identity), so re-emission is harmless: the server
+  answers a repeated key with a silent duplicate. A failed POST therefore
+  needs no queue — the same events re-derive next pass and are re-sent.
+* **One batch per poll pass, ≤ MAX_BATCH per call, ≤ MAX_BATCHES_PER_PASS
+  calls per pass.** The emitter tracks what it already sent (in memory only —
+  a restart re-emits everything once, and the server-side dedupe absorbs it)
+  and posts only the new events, split into calls of at most MAX_BATCH; a
+  pass POSTs at most MAX_BATCHES_PER_PASS of them and loudly leaves the rest
+  to the next pass, so a restart backfill has a bounded wall-clock cost.
+* **Best-effort, never fatal.** A failure logs ONE warning naming the count
+  and status and the pass completes. The daemon's job is spawning sessions;
+  telemetry must never cost a poll pass.
+
+Event vocabulary (the `kind` field; Studio validates the SHAPE
+``^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$``, not membership):
+
+* ``spawn.issue`` / ``spawn.fix`` / ``spawn.maintain`` — one per row of the
+  `spawns` / `fix_spawns` / `maintain_spawns` ledgers. A spawn issued with a
+  RESUME directive carries ``data.resume: true`` on its spawn event rather
+  than a separate ``resume`` kind (the issue offers either; the data flag
+  keeps one event per ledger row, so the key derivation stays a pure function
+  of the row). The flag is pass-observed and in-memory: after a daemon
+  restart the re-emitted spawn event omits it, and the server keeps the
+  original (first write wins on a repeated key).
+* ``defer`` — a candidate deferred this pass, keyed per coarse REASON token
+  (`capacity`, `activity-claim`, `in-flight`) so a continuing defer is one
+  event per reason, not one per pass.
+* ``handoff.ready`` — the orphan sweep readied a draft (`orphan-ready@…`,
+  ``data.action: "ready"``), completed a draft's handoff (`orphan@…`,
+  ``data.action: "requested"``), or the wedge self-heal re-requested review
+  (`rerequest:r<k>@…`, ``data.action: "rerequest"``) — all from the
+  `escalations` table, where those acts record their once-per-key rows.
+* ``cap.issue`` / ``cap.fix`` / ``cap.maintain`` — the cap-out escalations
+  (`cap`, `fix-cap:r<k>`, `maintain-cap[...]`). The ledger stores no page
+  text, so `reason` is derived from the kind, not quoted from the comment.
+* ``stalled`` — the three stall pings (`stalled:a<j>`, `fix-stalled:r<k>a<j>`,
+  `live-stalled:a<j>`), with the ledger family under ``data.kind``.
+* ``reap`` — a session the reaper killed this pass (`session`,
+  ``data.anchor``). Pass-observed: the reaper writes no ledger row, so the
+  event is keyed on the session name — deterministic because worker names
+  are deterministic per (repo, number, attempt) and a session dies once.
+* ``escalation.<kind>`` — every other escalation row, under its coarse kind
+  token with ``-`` mapped to ``_`` (`escalation.rerequest_rejected`,
+  `escalation.stacked_base`, `escalation.foreign_session`, …): Studio's kind
+  shape allows no hyphens, so the raw ledger kind rides in ``data.ledgerKind``
+  and `reason` instead.
+
+No ``poll`` vitals events: live vitals stay a console pull (`/api/state`).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable, Mapping, Sequence
+
+from .alissa_client import AlissaClient, AlissaError
+
+log = logging.getLogger(__name__)
+
+SEAT = "devloop"
+
+# The ingest contract's batch cap: 1–200 events per call. Larger passes split.
+MAX_BATCH = 200
+
+# How many calls one PASS may make (PR #102 review round 1, `[major]`). The
+# push runs in-band in `poll_once` and the loop is single-threaded, so an
+# unbounded sequence of sequential POSTs — the first pass after a restart
+# re-derives the volume's whole history — would delay the reaper sweep and
+# all three spawning edges by O(history / 200) network round-trips. Five
+# calls bounds a pass at a known wall-clock (≤ 5 × the client timeout, worst
+# case) while a restart backfill of thousands of events still drains in a
+# handful of passes: nothing marked emitted is lost, the tail simply
+# re-derives next pass, and the capped pass SAYS how much it left (no silent
+# caps). The fuller answer — a persisted derivation watermark so a pass never
+# scans rows it already shipped — is registered as a follow-up task.
+MAX_BATCHES_PER_PASS = 5
+
+# The ingest contract's `reason` cap. Over it is a 400 that fails the WHOLE
+# batch ("never a trim", server-side) — so the trim happens here.
+MAX_REASON = 2000
+
+# The kind grammar Studio validates (shape, not membership). Everything this
+# module emits must match it — one hyphen in a kind 400s a whole batch — so
+# derivation normalises through _kind_token and this regex backstops it.
+KIND_SHAPE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$")
+
+# The coarse defer-reason tokens (folded into the defer key so a continuing
+# defer is one event per reason, not one per pass).
+DEFER_CAPACITY = "capacity"  # max_sessions backpressure (Action.DEFERRED)
+DEFER_CLAIM = "activity-claim"  # another instance's fresh spawn line
+DEFER_IN_FLIGHT = "in-flight"  # own work already on the lane
+
+# The escalation-ledger kind grammars this module knows how to enrich. An
+# unmatched kind still emits — as a generic `escalation.<token>` — so a kind
+# added to the loop later reaches Studio without touching this table.
+_STALLED_RE = re.compile(r"^stalled:a(\d+)$")
+_LIVE_STALLED_RE = re.compile(r"^live-stalled:a(\d+)$")
+_FIX_STALLED_RE = re.compile(r"^fix-stalled:r(\d+)a(\d+)$")
+_FIX_CAP_RE = re.compile(r"^fix-cap:r(\d+)$")
+_MAINTAIN_CAP_RE = re.compile(r"^maintain-cap(:e\d+)?$")
+_REREQUEST_RE = re.compile(r"^rerequest:r(\d+)@(.+)$")
+_ORPHAN_READY_RE = re.compile(r"^orphan-ready@(.+)$")
+_ORPHAN_DONE_RE = re.compile(r"^orphan@(.+)$")
+_FOREIGN_RE = re.compile(r"^foreign-session:(.+)$")
+
+# Escalation kinds anchored on a repo ISSUE; everything else that names a
+# number names a PULL REQUEST (the fix/maintain/orphan/rerequest families all
+# key the PR number into the ledger's `issue` column).
+_ISSUE_ANCHORED = ("cap", "assignment", "stalled", "live-stalled")
+
+
+def _ms(ts: "int | float | str") -> int:
+    """A ledger timestamp (unix seconds) as the contract's epoch ms."""
+    return int(ts) * 1000
+
+
+def _kind_token(raw_kind: str) -> str:
+    """The coarse kind token of one escalation row, shaped for the contract.
+
+    The coarse token is the ledger kind up to its first `:` or `@` (the
+    folded-in episode key — round, attempt, head, session — is identity, not
+    vocabulary). Hyphens map to underscores because the contract's kind shape
+    allows none; anything else non-conforming is dropped, and a token that
+    still fails the shape falls back to `unknown` rather than 400ing a batch.
+    """
+    coarse = re.split(r"[:@]", raw_kind, maxsplit=1)[0]
+    token = re.sub(r"[^a-z0-9_]", "", coarse.lower().replace("-", "_"))
+    if not token or not token[0].isalpha():
+        return "unknown"
+    return token
+
+
+def _event(
+    kind: str,
+    at_ms: int,
+    dedupe_key: str,
+    *,
+    repo: "str | None" = None,
+    issue_number: "int | None" = None,
+    pr_number: "int | None" = None,
+    round_: "int | None" = None,
+    attempt: "int | None" = None,
+    session: "str | None" = None,
+    reason: "str | None" = None,
+    data: "Mapping[str, object] | None" = None,
+) -> "dict[str, object]":
+    """One ingest-shaped event, optional fields omitted rather than nulled.
+
+    The kind is checked against the contract's shape here — one bad kind
+    fails a WHOLE batch server-side, so a derivation bug must die at build
+    time, not silently cost every event it was batched with. A raise, not an
+    `assert`: `python -O` strips asserts, and a guard that exists to protect
+    a whole batch must not depend on nobody ever setting PYTHONOPTIMIZE
+    (PR #102 review round 1). The emitter's derivation guard catches it, so
+    even then the cost is one warned pass, never a crashed one.
+    """
+    if not KIND_SHAPE.match(kind):
+        raise ValueError(f"kind {kind!r} violates the ingest shape")
+    event: "dict[str, object]" = {
+        "seat": SEAT,
+        "kind": kind,
+        "at": at_ms,
+        "dedupeKey": dedupe_key,
+    }
+    if repo:
+        event["repo"] = repo
+    if issue_number is not None:
+        event["issueNumber"] = int(issue_number)
+    if pr_number is not None:
+        event["prNumber"] = int(pr_number)
+    if round_ is not None:
+        event["round"] = int(round_)
+    if attempt is not None:
+        event["attempt"] = int(attempt)
+    if session:
+        event["session"] = session
+    if reason:
+        event["reason"] = reason[:MAX_REASON]
+    if data:
+        event["data"] = dict(data)
+    return event
+
+
+# -- deterministic keys (the documented derivations) -------------------------
+
+
+def issue_spawn_key(repo: str, issue: int, attempt: int) -> str:
+    return f"{SEAT}:spawn.issue:{repo}:{issue}:{attempt}"
+
+
+def fix_spawn_key(repo: str, pr: int, round_: int, attempt: int) -> str:
+    return f"{SEAT}:spawn.fix:{repo}:{pr}:{round_}:{attempt}"
+
+
+def maintain_spawn_key(repo: str, pr: int, attempt: int) -> str:
+    return f"{SEAT}:spawn.maintain:{repo}:{pr}:{attempt}"
+
+
+def defer_key(repo: str, edge: str, number: int, reason_token: str) -> str:
+    return f"{SEAT}:defer:{repo}:{edge}:{number}:{reason_token}"
+
+
+def reap_key(session: str) -> str:
+    return f"{SEAT}:reap:{session}"
+
+
+def escalation_key(event_kind: str, repo_slug: str, number: int,
+                   raw_kind: str) -> str:
+    """Escalation-derived events key on the ledger PRIMARY KEY verbatim
+    (repo_slug, number, kind) under the event kind — one row, one key,
+    whatever the kind family. The raw ledger kind stays in the key even when
+    the event kind already names its family, because the kind column IS part
+    of the row's identity (`fix-cap:r1` and `fix-cap:r2` are two rows)."""
+    return f"{SEAT}:{event_kind}:{repo_slug}:{number}:{raw_kind}"
+
+
+# -- derivation: ledger rows → events ---------------------------------------
+
+
+def spawn_events(
+    spawn_rows: "Iterable[Mapping]",
+    fix_rows: "Iterable[Mapping]",
+    maintain_rows: "Iterable[Mapping]",
+    resume_keys: "frozenset[str] | set[str]" = frozenset(),
+) -> "list[dict]":
+    """The three spawn ledgers as events. `resume_keys` holds the dedupe keys
+    of spawns issued with a RESUME directive (pass-observed by the loop);
+    their events carry ``data.resume: true``."""
+    events = []
+    for row in spawn_rows:
+        key = issue_spawn_key(row["repo_slug"], row["issue"], row["attempt"])
+        events.append(_event(
+            "spawn.issue",
+            _ms(row["spawned_at"]),
+            key,
+            repo=row["repo_slug"],
+            issue_number=row["issue"],
+            attempt=row["attempt"],
+            session=row["session"],
+            data={"resume": True} if key in resume_keys else None,
+        ))
+    for row in fix_rows:
+        key = fix_spawn_key(
+            row["repo_slug"], row["number"], row["round"], row["attempt"]
+        )
+        events.append(_event(
+            "spawn.fix",
+            _ms(row["spawned_at"]),
+            key,
+            repo=row["repo_slug"],
+            pr_number=row["number"],
+            round_=row["round"],
+            attempt=row["attempt"],
+            session=row["session"],
+            data={"resume": True} if key in resume_keys else None,
+        ))
+    for row in maintain_rows:
+        key = maintain_spawn_key(row["repo_slug"], row["number"], row["attempt"])
+        events.append(_event(
+            "spawn.maintain",
+            _ms(row["spawned_at"]),
+            key,
+            repo=row["repo_slug"],
+            pr_number=row["number"],
+            attempt=row["attempt"],
+            session=row["session"],
+        ))
+    return events
+
+
+def escalation_event(row: "Mapping") -> "dict":
+    """One escalation row as its event — cap-out, stall, handoff act, or the
+    generic `escalation.<kind>`. Total: every row derives SOMETHING, so a new
+    ledger kind reaches Studio without a derivation change."""
+    raw = str(row["kind"])
+    repo = str(row["repo_slug"])
+    number = int(row["issue"])
+    at = _ms(row["escalated_at"])
+
+    def build(kind, **fields):
+        return _event(kind, at, escalation_key(kind, repo, number, raw),
+                      repo=repo, **fields)
+
+    if raw == "cap":
+        return build("cap.issue", issue_number=number,
+                     reason="developer attempt cap reached")
+    match = _FIX_CAP_RE.match(raw)
+    if match:
+        round_ = int(match.group(1))
+        return build("cap.fix", pr_number=number, round_=round_,
+                     reason=f"fix attempts for round {round_} capped")
+    if _MAINTAIN_CAP_RE.match(raw):
+        return build("cap.maintain", pr_number=number,
+                     reason="maintenance attempts capped")
+
+    match = _STALLED_RE.match(raw)
+    if match:
+        return build("stalled", issue_number=number,
+                     attempt=int(match.group(1)), data={"kind": "stalled"})
+    match = _LIVE_STALLED_RE.match(raw)
+    if match:
+        return build("stalled", issue_number=number,
+                     attempt=int(match.group(1)),
+                     data={"kind": "live-stalled"})
+    match = _FIX_STALLED_RE.match(raw)
+    if match:
+        return build("stalled", pr_number=number,
+                     round_=int(match.group(1)), attempt=int(match.group(2)),
+                     data={"kind": "fix-stalled"})
+
+    match = _ORPHAN_READY_RE.match(raw)
+    if match:
+        return build("handoff.ready", pr_number=number,
+                     data={"action": "ready", "headSha": match.group(1)})
+    match = _ORPHAN_DONE_RE.match(raw)
+    if match:
+        return build("handoff.ready", pr_number=number,
+                     data={"action": "requested", "headSha": match.group(1)})
+    match = _REREQUEST_RE.match(raw)
+    if match:
+        return build("handoff.ready", pr_number=number,
+                     round_=int(match.group(1)),
+                     data={"action": "rerequest", "headSha": match.group(2)})
+
+    # Everything else: the generic family. The foreign-session page has
+    # DEGENERATE ledger coordinates by design (repo "-", number 0 — a tmux
+    # session has no GitHub artifact), so those two fields stay off the event
+    # (both are optional on the contract) and the session name rides where it
+    # belongs. The key still uses the placeholders verbatim: it derives from
+    # the row's primary key, whatever that key holds.
+    kind = f"escalation.{_kind_token(raw)}"
+    match = _FOREIGN_RE.match(raw)
+    if match:
+        return _event(kind, at, escalation_key(kind, repo, number, raw),
+                      session=match.group(1), reason=raw,
+                      data={"ledgerKind": raw})
+    fields: "dict[str, object]" = {"reason": raw, "data": {"ledgerKind": raw}}
+    if raw.split(":", 1)[0] in _ISSUE_ANCHORED:
+        fields["issue_number"] = number
+    else:
+        # Every other known family keys a PR number into the `issue` column;
+        # an unknown future kind is assumed to as well (new edges here have
+        # all been PR-side since the issue edge shipped).
+        fields["pr_number"] = number
+    return build(kind, **fields)
+
+
+def escalation_events(rows: "Iterable[Mapping]") -> "list[dict]":
+    return [escalation_event(row) for row in rows]
+
+
+def defer_events(
+    deferrals: "Sequence[Mapping]", at_ms: int
+) -> "list[dict]":
+    """Pass-observed deferrals as events. Each entry carries `repo`, `edge`
+    (`issue`/`fix`/`maintain`), `number`, `token` (the coarse reason), and
+    `reason` (the decision's verbatim sentence). Keyed per (repo, edge,
+    number, token): a defer that continues across passes — or recurs for the
+    same reason — is one event, which is the point of the coarse token."""
+    events = []
+    for item in deferrals:
+        edge = str(item["edge"])
+        number = int(item["number"])
+        events.append(_event(
+            "defer",
+            at_ms,
+            defer_key(str(item["repo"]), edge, number, str(item["token"])),
+            repo=str(item["repo"]),
+            issue_number=number if edge == "issue" else None,
+            pr_number=number if edge != "issue" else None,
+            reason=str(item.get("reason") or "") or None,
+            data={"edge": edge, "reasonToken": str(item["token"])},
+        ))
+    return events
+
+
+def reap_events(reaps: "Sequence[Mapping]", at_ms: int) -> "list[dict]":
+    """Pass-observed reaper kills as events. Each entry carries `session`,
+    `anchor` (the kill's stated evidence), and — when the session resolved to
+    a ledger row — `repo`, `edge` and `number`. Keyed on the session name
+    alone: worker names are deterministic per (repo, number, attempt) and a
+    session dies once, so the name IS the kill's identity."""
+    events = []
+    for item in reaps:
+        edge = str(item.get("edge") or "")
+        number = item.get("number")
+        events.append(_event(
+            "reap",
+            at_ms,
+            reap_key(str(item["session"])),
+            repo=str(item.get("repo") or "") or None,
+            issue_number=int(number) if number is not None and edge == "issue"
+            else None,
+            pr_number=int(number) if number is not None and edge != "issue"
+            else None,
+            session=str(item["session"]),
+            data={"anchor": str(item.get("anchor") or "unknown")},
+        ))
+    return events
+
+
+# -- the emitter -------------------------------------------------------------
+
+
+class LoopEventEmitter:
+    """One idempotent batch per poll pass, best-effort.
+
+    Holds three pieces of in-memory state, all safe to lose (a restart
+    re-emits, the server dedupes):
+
+    * `_emitted` — dedupe keys already accepted by the server this process,
+      so a pass sends only what is new;
+    * `_observed` — pass-observed events (defers, reaps) not yet accepted:
+      unlike the ledger-derived events these cannot be re-derived next pass,
+      so they are carried until a POST lands;
+    * `_resume_keys` — spawn keys the loop flagged as RESUME spawns, kept for
+      the life of the process so a failed POST re-derives the spawn event
+      with its flag intact.
+    """
+
+    def __init__(self, state, client: "AlissaClient"):
+        self.state = state
+        self.client = client
+        self._emitted: "set[str]" = set()
+        self._observed: "dict[str, dict]" = {}
+        self._resume_keys: "set[str]" = set()
+
+    def note_resume(self, dedupe_key: str) -> None:
+        """Flag one spawn key as a RESUME spawn (see the module docstring for
+        why the flag is a data field on the spawn event, not its own kind)."""
+        self._resume_keys.add(dedupe_key)
+
+    def emit_pass(
+        self,
+        *,
+        deferrals: "Sequence[Mapping]" = (),
+        reaps: "Sequence[Mapping]" = (),
+        now_ms: int,
+    ) -> int:
+        """Derive this pass's events and POST what the server has not yet
+        accepted, in batches of at most MAX_BATCH and at most
+        MAX_BATCHES_PER_PASS calls per pass (the tail re-derives next pass).
+        Returns how many events were accepted this pass. NEVER raises: any
+        failure — a wedged ledger read, a transport error, an ingest 400 —
+        logs one warning naming the count (and status, when there is one)
+        and the pass completes."""
+        try:
+            for event in (defer_events(deferrals, now_ms)
+                          + reap_events(reaps, now_ms)):
+                self._observed.setdefault(str(event["dedupeKey"]), event)
+            events = (
+                spawn_events(
+                    self.state.read_spawns(),
+                    self.state.read_fix_spawns(),
+                    self.state.read_maintain_spawns(),
+                    self._resume_keys,
+                )
+                + escalation_events(self.state.read_escalations())
+                + list(self._observed.values())
+            )
+        except Exception as exc:
+            # Derivation reads the ledger, and the ledger can be wedged (the
+            # strict readers raise sqlite3.Error). Telemetry must not be the
+            # thing that abandons a pass over it.
+            log.warning(
+                "loop events: derivation failed (%s) — no events pushed this "
+                "pass; the ledgers re-derive next pass", exc,
+            )
+            return 0
+
+        fresh = [e for e in events if e["dedupeKey"] not in self._emitted]
+        if not fresh:
+            return 0
+
+        # The per-pass bound (see MAX_BATCHES_PER_PASS): the push is in-band,
+        # so a pass POSTs at most this many batches and leaves the tail —
+        # loudly — to the next pass. Ordinary passes never come near it; the
+        # case it bounds is the restart backfill.
+        cap = MAX_BATCH * MAX_BATCHES_PER_PASS
+        held_over = max(0, len(fresh) - cap)
+
+        sent = 0
+        for start in range(0, min(len(fresh), cap), MAX_BATCH):
+            batch = fresh[start:start + MAX_BATCH]
+            try:
+                self.client.post_loop_events(batch)
+            except AlissaError as exc:
+                log.warning(
+                    "loop events: POST /v1/loop-events of %d event(s) failed "
+                    "(status %s: %s) — %d of %d sent this pass; the rest "
+                    "re-emit next pass (deterministic keys make re-emission "
+                    "harmless)",
+                    len(batch), exc.status, exc.detail, sent, len(fresh),
+                )
+                return sent
+            for event in batch:
+                key = str(event["dedupeKey"])
+                self._emitted.add(key)
+                self._observed.pop(key, None)
+            sent += len(batch)
+        if held_over:
+            log.info(
+                "loop events: per-pass bound reached — pushed %d of %d new "
+                "event(s), the remaining %d re-derive next pass",
+                sent, len(fresh), held_over,
+            )
+        else:
+            # INFO, not DEBUG (PR #102 review round 1): an operator who turns
+            # the push on and watches unattended logs needs the success path
+            # visible without -v, or "enabled and working" reads exactly like
+            # "enabled and never firing". Quiet passes stay quiet -- the
+            # early return above means this line only prints when something
+            # actually shipped.
+            log.info("loop events: pushed %d new event(s)", sent)
+        return sent

alissa_tools_github_devloop-0.8.14/src/main/alissa/tools/github/devloop/version

@@ -0,0 +1 @@
+0.8.14

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.14/src/main/alissa_tools_github_devloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.13
+Version: 0.8.14
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.13 → alissa_tools_github_devloop-0.8.14}/src/main/alissa_tools_github_devloop.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/main/alissa/tools/github/devloop/config.py
 src/main/alissa/tools/github/devloop/ghclient.py
 src/main/alissa/tools/github/devloop/janitor.py
 src/main/alissa/tools/github/devloop/loop.py
+src/main/alissa/tools/github/devloop/loop_events.py
 src/main/alissa/tools/github/devloop/proc.py
 src/main/alissa/tools/github/devloop/state.py
 src/main/alissa/tools/github/devloop/version

alissa_tools_github_devloop-0.8.13/src/main/alissa/tools/github/devloop/version

@@ -1 +0,0 @@
-0.8.13