alissa-tools-github-orcloop 0.2.0__tar.gz → 0.3.0__tar.gz

{alissa_tools_github_orcloop-0.2.0/src/main/alissa_tools_github_orcloop.egg-info → alissa_tools_github_orcloop-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.2.0
+Version: 0.3.0
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_orcloop-0.2.0 → alissa_tools_github_orcloop-0.3.0}/src/main/alissa/tools/github/orcloop/__main__.py

@@ -1,7 +1,10 @@
 """CLI entry point: alissa-orcloop (or python -m alissa.tools.github.orcloop).
 
 O1 wired the config surface and the argument parser; O3 wires the decision
-loop behind it. The CLI resolves and validates the full configuration
+loop behind it; O6 adds the release-feed selector (`--release-feed bow` and its
+`--bow-prefix` / `--bow-owner` / `--scan-fallback-interval` knobs).
+
+The CLI resolves and validates the full configuration
 (four-layer precedence, fail-closed `repos` guard), reports the effective
 settings, then runs the orchestrator: `--once` for a single sweep (pair it
 with `--dry-run -v` to print every decision and its reasons without touching
@@ -18,6 +21,8 @@ from pathlib import Path
 
 from .alissa_client import AlissaError
 from .config import (
+    FEED_BOW,
+    RELEASE_FEEDS,
     Config,
     load_config_file,
     resolve_config_path,
@@ -91,6 +96,41 @@ def build_parser() -> argparse.ArgumentParser:
     over.add_argument("--scope-key", metavar="KEY", help="Autonomous-Scope trailer key")
     over.add_argument("--alissa-endpoint", metavar="URL")
     over.add_argument("--ledger-path", type=Path, metavar="PATH")
+    over.add_argument(
+        "--release-feed",
+        choices=RELEASE_FEEDS,
+        metavar="{" + ",".join(RELEASE_FEEDS) + "}",
+        help="where release candidates come from: 'scan' (the default) lists "
+        "every committed task and filters it on the release marker; 'bow' "
+        "reads the per-repo Bodies of Work named <bow-prefix><owner>/<repo>, "
+        "where attaching a task is the release trigger AND the repo declaration",
+    )
+    over.add_argument(
+        "--bow-prefix",
+        metavar="PREFIX",
+        help="title prefix that marks a Body of Work as a release feed "
+        "(default 'autodev: '); the rest of the title is the target owner/repo",
+    )
+    over.add_argument(
+        "--bow-owner",
+        dest="bow_owners",
+        action="append",
+        metavar="ACTOR_ID",
+        help="bow feed only: trust bodies of work OWNED by this Alissa actor "
+        "as release feeds; repeatable. When given, REPLACES the config "
+        "`bow_owners` list. Fail-closed like --repo: `--release-feed bow` with "
+        "an empty owner list is a fatal startup error, because being SHARED a "
+        "body of work is not a claim to drive this daemon. An actor id is the "
+        "`ownerActorId` on the container's row in GET /v1/bodies-of-work.",
+    )
+    over.add_argument(
+        "--scan-fallback-interval",
+        type=int,
+        metavar="SECONDS",
+        help="bow feed only: how often to ALSO run the full marker scan and "
+        "log every marked task the feed did not surface (default 3600; 0 "
+        "disables it). The sweep reports, it never releases.",
+    )
 
     close = over.add_mutually_exclusive_group()
     close.add_argument(
@@ -139,6 +179,10 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "ledger_path": args.ledger_path,
         "close_loop_enabled": args.close_loop_enabled,
         "dry_run": args.dry_run,
+        "release_feed": args.release_feed,
+        "bow_prefix": args.bow_prefix,
+        "bow_owners": tuple(args.bow_owners) if args.bow_owners else None,
+        "scan_fallback_interval": args.scan_fallback_interval,
     }
 
 
@@ -161,6 +205,22 @@ def log_effective_config(config: Config) -> None:
         config.poll_interval, config.repo_parallelism, config.dry_run,
         config.close_loop_enabled,
     )
+    if config.release_feed == FEED_BOW:
+        log.info(
+            "release feed: bow — candidates are the tasks attached to the "
+            "%r bodies of work OWNED by %s; scan fallback sweep %s",
+            config.bow_prefix,
+            ", ".join(config.bow_owners),
+            f"every {config.scan_fallback_interval}s"
+            if config.scan_fallback_interval
+            else "DISABLED",
+        )
+    else:
+        log.info(
+            "release feed: scan — candidates are committed tasks carrying %r, "
+            "targeted by their %s trailer",
+            config.label, config.marker_key,
+        )
     log.debug("marker_key: %s", config.marker_key)
     log.debug("scope_key: %s", config.scope_key)
     log.debug("release_blocked_floor_days: %s", config.release_blocked_floor_days)

{alissa_tools_github_orcloop-0.2.0 → alissa_tools_github_orcloop-0.3.0}/src/main/alissa/tools/github/orcloop/alissa_client.py

@@ -53,6 +53,47 @@ Three narrow, actionable buckets so the loop can react without string-matching:
 
 Anything else (a 400 validation error, say) surfaces as the base
 ``AlissaError`` -- a bug to fix, not a condition to retry blindly.
+
+THE BODY-OF-WORK SURFACE (O6)
+=============================
+The `bow` release feed reads candidates out of per-repo Bodies of Work instead
+of scanning every committed task. Three endpoints, all verified live against
+``api.alissa.app`` while implementing O6:
+
+* ``GET /v1/bodies-of-work?includeShared=true`` -> ``{"bodiesOfWork": [...]}``.
+  **One call, no server-side title/status filter** (``?status=``/``?q=`` are
+  silently ignored), so the ``bow_prefix`` match runs here. The endpoint does,
+  however, have a SCOPE parameter, and it is not optional for a daemon: the
+  default list is what the actor **owns**, and ``includeShared=true`` adds the
+  ones it merely collaborates on. Measured live: 14 owned, 19 with the flag.
+  Feed containers are operator-created (there is no create endpoint) and the
+  daemon is a collaborator, so every one of them lives in that difference --
+  omitting the flag makes the ``bow`` feed discover nothing, silently. A
+  collaborator BOW is otherwise perfectly visible: ``GET
+  /v1/bodies-of-work/<id>`` returns it and membership reads work; it is only
+  absent from the DEFAULT listing. This is the whole discovery cost: the number
+  of Bodies of Work an org has is a small constant, not a function of task
+  count. The flag also widens the listing to containers ANY actor shared with
+  the daemon, so each row carries its ``ownerActorId`` and the loop admits only
+  the owners the operator allowlisted (``bow_owners``) -- see
+  ``list_bodies_of_work``.
+* ``GET /v1/bodies-of-work/<id>`` -> ``{"bodyOfWork": {..., "tasks": [{"_id",
+  "status", "title"}]}}``. The membership list is EMBEDDED in the BOW detail;
+  there is no ``/bodies-of-work/<id>/tasks`` route, and ``GET /v1/tasks`` has no
+  ``bodyOfWorkId`` filter (an unknown query param is silently ignored, which
+  would have read as "every task is a member"). Member rows carry no
+  ``taskNumber``, so the loop resolves each committed member through
+  ``get_task`` -- which accepts the opaque ``_id`` as a ref.
+* ``DELETE /v1/bodies-of-work/<id>/tasks/<ref>`` -> ``{"removed": bool}``. The
+  detach that terminates a successful release. **Idempotent**: detaching a task
+  that is not attached returns ``removed: false`` rather than an error, so a
+  crash-resumed detach is safe. The ``<ref>`` accepts both ``TASK-<n>`` and the
+  opaque id. A task id that does not exist at all is a 404 (``TASK_NOT_FOUND``).
+
+Both BOW endpoints require the daemon actor to be a **collaborator** on the
+Body of Work (otherwise 403 ``FORBIDDEN`` on attach/detach) -- an operator setup
+step, documented in the README. orcloop never attaches: attaching is the
+operator's trigger, detaching is orcloop's terminal release act.
 """
 
 from __future__ import annotations
