tickwork 0.3.0__py3-none-any.whl

tickwork/pool.py

@@ -0,0 +1,214 @@
+"""Role-keyed flock claim and worker-slot primitives.
+
+The concurrency primitives a worker pool needs, built on ``fcntl.flock`` with
+non-blocking acquisition: no waiting, no daemon, and no explicit cleanup (the
+lock is released when the holding process exits or crashes).
+
+- ``try_claim(role, state_dir, kind, repo, number)`` — claim exclusive
+  ownership of an item (e.g. ``kind="issue"`` or ``"pr"``) so two concurrent
+  ticks of *role* never work the same item.
+- ``acquire_worker_slot(role, state_dir, pool_size)`` — claim the
+  lowest-numbered free slot in ``1..pool_size`` for per-tick disambiguation
+  (branch naming, local state).
+- ``lock_worker_slot(role, state_dir, slot)`` — claim a *specific* slot's
+  lease (no free-slot scan), for when the slot is pinned from outside the
+  process.
+- ``flock_nonblock(path)`` — open *path* and take a non-blocking exclusive
+  ``flock`` on it; returns the file descriptor, or ``None`` when another
+  holder has the lock.  Public so a caller can hold an extra lock file
+  next to the generic ones.
+
+Lock files live under ``<state_dir>/claims/<role>/<kind>-<owner>_<repo>-<n>.lock``
+and ``<state_dir>/slots/<role>/<slot>.lock``.  The state directory is
+passed in by the caller; this module reads no environment variables, so it
+names nothing of the instance it runs for.
+
+stdlib-only — no new dependencies.  ``fcntl.flock`` is POSIX-only; the module
+will fail at import on non-POSIX platforms (consistent with the repo's
+single-host Linux deploy model).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import os
+from collections.abc import Generator
+
+
+def _item_lock_path(role: str, state_dir: str, kind: str, repo: str | None, number: int) -> str:
+    """Full path to the lock file for one item of *kind* held by *role*.
+
+    With *repo*, the path is keyed by repo too, so the same item number in
+    two repos doesn't share one lock.  ``owner/name`` is flattened into one
+    path component (``owner_name``).
+    """
+    claims_dir = os.path.join(state_dir, "claims", role)
+    if repo:
+        return os.path.join(claims_dir, f"{kind}-{repo.replace('/', '_')}-{number}.lock")
+    return os.path.join(claims_dir, f"{kind}-{number}.lock")
+
+
+def _slot_lock_path(role: str, state_dir: str, slot: int) -> str:
+    """Full path to the lock file for a worker slot (1-indexed)."""
+    return os.path.join(state_dir, "slots", role, f"{slot}.lock")
+
+
+# ─── helpers ─────────────────────────────────────────────────────────────────
+
+
+def _ensure_dir(path: str) -> None:
+    """Create *path* (and parents) if absent.  Silent on success; raises on
+    permission errors so the caller can surface the failure."""
+    os.makedirs(path, exist_ok=True)
+
+
+def flock_nonblock(path: str) -> int | None:
+    """Open *path* for writing (creating it if needed) and try a non-blocking
+    exclusive ``flock``.  Returns the file descriptor on success, or ``None``
+    when another process already holds the lock (``EWOULDBLOCK``).
+
+    The lock file is created with ``os.O_CREAT`` so it persists on disk even
+    after the lock is released — this is intentional: ``flock`` is advisory
+    and tied to the file descriptor, so the file's existence on disk is
+    harmless and re-using the same path is critical for cross-process
+    coordination.
+
+    On an unrecoverable OS error (e.g. ``PermissionError``, ``IOError`` from
+    a full filesystem) the exception propagates so the caller can escalate
+    rather than silently proceeding without a lock.
+    """
+    try:
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT, 0o644)
+    except OSError as e:
+        # The directory doesn't exist yet — create it and retry once.
+        if e.errno == 2:  # ENOENT
+            _ensure_dir(os.path.dirname(path))
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT, 0o644)
+        else:
+            raise
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError as e:
+        os.close(fd)
+        if e.errno in (11, 35):  # EAGAIN / EWOULDBLOCK
+            return None
+        raise
+    return fd
+
+
+@contextlib.contextmanager
+def _lock_holder(fd: int) -> Generator[None, None, None]:
+    """Context manager that holds a ``flock``-ed file descriptor for the
+    duration of the ``with`` block, then releases it.
+
+    The lock is released either by an explicit ``os.close`` (the ``finally``
+    block), or automatically when the process exits — the kernel releases all
+    file-descriptor locks on process termination, so a crashed/killed process
+    never leaves a stale lock behind.
+    """
+    try:
+        yield
+    finally:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass  # best-effort; a crash during yield may leave fd stale, but
+            # the kernel will clean up on process exit.
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
+@contextlib.contextmanager
+def _slot_id_holder(fd: int, slot: int) -> Generator[int, None, None]:
+    """Like ``_lock_holder`` but also yields the *slot* integer to the ``with``
+    target so ``acquire_worker_slot`` and ``lock_worker_slot`` can be used as::
+
+        with acquire_worker_slot(role, state, 3) as slot:
+            print(slot)  # 1, 2, or 3
+    """
+    try:
+        yield slot
+    finally:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+
+# ─── public API ──────────────────────────────────────────────────────────────
+
+
+def try_claim(
+    role: str, state_dir: str, kind: str, repo: str | None, number: int
+) -> contextlib.AbstractContextManager | None:
+    """Attempt a non-blocking claim by *role* on item *number* of *kind*.
+
+    *kind* selects the lock-file prefix (``"issue"``, ``"pr"``, …); each kind
+    gets its own lock, so a PR 7 and an issue 7 don't collide.  *repo* keys
+    the lock by repository when given.
+
+    Returns a context manager that holds the exclusive lock for the lifetime
+    of the ``with`` block, or ``None`` if another process already holds the
+    claim.  The lock is released on context-manager exit OR on process
+    exit/crash (kernel-managed, no cleanup needed).
+
+    Usage::
+
+        claim = try_claim(role, state_dir, "issue", repo, 42)
+        if claim is None:
+            log("issue 42 already claimed by another tick")
+            return
+        with claim:
+            ...  # compose the work
+    """
+    fd = flock_nonblock(_item_lock_path(role, state_dir, kind, repo, number))
+    if fd is None:
+        return None
+    return _lock_holder(fd)
+
+
+def lock_worker_slot(role: str, state_dir: str, slot: int) -> contextlib.AbstractContextManager | None:
+    """Claim the flock lease on *specifically* slot *slot* — no free-slot scan.
+
+    Companion to :func:`acquire_worker_slot` for the pinned-slot case: when
+    the slot is set from outside the process, the lease must still be *taken*
+    so concurrent ticks on the same slot collide instead of silently running
+    double — but which slot it is has already been decided, so there is
+    nothing to scan for.
+
+    Returns a context manager yielding *slot*, or ``None`` if the slot is
+    already held by another worker (caller should skip the tick, same contract
+    as a full :func:`acquire_worker_slot` scan).
+    """
+    if slot is None or slot < 1:
+        return None
+    fd = flock_nonblock(_slot_lock_path(role, state_dir, slot))
+    if fd is None:
+        return None
+    return _slot_id_holder(fd, slot)
+
+
+def acquire_worker_slot(
+    role: str, state_dir: str, pool_size: int
+) -> contextlib.AbstractContextManager | None:
+    """Claim the lowest-numbered free worker slot in ``1..pool_size`` for *role*.
+
+    Returns a context manager that yields the slot number (``int``) for the
+    duration of the ``with`` block, or ``None`` if every slot is taken (or
+    ``pool_size < 1``).  When all slots are occupied, returns ``None``
+    immediately — the caller should skip the tick rather than waiting.
+    """
+    if pool_size < 1:
+        return None
+    for slot in range(1, pool_size + 1):
+        fd = flock_nonblock(_slot_lock_path(role, state_dir, slot))
+        if fd is not None:
+            return _slot_id_holder(fd, slot)
+    return None

tickwork/providers/__init__.py

@@ -0,0 +1,10 @@
+"""Provider implementations for :mod:`tickwork.replay`.
+
+Each provider is a stdlib-only adapter speaking one API shape, imported
+here so a CLI can map a ``--provider <name>`` flag to an adapter without
+the replay core knowing about transports.
+"""
+
+from tickwork.providers.openai_compat import OpenAICompatProvider
+
+__all__ = ["OpenAICompatProvider"]

tickwork/providers/openai_compat.py

@@ -0,0 +1,82 @@
+"""A stdlib-only :class:`~tickwork.replay.Provider` for OpenAI-compatible APIs.
+
+Speaks any ``/chat/completions`` endpoint: the base URL and the name of the
+API-key environment variable are constructor parameters, so nothing about a
+deployment is baked in. The key is read from the environment per call and
+used only in the request's ``Authorization`` header — it is never logged,
+printed, or included in an error string.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.request
+from typing import Any
+
+from tickwork.replay import Reply
+
+
+class OpenAICompatProvider:
+    """Provider for any OpenAI-compatible ``/chat/completions`` endpoint."""
+
+    def __init__(self, base_url: str, key_env: str = "OPENAI_API_KEY", timeout: float = 120.0):
+        self.base_url = base_url.rstrip("/")
+        self.key_env = key_env
+        self.timeout = timeout
+
+    def generate(self, model: str, messages: list[dict]) -> Reply:
+        """Send *messages* to *model*; failures come back as a Reply."""
+        start = time.monotonic()
+        response, usage, finish_reason, error = self._chat(model, messages)
+        return {
+            "response": response,
+            "ms": int((time.monotonic() - start) * 1000),
+            "prompt_tokens": _usage_int(usage, "prompt_tokens"),
+            "completion_tokens": _usage_int(usage, "completion_tokens"),
+            "reasoning_tokens": _usage_int(usage.get("completion_tokens_details") or {}, "reasoning_tokens"),
+            "cache_hit_tokens": _usage_int(usage.get("prompt_tokens_details") or {}, "cached_tokens"),
+            "finish_reason": finish_reason,
+            "error": error,
+        }
+
+    def _chat(self, model: str, messages: list[dict]) -> tuple[str | None, Any, str | None, str | None]:
+        """One POST; returns (response text, usage, finish_reason, error).
+
+        The key is only ever attached as the Authorization header of the
+        request object, which is never str()'d or logged — so no failure
+        path can carry it into the returned error string.
+        """
+        key = os.environ.get(self.key_env)
+        if not key:
+            return None, {}, None, f"environment variable {self.key_env} is not set"
+        request = urllib.request.Request(
+            f"{self.base_url}/chat/completions",
+            data=json.dumps({"model": model, "messages": messages}).encode("utf-8"),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {key}"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                data = json.loads(response.read().decode("utf-8"))
+        except Exception as exc:  # one bad call is one errored reply, not a crash
+            return None, {}, None, f"{type(exc).__name__}: {exc}"
+        if not isinstance(data, dict):
+            return None, {}, None, f"malformed response: top level is {type(data).__name__}"
+        choices = data.get("choices")
+        if not isinstance(choices, list) or not choices or not isinstance(choices[0], dict):
+            return None, {}, None, "malformed response: no choices[0] object"
+        choice = choices[0]
+        message = choice.get("message") or {}
+        content = message.get("content") if isinstance(message, dict) else None
+        response_text = content if isinstance(content, str) else None
+        usage = data.get("usage") or {}
+        usage = usage if isinstance(usage, dict) else {}
+        return response_text, usage, choice.get("finish_reason"), None
+
+
+def _usage_int(usage: dict, key: str) -> int | None:
+    """The int value of one usage counter, or None when absent/malformed."""
+    val = usage.get(key)
+    return int(val) if isinstance(val, (int, float)) else None

tickwork/replay.py

@@ -0,0 +1,134 @@
+"""Generic replay of recorded LLM calls.
+
+The instance-neutral core of the offline replay: read the final transcript
+records (the ``final: true`` JSONL records carrying the
+complete ``messages`` array), send each ``messages`` array to a model
+through a caller-supplied :class:`Provider`, deep-merge a variant overlay,
+and score every reply into one metrics dict per (record, model, repeat).
+The module imports nothing beyond the standard library and names no
+deployment: providers and scorers are parameters, never imports.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from pathlib import Path
+from typing import Any, Protocol, TypedDict
+
+
+class Reply(TypedDict):
+    """One model reply plus the per-call facts a metrics line is built from."""
+
+    response: str | None
+    ms: int
+    prompt_tokens: int | None
+    completion_tokens: int | None
+    reasoning_tokens: int | None
+    cache_hit_tokens: int | None
+    finish_reason: str | None
+    error: str | None
+
+
+class Provider(Protocol):
+    """Anything that can send a recorded ``messages`` array to a model.
+
+    Implementations surface call failures as the ``error`` field of a
+    :class:`Reply` (never raised), so one bad call skips into the metrics
+    instead of aborting the run.
+    """
+
+    def generate(self, model: str, messages: list[dict]) -> Reply: ...
+
+
+def read_records(paths: Iterable[str | Path]) -> Iterator[dict]:
+    """Yield the final transcript records of *paths* (JSONL files).
+
+    A final record (the transcript writer marks it ``final: true``) carries
+    the call's complete ``messages`` array; every other line is skipped:
+    blank lines, lines JSON cannot parse, non-dict
+    lines, intermediate (non-final) records, and final records without a
+    usable ``messages`` array. Skipping, not failing: a transcript
+    legitimately mixes records, and only the finals replay.
+    """
+    for path in paths:
+        with open(path, encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if (
+                    isinstance(rec, dict)
+                    and rec.get("final") is True
+                    and isinstance(rec.get("messages"), list)
+                    and rec.get("messages")
+                ):
+                    yield rec
+
+
+def deep_merge(base: dict, overlay: dict) -> dict:
+    """Recursively merge ``overlay`` into ``base`` (returns a new dict).
+
+    Nested mappings merge key by key; every other value (scalars, lists)
+    is replaced wholesale by the overlay's value.
+    """
+    out = dict(base)
+    for key, val in overlay.items():
+        if isinstance(val, dict) and isinstance(out.get(key), dict):
+            out[key] = deep_merge(out[key], val)
+        else:
+            out[key] = val
+    return out
+
+
+def replay(
+    records: Iterable[dict],
+    provider: Provider,
+    models: Sequence[str],
+    scorers: Mapping[tuple[str, str], Any],
+    repeats: int = 1,
+    skips: dict[str, int] | None = None,
+) -> Iterator[dict]:
+    """Replay every (record, model, repeat) and yield one metrics dict each.
+
+    ``scorers`` maps a ``(role, stage)`` pair — or the wildcard
+    ``("*", "*")`` fallback — to a ``(record, reply) -> dict`` function whose
+    result is merged into that record's metrics line. A record with no
+    matching scorer is skipped and counted in ``skips`` under a readable
+    reason when the caller passes a mapping. A provider failure arrives as
+    the reply's ``error`` field and flows into the metrics line; replay
+    itself never raises for one bad call.
+    """
+    for rec in records:
+        role, stage = rec.get("role"), rec.get("stage")
+        scorer = scorers.get((role, stage), scorers.get(("*", "*")))
+        if scorer is None:
+            if skips is not None:
+                reason = f"no scorer for {role}/{stage}"
+                skips[reason] = skips.get(reason, 0) + 1
+            continue
+        for model in models:
+            for repeat in range(max(repeats, 0)):
+                reply = provider.generate(model, rec["messages"])
+                metrics = {
+                    "role": role,
+                    "stage": stage,
+                    "repo": rec.get("repo"),
+                    "issue": rec.get("issue"),
+                    "model": model,
+                    "repeat": repeat,
+                    "ms": reply.get("ms"),
+                    "response": reply.get("response"),
+                    "prompt_tokens": reply.get("prompt_tokens"),
+                    "completion_tokens": reply.get("completion_tokens"),
+                    "reasoning_tokens": reply.get("reasoning_tokens"),
+                    "cache_hit_tokens": reply.get("cache_hit_tokens"),
+                    "finish_reason": reply.get("finish_reason"),
+                    "error": reply.get("error"),
+                }
+                metrics.update(scorer(rec, reply))
+                yield metrics

tickwork/workflow_states.py

@@ -0,0 +1,226 @@
+"""Loader and validator for a workflow states file.
+
+A states file maps each workflow state to a predicate (``when``), a board
+bucket (``board``) and an owner (``owner``: a role name or ``human``). This
+module knows nothing about any instance: the caller supplies the path and the
+set of allowed owner names. It names no role and has no default path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+HUMAN = "human"
+
+# The predicate vocabulary a `when` block may use, at any nesting depth.
+PREDICATE_KEYS = frozenset(
+    {
+        "issue.state",
+        "issue.assignee",
+        "issue.dependencies",
+        "pr",
+        "pr.state",
+        "pr.assignee",
+        "pr.requested_reviewers",
+        "pr.reviewed_on_head",
+        "pr.approved_on_head",
+        "any",
+        "not",
+    }
+)
+
+VALID_BOARDS = frozenset(
+    {
+        "queued",
+        "in_progress",
+        "waiting_on_human",
+        "blocked",
+        "done",
+        "failed",
+        "intake",
+    }
+)
+
+_STATE_FIELDS = frozenset({"when", "board", "owner", "override", "terminal"})
+
+
+def load(path: str | Path, roles: set[str]) -> dict[str, dict[str, Any]]:
+    """Read and validate the states file at *path*.
+
+    *roles* is the set of allowed role-name owners; ``human`` is always allowed.
+
+    Returns ``{state name: {when, board, owner, override, terminal}}`` in file
+    order (``override``/``terminal`` default to ``False``; a ``terminal`` state
+    may omit ``owner``).
+
+    Raises ``ValueError`` naming the state and the offending field on any
+    violation.
+    """
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or not isinstance(data.get("states"), dict):
+        raise ValueError(f"{path}: top level must be a mapping with a `states` block")
+    allowed_owners = set(roles) | {HUMAN}
+    states: dict[str, dict[str, Any]] = {}
+    for name, spec in data["states"].items():
+        if not isinstance(name, str) or not name:
+            raise ValueError(f"states: state name {name!r} must be a non-empty string")
+        if not isinstance(spec, dict):
+            raise ValueError(f"{name}: state must be a mapping, got {type(spec).__name__}")
+        unknown = sorted(set(spec) - _STATE_FIELDS)
+        if unknown:
+            raise ValueError(f"{name}: unknown field(s) {unknown}")
+        when = spec.get("when")
+        if not isinstance(when, dict) or not when:
+            raise ValueError(f"{name}: `when` must be a non-empty mapping")
+        _check_predicates(name, when)
+        board = spec.get("board")
+        if board not in VALID_BOARDS:
+            raise ValueError(f"{name}: `board` {board!r} not in {sorted(VALID_BOARDS)}")
+        for field in ("override", "terminal"):
+            value = spec.get(field, False)
+            if not isinstance(value, bool):
+                raise ValueError(f"{name}: `{field}` must be a boolean, got {value!r}")
+        owner = spec.get("owner")
+        if owner is None:
+            if not spec.get("terminal", False):
+                raise ValueError(f"{name}: missing `owner`")
+        elif owner not in allowed_owners:
+            raise ValueError(f"{name}: `owner` {owner!r} not in {sorted(allowed_owners)}")
+        states[name] = {
+            "when": when,
+            "board": board,
+            "owner": owner,
+            "override": spec.get("override", False),
+            "terminal": spec.get("terminal", False),
+        }
+    return states
+
+
+def _check_predicates(state: str, pred: dict[str, Any]) -> None:
+    """Validate predicate keys at any depth of a `when` block."""
+    for key, value in pred.items():
+        if key not in PREDICATE_KEYS:
+            raise ValueError(f"{state}: `when` has unknown predicate key {key!r}")
+        if key == "any":
+            if not isinstance(value, list) or not all(isinstance(v, dict) for v in value):
+                raise ValueError(f"{state}: `when.any` must be a list of mappings")
+            for sub in value:
+                _check_predicates(state, sub)
+        elif key == "not":
+            if not isinstance(value, dict):
+                raise ValueError(f"{state}: `when.not` must be a mapping")
+            _check_predicates(state, value)
+
+
+# ─── predicate evaluation ─────────────────────────────────────────────────────
+
+# Predicate leaf → the field of the item dict it reads. Assignee predicates
+# name a ROLE, or the value `none` (`issue.assignee` only) meaning an empty
+# assignees list; role names resolve through the caller-supplied `logins`.
+_ITEM_KEYS = {
+    "assignee": "assignees",
+    "requested_reviewers": "requested_reviewers",
+    "state": "state",
+    "dependencies": "open_dependencies",
+    "reviewed_on_head": "reviewed_on_head",
+    "approved_on_head": "approved_on_head",
+}
+
+
+def evaluate(states: dict[str, dict[str, Any]], item: dict[str, Any], logins: dict[str, str]) -> list[str]:
+    """Return the names of all states whose `when` predicate matches *item*.
+
+    Override states are tested first, in file order, and the first match wins
+    alone. Otherwise the result is every matching non-override state.
+
+    *item* is a plain dict built from adapter data: ``repo``, ``issue``
+    (``number``/``state``/``assignees``/``open_dependencies``) and ``pr``
+    (``None``, or ``number``/``state``/``assignees``/``requested_reviewers``/
+    ``reviewed_on_head``/``approved_on_head``). Role names in predicates
+    resolve to logins through *logins*; this module never looks logins up
+    itself. Well-formed items resolve to exactly one state; zero or 2+ is an
+    anomaly that :func:`check` reports.
+    """
+    for name, spec in states.items():
+        if spec["override"] and _match(spec["when"], item, logins):
+            return [name]
+    return [
+        name for name, spec in states.items() if not spec["override"] and _match(spec["when"], item, logins)
+    ]
+
+
+def check(
+    states: dict[str, dict[str, Any]],
+    items: list[dict[str, Any]],
+    logins: dict[str, str],
+) -> list[dict]:
+    """Report every *item* that matches zero or 2+ states.
+
+    Returns one anomaly ``{repo, issue, pr, matched: [...]}`` per mis-mapped
+    item, in items order: an item matched by nothing is owned by nobody, one
+    matched twice is contested between owners.
+    """
+    anomalies: list[dict] = []
+    for item in items:
+        matched = evaluate(states, item, logins)
+        if len(matched) != 1:
+            anomalies.append(
+                {
+                    "repo": item.get("repo"),
+                    "issue": (item.get("issue") or {}).get("number"),
+                    "pr": (item.get("pr") or {}).get("number"),
+                    "matched": matched,
+                }
+            )
+    return anomalies
+
+
+def _match(pred: dict[str, Any], item: dict[str, Any], logins: dict[str, str]) -> bool:
+    return all(_leaf(key, value, item, logins) for key, value in pred.items())
+
+
+def _leaf(key: str, expected: Any, item: dict[str, Any], logins: dict[str, str]) -> bool:
+    if key == "any":
+        return any(_match(sub, item, logins) for sub in expected)
+    if key == "not":
+        return not _match(expected, item, logins)
+    section, _, attr = key.partition(".")
+    if not attr:
+        # A bare section name (`pr`) tests presence: the only use is `pr: none`.
+        has = item.get("pr") is not None
+        return has if expected != "none" else not has
+    obj = item.get(section) or {}
+    if attr == "assignee" or attr == "requested_reviewers":
+        if not isinstance(expected, str):
+            return False
+        if expected == "none":
+            # `issue.assignee: none` tests an empty assignees list, in the
+            # way `pr: none` tests PR absence. A role name is never `none`.
+            if attr != "assignee":
+                return False
+            return not (obj.get(_ITEM_KEYS[attr]) or [])
+        return _role_login(expected, logins, key) in (obj.get(_ITEM_KEYS[attr]) or [])
+    if attr == "state":
+        return obj.get("state") == expected
+    if attr == "dependencies":
+        truth = bool(obj.get("open_dependencies"))
+        return truth if expected == "open" else not truth
+    if attr in ("reviewed_on_head", "approved_on_head"):
+        return bool(obj.get(_ITEM_KEYS[attr])) == _as_bool(expected)
+    return False  # validated files cannot reach an unknown leaf
+
+
+def _role_login(role: str, logins: dict[str, str], key: str) -> str:
+    try:
+        return logins[role]
+    except KeyError:
+        raise ValueError(f"`{key}`: role {role!r} not in the caller-supplied `logins`") from None
+
+
+def _as_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in {"true", "yes"}

tickwork-0.3.0.data/data/share/tickwork/examples/items.jsonl

@@ -0,0 +1,3 @@
+{"repo": "example/widget", "issue": {"number": 101, "state": "open", "assignees": ["dee"], "open_dependencies": []}, "pr": null}
+{"repo": "example/widget", "issue": {"number": 102, "state": "open", "assignees": ["dee"], "open_dependencies": []}, "pr": {"number": 202, "state": "open", "assignees": [], "requested_reviewers": [], "reviewed_on_head": false, "approved_on_head": false}}
+{"repo": "example/widget", "issue": {"number": 103, "state": "open", "assignees": ["dee"], "open_dependencies": []}, "pr": {"number": 203, "state": "open", "assignees": [], "requested_reviewers": ["ria"], "reviewed_on_head": false, "approved_on_head": true}}

tickwork-0.3.0.data/data/share/tickwork/examples/logins.yaml

@@ -0,0 +1,7 @@
+# Role name → login. The logins are made up for the example; substitute your
+# own. `human` is needed because the states file's override predicates name it.
+dev: dee
+reviewer: ria
+planner: pip
+verifier: val
+human: hum