@@ -116,6 +157,38 @@ class MarkedTask:
     description: str
 
 
+@dataclass(frozen=True)
+class BodyOfWork:
+    """A Body of Work as the LIST endpoint reports it. Only the fields the feed
+    needs: the id to read membership with, the title carrying the
+    `<prefix><owner>/<repo>` naming convention, the BOW's own status, and
+    `owner_id` -- the actor that OWNS the container (`ownerActorId`).
+
+    `owner_id` is the container's provenance and the only thing here that is
+    not operator-authored text: the listing includes containers this actor was
+    merely SHARED, so the title alone cannot say whether a feed is one the
+    operator set up (see `Config.bow_owners`). Empty when the payload omits it,
+    which the caller treats as untrusted rather than unknown."""
+
+    id: str
+    title: str
+    status: str = ""
+    owner_id: str = ""
+
+
+@dataclass(frozen=True)
+class BowMember:
+    """One task attached to a Body of Work, as the BOW DETAIL endpoint reports
+    it. Deliberately thin: the membership rows carry `_id`, `status` and
+    `title` and NOTHING else -- no taskNumber, no description. `status` is
+    enough to hold an uncommitted member without a detail round-trip; a
+    committed member is resolved through `get_task(id)`."""
+
+    id: str
+    title: str
+    status: str
+
+
 @dataclass(frozen=True)
 class Criterion:
     id: str
@@ -296,6 +369,98 @@ class AlissaClient:
             )
         return out
 
+    # --- the Body-of-Work feed (O6) ----------------------------------------
+
+    def list_bodies_of_work(self) -> list[BodyOfWork]:
+        """Every Body of Work this actor owns OR collaborates on -- ONE call.
+
+        `includeShared=true` is load-bearing, not decoration: the endpoint
+        defaults to OWNED-only, and a feed container is created by the operator
+        in Studio (there is no create endpoint) with the daemon added as a
+        COLLABORATOR. Without the flag the feed's only discovery path returns
+        nothing and `release_feed: bow` is silently inert. There is still no
+        server-side title/status filter (see the module docstring), so the
+        caller narrows by prefix. Rows without an `_id` are dropped: a BOW that
+        cannot be addressed cannot be read for membership.
+
+        THE TRUST BOUNDARY THE FLAG MOVES. `includeShared=true` is necessary
+        (above) but it widens this listing to every container ANY actor in the
+        tenant has shared with the daemon -- unilaterally, with no acceptance
+        step on this side. So membership of this list is NOT a claim to be a
+        release feed: it means "visible", not "authoritative". The title-derived
+        gates downstream (`parse_bow_repo`, `Config.watches`) bound which repo a
+        release lands in, not whose task reaches it, and an allowlisted repo is
+        precisely where the daemon's writes are most trusted. Provenance is
+        therefore carried out of here as `BodyOfWork.owner_id` and checked
+        against the operator's `bow_owners` allowlist before a container is
+        treated as a feed. Collaboration makes a container READABLE (and is
+        still required, for detach); `bow_owners` makes it AUTHORITATIVE.
+        """
+        payload = self._request("GET", "/v1/bodies-of-work?includeShared=true")
+        rows = payload.get("bodiesOfWork") if isinstance(payload, dict) else None
+        if not isinstance(rows, list):
+            return []
+        out: list[BodyOfWork] = []
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            bow_id = row.get("_id")
+            if not isinstance(bow_id, str) or not bow_id:
+                continue
+            out.append(
+                BodyOfWork(
+                    id=bow_id,
+                    title=row.get("title") or "",
+                    status=row.get("status") or "",
+                    owner_id=row.get("ownerActorId") or "",
+                )
+            )
+        return out
+
+    def body_of_work_tasks(self, bow_id: str) -> list[BowMember]:
+        """The tasks attached to one Body of Work, in the BOW's own order.
+
+        Membership is embedded in the BOW detail payload; there is no separate
+        listing route. Rows without an `_id` are dropped for the same reason as
+        above -- an unaddressable member cannot be resolved or detached.
+        """
+        payload = self._request(
+            "GET", f"/v1/bodies-of-work/{urllib.parse.quote(str(bow_id), safe='')}"
+        )
+        bow = payload.get("bodyOfWork") if isinstance(payload, dict) else None
+        if not isinstance(bow, dict):
+            raise AlissaError(200, f"no bodyOfWork object in response for {bow_id!r}")
+        out: list[BowMember] = []
+        for row in bow.get("tasks") or []:
+            if not isinstance(row, dict):
+                continue
+            task_id = row.get("_id")
+            if not isinstance(task_id, str) or not task_id:
+                continue
+            out.append(
+                BowMember(
+                    id=task_id,
+                    title=row.get("title") or "",
+                    status=row.get("status") or "",
+                )
+            )
+        return out
+
+    def detach_task(self, bow_id: str, ref: str) -> bool:
+        """Detach a task from a Body of Work; True when this call removed it.
+
+        Idempotent by contract: detaching an already-detached task answers
+        `removed: false` with a 2xx, so the terminal step of a release can be
+        retried after a crash without a "was it already done?" probe. `ref`
+        accepts `TASK-<n>` or the opaque task id.
+        """
+        payload = self._request(
+            "DELETE",
+            f"/v1/bodies-of-work/{urllib.parse.quote(str(bow_id), safe='')}"
+            f"/tasks/{urllib.parse.quote(str(ref), safe='')}",
+        )
+        return bool(payload.get("removed")) if isinstance(payload, dict) else False
+
     def get_task(self, ref: str) -> Task:
         """Full detail for one task. `ref` is any reference form the API accepts
         (`TASK-<n>`, public id, url). Raises `AlissaNotFound` when the bound

{alissa_tools_github_orcloop-0.2.0 → alissa_tools_github_orcloop-0.3.0}/src/main/alissa/tools/github/orcloop/config.py

@@ -24,6 +24,27 @@ closes the loop on merge, so it never runs against an unbounded repo set.
 The marker contract (`Autonomous-Dev` / `Autonomous-Scope` issue-body
 trailers) is parsed in `markers.py`; the keys that name those trailers live
 here (`marker_key`, `scope_key`) so an operator can rename them per-deployment.
+
+RELEASE FEED (O6). `release_feed` selects where release candidates come from:
+
+* `scan` (the DEFAULT, for backward compatibility) — list every committed task
+  and filter it on the release marker. Simple, but the read is O(all committed
+  tasks) every poll, which is the DB-load concern that motivated O6.
+* `bow` — read them out of the per-repo **Bodies of Work** named
+  `<bow_prefix><owner>/<repo>` (default prefix `autodev: `). Attaching a task to
+  such a BOW is both the release trigger and the repo declaration; the read is
+  O(total BOW membership). `scan_fallback_interval` keeps a low-frequency full
+  trailer scan running underneath as a visibility safety net.
+
+The `bow` feed has a **second** fail-closed allowlist, `bow_owners`, and the two
+answer different questions. A container's title says which repo it targets, so
+`repos` bounds *where* a release lands. Nothing in a title says who created the
+container — and the daemon lists Bodies of Work it merely **collaborates** on,
+which any actor in the tenant can arrange without an acceptance step on this
+side. `bow_owners` names the actor id(s) whose containers may drive the daemon,
+so "whose work reaches an autonomous pipeline" is an operator decision rather
+than a consequence of being shared something. Empty is fatal under
+`release_feed: bow`, exactly as an empty `repos` is fatal always.
 """
 
 from __future__ import annotations
@@ -55,13 +76,23 @@ CONFIG_KEYS = (
     "dry_run",
     "ledger_path",
     "close_loop_enabled",
+    "release_feed",
+    "bow_prefix",
+    "bow_owners",
+    "scan_fallback_interval",
 )
 
+# `release_feed` values. `scan` is the O0-O5 behavior and stays the default so
+# an existing deployment upgrades without a config change; `bow` is the O6 feed.
+FEED_SCAN = "scan"
+FEED_BOW = "bow"
+RELEASE_FEEDS = (FEED_SCAN, FEED_BOW)
+
 # Keys carrying a boolean; env strings for these need real parsing (bool("false")
 # is True, which would silently invert the setting).
 _BOOL_KEYS = frozenset({"dry_run", "close_loop_enabled"})
 # Keys carrying a list of strings; an env value is comma-separated.
-_LIST_KEYS = frozenset({"repos"})
+_LIST_KEYS = frozenset({"repos", "bow_owners"})
 
 MIN_POLL_INTERVAL = 10  # the GitHub search API allows 30 req/min
 
@@ -180,6 +211,33 @@ class Config:
 
     dry_run: bool = False
 
+    # Where release candidates come from: `scan` (all committed tasks, filtered
+    # on the marker) or `bow` (the per-repo Bodies of Work). Default `scan` —
+    # an existing deployment must not change behavior on upgrade.
+    release_feed: str = FEED_SCAN
+
+    # The naming convention that makes a Body of Work a release feed: its title
+    # is `<bow_prefix><owner>/<repo>`. The trailing space is part of the default
+    # (`autodev: fahera-mx/widgets`); prefix matching is case-insensitive.
+    bow_prefix: str = "autodev: "
+
+    # WHOSE Bodies of Work may act as a release feed: the Alissa actor id(s)
+    # allowed to OWN a feed container. Fail-closed like `repos` — empty is
+    # REJECTED at build when `release_feed` is `bow` (see build's guard). The
+    # title tells the daemon which repo a container targets; it says nothing
+    # about who created it, and the daemon lists containers it merely
+    # collaborates on, which anyone in the tenant can arrange unilaterally.
+    # So provenance is an operator decision, made here. Ids are opaque and
+    # compared EXACTLY (unlike `repos`, which casefolds GitHub names).
+    bow_owners: tuple[str, ...] = ()
+
+    # The `bow`-feed safety net: every this-many seconds, ALSO run the full
+    # marker scan and LOG every marked committed task the BOW feed did not
+    # surface, so a feed bug can never make work invisible. Purely level-based
+    # visibility — the sweep never releases (attachment is the only trigger).
+    # 0 disables it. Ignored entirely in `scan` mode (the scan IS the feed).
+    scan_fallback_interval: int = 3600
+
     # Derived at build time: `repos` casefolded for matching. GitHub names are
     # case-insensitive, but `repos` keeps the operator's casing for logs/repr.
     _repo_match: frozenset[str] = field(
@@ -205,6 +263,16 @@ class Config:
         GitHub owner/repo names."""
         return full_name.casefold() in self._repo_match
 
+    def trusts_feed_owner(self, actor_id: str | None) -> bool:
+        """Whether a Body of Work owned by this actor may act as a release feed.
+
+        Fail-closed on a MISSING owner too: a container whose provenance the
+        payload does not state cannot be attributed, and an unattributable feed
+        is exactly what `bow_owners` exists to refuse. Exact comparison — Alissa
+        actor ids are opaque, so normalising them would only widen the match.
+        """
+        return bool(actor_id) and actor_id in self.bow_owners
+
     @classmethod
     def build(
         cls,
@@ -280,6 +348,65 @@ class Config:
             if not value.strip():
                 raise ValueError(f"{name} must be a non-empty string")
 
+        release_feed = str(raw.get("release_feed", cls.release_feed)).strip().lower()
+        if release_feed not in RELEASE_FEEDS:
+            raise ValueError(
+                f"release_feed must be one of {', '.join(RELEASE_FEEDS)}, got "
+                f"{raw.get('release_feed')!r}"
+            )
+
+        # NOT stripped: the convention's trailing space (`autodev: `) is load-
+        # bearing, so only an all-whitespace prefix is rejected. An empty prefix
+        # would make EVERY Body of Work a release feed.
+        bow_prefix = str(raw.get("bow_prefix", cls.bow_prefix))
+        if not bow_prefix.strip():
+            raise ValueError(
+                "bow_prefix must be a non-empty string — an empty prefix would "
+                "turn every Body of Work into a release feed"
+            )
+
+        bow_owners = _string_list(raw.get("bow_owners", cls.bow_owners), "bow_owners")
+        if release_feed == FEED_BOW and not bow_owners:
+            # Fail-closed, the `repos` guard's twin. `repos` bounds WHERE the
+            # orchestrator writes; this bounds WHOSE work drives it. The feed
+            # lists Bodies of Work the daemon merely collaborates on, and being
+            # made a collaborator takes no acceptance step on this side, so
+            # without an owner allowlist "shared with the daemon and titled for
+            # a watched repo" is enough to get a task rendered into an issue in
+            # that repo and handed to the develop pipeline. Only fatal for the
+            # `bow` feed: `scan` never reads a Body of Work at all.
+            raise ValueError(
+                "bow_owners is empty and release_feed is 'bow' — the release "
+                "feed is fail-closed and refuses to start without the actor "
+                "id(s) allowed to own a feed Body of Work (being shared one is "
+                "not a claim to drive this daemon). Set `bow_owners` in the "
+                "config file, pass one or more --bow-owner flags, or set "
+                "ALISSA_ORC_BOW_OWNERS. An actor id is the `ownerActorId` on "
+                "the container's row in GET /v1/bodies-of-work."
+            )
+
+        fallback = int(raw.get("scan_fallback_interval", cls.scan_fallback_interval))
+        if fallback < 0:
+            raise ValueError(
+                f"scan_fallback_interval must be >= 0 (0 disables the sweep), "
+                f"got {fallback}"
+            )
+        if 0 < fallback < MIN_POLL_INTERVAL:
+            # A floor on absurd values, nothing more. The sweep is driven from
+            # the poll loop, so it can never run more often than `poll_interval`
+            # anyway -- what this rejects is a value so small it reads as "off"
+            # to a human but is not (`1`), and it shares MIN_POLL_INTERVAL
+            # rather than inventing a second floor. The real contract -- that
+            # the sweep is LOW-frequency relative to the poll, so the `bow` feed
+            # keeps saving the full scan it exists to avoid -- is the operator's
+            # to set: any `scan_fallback_interval <= poll_interval` sweeps on
+            # every poll, which is legitimate on a slow poll and wasteful on a
+            # fast one, so it is documented (README) rather than enforced here.
+            raise ValueError(
+                f"scan_fallback_interval must be 0 (off) or >= {MIN_POLL_INTERVAL} "
+                f"seconds, got {fallback}"
+            )
+
         ledger_path = raw.get("ledger_path", cls.ledger_path)
         return cls(
             workspace_root=Path(workspace_root),
@@ -296,6 +423,10 @@ class Config:
                 raw.get("close_loop_enabled", cls.close_loop_enabled)
             ),
             dry_run=bool(raw.get("dry_run", cls.dry_run)),
+            release_feed=release_feed,
+            bow_prefix=bow_prefix,
+            bow_owners=bow_owners,
+            scan_fallback_interval=fallback,
         )