aflib 0.0.6__tar.gz → 0.0.7__tar.gz

{aflib-0.0.6 → aflib-0.0.7}/.gitignore

@@ -5,3 +5,4 @@ build/
 dist/
 .venv/
 .pytest_cache/
+.env

{aflib-0.0.6 → aflib-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: aflib
-Version: 0.0.6
+Version: 0.0.7
 Summary: Helper library for business logic inside Airflows plpython function bodies
 License: MIT
 License-File: LICENSE
@@ -27,16 +27,49 @@ so low.
 Airflows resolves Python packages from public PyPI by name and version only; there is no
 local-import, git or private-index route. Declare it in
 `models/pythonPackages/pythonPackages.airflows` by pinning **name and version in
-separate fields** — never as a single `aflib==0.0.6` string (that form produced
+separate fields** — never as a single `aflib==0.0.7` string (that form produced
 malformed `name==ver==ver` entries in a real instance's package list):
 
 ```
 name:    aflib
-version: 0.0.6
+version: 0.0.7
 ```
 
 Then import it from a function body.
 
+## What 0.0.7 gives you
+
+Everything in 0.0.6, plus three capabilities that ran on a real instance on
+2026-10-01 before they were extracted:
+
+- **`Batch(plpy).run(...)`** — one committed chunk. The pending predicate is
+  placed in the outer `WHERE` and in the subquery, and the result carries
+  `done`, `remaining` and `seconds`.
+- **`workflow.start` / `status` / `stuck`** — insert a `PENDING` workflow
+  instance and its variables, read the newest instance for a business key, and
+  list instances that are still `PENDING` or `IN_PROGRESS` after an interval.
+- **`Outbox(plpy, outbox=..., delivery=..., subscription=...).emit` / `pump`** —
+  one event plus a pending delivery per active subscriber, then a chunk of
+  deliveries. Each subscriber runs inside `plpy.subtransaction()`. Failures
+  retry with `attempts`, `next_attempt_at` and `last_error`, and dead-letter
+  after 3 attempts.
+
+```python
+from aflib import workflow
+from aflib.events import Outbox
+
+workflow.start(plpy, "WFP_cadena", "case-58", {
+    "SomeSchema.some_function.p_id": ("INTEGER", 42),
+})
+
+box = Outbox(plpy, outbox="app.outbox", delivery="app.delivery", subscription="app.sub")
+box.emit("order.placed", {"id": 42}, 42)
+box.pump(deliver, limit=50)
+```
+
+`deliver(subscriber, outbox_id, attempt)` does the work and raises to fail the
+attempt. Table names are identifiers you wrote, not request data.
+
 ## What 0.0.6 gives you
 
 0.0.1–0.0.3 (read/result, errors/logging, `transaction.atomic`) plus what
@@ -58,10 +91,10 @@ the 2026-09 platform probes showed, plus two verified fixes:
   resolve.
 - **`identity.current_user(plpy)`** — `SELECT current_user`. Not a User id.
 
-Pin **name and version in separate fields** (`aflib` / `0.0.6`), not
-`aflib==0.0.6` as one string.
+Pin **name and version in separate fields** (`aflib` / `0.0.7`), not
+`aflib==0.0.7` as one string.
 
-## Core API (0.0.1–0.0.3, still in 0.0.6)
+## Core API (0.0.1–0.0.3, still in 0.0.7)
 
 ```python
 from aflib import Db, errors, fail, logging, ok, params

{aflib-0.0.6 → aflib-0.0.7}/README.md

@@ -18,16 +18,49 @@ so low.
 Airflows resolves Python packages from public PyPI by name and version only; there is no
 local-import, git or private-index route. Declare it in
 `models/pythonPackages/pythonPackages.airflows` by pinning **name and version in
-separate fields** — never as a single `aflib==0.0.6` string (that form produced
+separate fields** — never as a single `aflib==0.0.7` string (that form produced
 malformed `name==ver==ver` entries in a real instance's package list):
 
 ```
 name:    aflib
-version: 0.0.6
+version: 0.0.7
 ```
 
 Then import it from a function body.
 
+## What 0.0.7 gives you
+
+Everything in 0.0.6, plus three capabilities that ran on a real instance on
+2026-10-01 before they were extracted:
+
+- **`Batch(plpy).run(...)`** — one committed chunk. The pending predicate is
+  placed in the outer `WHERE` and in the subquery, and the result carries
+  `done`, `remaining` and `seconds`.
+- **`workflow.start` / `status` / `stuck`** — insert a `PENDING` workflow
+  instance and its variables, read the newest instance for a business key, and
+  list instances that are still `PENDING` or `IN_PROGRESS` after an interval.
+- **`Outbox(plpy, outbox=..., delivery=..., subscription=...).emit` / `pump`** —
+  one event plus a pending delivery per active subscriber, then a chunk of
+  deliveries. Each subscriber runs inside `plpy.subtransaction()`. Failures
+  retry with `attempts`, `next_attempt_at` and `last_error`, and dead-letter
+  after 3 attempts.
+
+```python
+from aflib import workflow
+from aflib.events import Outbox
+
+workflow.start(plpy, "WFP_cadena", "case-58", {
+    "SomeSchema.some_function.p_id": ("INTEGER", 42),
+})
+
+box = Outbox(plpy, outbox="app.outbox", delivery="app.delivery", subscription="app.sub")
+box.emit("order.placed", {"id": 42}, 42)
+box.pump(deliver, limit=50)
+```
+
+`deliver(subscriber, outbox_id, attempt)` does the work and raises to fail the
+attempt. Table names are identifiers you wrote, not request data.
+
 ## What 0.0.6 gives you
 
 0.0.1–0.0.3 (read/result, errors/logging, `transaction.atomic`) plus what
@@ -49,10 +82,10 @@ the 2026-09 platform probes showed, plus two verified fixes:
   resolve.
 - **`identity.current_user(plpy)`** — `SELECT current_user`. Not a User id.
 
-Pin **name and version in separate fields** (`aflib` / `0.0.6`), not
-`aflib==0.0.6` as one string.
+Pin **name and version in separate fields** (`aflib` / `0.0.7`), not
+`aflib==0.0.7` as one string.
 
-## Core API (0.0.1–0.0.3, still in 0.0.6)
+## Core API (0.0.1–0.0.3, still in 0.0.7)
 
 ```python
 from aflib import Db, errors, fail, logging, ok, params

{aflib-0.0.6 → aflib-0.0.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aflib"
-version = "0.0.6"
+version = "0.0.7"
 description = "Helper library for business logic inside Airflows plpython function bodies"
 readme = "README.md"
 # The platform runs Python 3.11.2 (observed, not assumed — see docs/platform-constraints.md).

{aflib-0.0.6 → aflib-0.0.7}/src/aflib/__init__.py

@@ -33,9 +33,11 @@ Python exception.
 
 from aflib import (
     authz,
+    batch,
     codec,
     db,
     errors,
+    events,
     functions,
     identity,
     logging,
@@ -43,23 +45,30 @@ from aflib import (
     result,
     transaction,
     trigger,
+    workflow,
 )
+from aflib.batch import Batch
 from aflib.db import Db
+from aflib.events import Outbox
 from aflib.params import BadParameter
 from aflib.result import fail, ok
 
 # Kept in step with `pyproject.toml` by hand. A deployed body returns this so a run can
 # prove which aflib it actually imported — a stale package otherwise looks exactly like a
 # working one.
-__version__ = "0.0.6"
+__version__ = "0.0.7"
 
 __all__ = [
     "BadParameter",
+    "Batch",
     "Db",
+    "Outbox",
     "authz",
+    "batch",
     "codec",
     "db",
     "errors",
+    "events",
     "fail",
     "functions",
     "identity",
@@ -69,5 +78,6 @@ __all__ = [
     "result",
     "transaction",
     "trigger",
+    "workflow",
     "__version__",
 ]

aflib-0.0.7/src/aflib/batch.py

@@ -0,0 +1,141 @@
+"""Work through a backlog one committed chunk at a time.
+
+    from aflib.batch import Batch
+
+    batch = Batch(plpy)
+
+    progress = batch.run(
+        table="\\"Economic\\".\\"Receipt\\"",
+        set_clause='id_status = $1',
+        pending='id_status = $2 AND (period_from IS NULL OR period_from <= CURRENT_DATE + 5)',
+        args=[pending_id, planned_id],
+        types=["integer", "integer"],
+        limit=1000,
+    )
+
+    return ok({"done": progress.done, "remaining": progress.remaining})
+
+One call is one chunk. The caller decides what drives the next one — a `pg_cron` job, the
+next step of a workflow, a human pressing a button again — and each call is its own
+transaction, so each chunk is **kept** whether or not the next one happens.
+
+**Why a function and not a loop.** A plpgsql or plpython function cannot commit: it runs
+inside a transaction it does not own, and `plpy.commit()` fails with *invalid transaction
+termination*. There are no `PROCEDURE`s on the platform either (401 functions, zero
+procedures, measured 2026-10-01), so the usual `LOOP … COMMIT` shape has nowhere to live.
+A chunk per invocation is not a stylistic choice; it is the only way to commit progress.
+
+**The one rule this exists to enforce: the pending predicate goes in two places.** It
+selects the ids *and* it guards the update. Written the obvious way, with the predicate
+only in the subquery, this is wrong:
+
+    UPDATE t SET … WHERE id IN (SELECT id FROM t WHERE pending LIMIT 1000)   -- BROKEN
+
+Under `READ COMMITTED` the subquery runs against the statement's snapshot, but when the
+update reaches a row another transaction has since changed, Postgres re-reads the latest
+committed version and applies the update to **that**. A row that was pending when selected
+and is now cancelled gets updated anyway. On 2026-10-01 that aborted a production run on
+its second chunk: a receipt was cancelled by a user mid-batch and the trigger refused the
+`Cancelled → Pending` transition. Repeating the predicate in the outer `WHERE` makes
+Postgres re-evaluate it against the new version and skip the row.
+
+`run()` takes the predicate once and places it twice, so getting this wrong requires
+bypassing the helper.
+
+**`table`, `set_clause` and `pending` are SQL, and are interpolated.** They are code
+written by the caller, not values — values go in `args` and are bound. Never build them
+from anything a request supplied.
+
+**Chunk size is measured, not chosen.** Cost per row depends on the triggers the write
+fires, and the figure is not guessable: the same 1.000-row chunk took 19 s on
+`Economic.Receipt`, whose triggers recalculate and audit, and 0.07 ms per row on a bare
+table. Run one chunk, read `progress.seconds`, and size the rest so a chunk finishes well
+inside the environment's `statement_timeout` — 180 s on PRO, no limit on PRE, so **PRE
+cannot tell you whether a chunk fits**.
+"""
+
+import time
+
+from aflib.db import Db
+
+
+class Progress(object):
+    """What one chunk did, and whether there is more.
+
+    `remaining` is counted **after** the update, in the same transaction, so it already
+    reflects this chunk. A caller that loops until `complete` therefore terminates without
+    needing to subtract anything itself.
+    """
+
+    __slots__ = ("done", "remaining", "seconds")
+
+    def __init__(self, done, remaining, seconds):
+        self.done = done
+        self.remaining = remaining
+        self.seconds = seconds
+
+    @property
+    def complete(self):
+        """True when nothing is left to do."""
+        return self.remaining == 0
+
+    def as_dict(self):
+        return {"done": self.done, "remaining": self.remaining,
+                "seconds": round(self.seconds, 3), "complete": self.complete}
+
+    def __repr__(self):
+        return "Progress(done=%r, remaining=%r, complete=%r)" % (
+            self.done, self.remaining, self.complete)
+
+
+class Batch(object):
+    """One committed chunk per call. `plpy` is injected, as everywhere in aflib."""
+
+    def __init__(self, plpy):
+        self._db = Db(plpy)
+
+    ALIAS = "_t"
+
+    def run(self, table, set_clause, pending, args=None, types=None,
+            limit=1000, key="id", order=None):
+        """Update at most `limit` rows matching `pending`, and report what is left.
+
+        `pending` must be **unqualified** — write `id_status = $1`, not
+        `"Receipt".id_status = $1`. That is not a style rule: the same text is placed in
+        the outer `WHERE`, where Postgres resolves it against the update target, and
+        inside the subquery, where it resolves against the subquery's own `FROM`. Both
+        resolutions are what we want, and either qualification breaks one of them. A
+        predicate mentioning the alias is rejected rather than silently misplaced.
+
+        `order` defaults to `key`, which makes the work deterministic and the chunks
+        disjoint. Ordering by something non-unique would let two concurrent callers pick
+        overlapping sets; the row-level guard still keeps them correct, but they would
+        waste each other's work.
+        """
+        if self.ALIAS in pending:
+            raise ValueError(
+                "`pending` must be unqualified: it is placed both in the outer WHERE and "
+                "inside the subquery, and %r resolves in only one of them." % self.ALIAS)
+
+        args = list(args or [])
+        types = list(types or [])
+        order = order or key
+
+        started = time.time()
+        updated = self._db.query(
+            "UPDATE {table} AS {alias} SET {set_clause} "
+            "WHERE {pending} "
+            "  AND {alias}.{key} IN (SELECT {key} FROM {table} WHERE {pending} "
+            "                        ORDER BY {order} LIMIT {limit}) "
+            "RETURNING {alias}.{key}".format(
+                table=table, alias=self.ALIAS, set_clause=set_clause,
+                pending=pending, key=key, order=order, limit=int(limit)),
+            args, types).rows()
+        elapsed = time.time() - started
+
+        remaining = self._db.query(
+            "SELECT count(*)::int AS n FROM {table} WHERE {pending}".format(
+                table=table, pending=pending),
+            args, types).scalar("n")
+
+        return Progress(len(updated), remaining, elapsed)

aflib-0.0.7/src/aflib/events.py

@@ -0,0 +1,176 @@
+"""A minimal outbox: emit one event, deliver it with retries.
+
+    from aflib.events import Outbox
+
+    box = Outbox(
+        plpy,
+        outbox="public.aflib_outbox",
+        delivery="public.aflib_delivery",
+        subscription="public.aflib_sub",
+    )
+    box.emit("matricula.finalizada", {"id_tuition": 321633}, 321633)
+
+    def deliver(subscriber, outbox_id, attempt):
+        functions.call(plpy, subscriber, [outbox_id, attempt], ["bigint", "integer"])
+
+    box.pump(deliver, limit=50)
+
+The columns are the ones the probe created and ran on PRE, 2026-10-01. This module
+does not create the tables.
+
+- `outbox`: `id` bigint, `evento` text, `payload` jsonb, `aggregate_id` bigint
+- `delivery`: `id` bigint, `id_outbox` bigint, `suscriptor` text,
+  `estado` text (`pending`, `done`, `dead`), `attempts` int,
+  `next_attempt_at` timestamptz, `last_error` text
+- `subscription`: `evento` text, `suscriptor` text, `activo` boolean
+
+`emit` inserts the event and one `pending` delivery per active subscriber, in the
+caller's transaction. `pump` is one chunk: the caller invokes it again (`pg_cron`,
+the next request) and each invocation is its own transaction.
+
+A subscriber that raises must not take the others with it. The effect runs inside
+`plpy.subtransaction()`. The attempt counter is written **after** that block, so a
+failure rolls the effect back and still records the attempt. Writing the counter
+inside the savepoint would roll the count back too, and the same delivery would
+retry forever. A SQL `SAVEPOINT` is not the way to get that block:
+`plpy.execute("savepoint s")` fails with `SPI_ERROR_TRANSACTION`.
+
+`deliver` is called as `deliver(subscriber, outbox_id, attempt)`. The first attempt
+is 1. A raise is a failed attempt. After `max_attempts` (3 on the run) the row
+becomes `dead`. Before that, `next_attempt_at` moves forward by `2**attempt`
+seconds, which is the backoff the probe wrote. `last_error` keeps the first 200
+characters of the exception text.
+
+Table names are caller-written SQL identifiers, quoted after a check. Event names,
+payloads, ids and error text are bound.
+"""
+
+import re
+
+from aflib.codec import dumps
+from aflib.db import Db
+
+
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_ERROR_LIMIT = 200
+
+
+def _quote_table(name):
+    """`"Schema"."table"` or `"table"`. Anything else is refused.
+
+    The name is interpolated, because an identifier cannot be a bound parameter.
+    Checking it first is what keeps a payload or an error string from being able
+    to ride along in that position.
+    """
+    parts = name.split(".")
+    if not 1 <= len(parts) <= 2 or not all(_IDENT.match(part) for part in parts):
+        raise ValueError(
+            "table name must be an identifier or schema.identifier, got {!r}".format(name)
+        )
+    return ".".join('"{}"'.format(part) for part in parts)
+
+
+class Outbox(object):
+    """`emit` and `pump` against one trio of tables. `plpy` is injected."""
+
+    def __init__(self, plpy, outbox, delivery, subscription):
+        self._plpy = plpy
+        self._db = Db(plpy)
+        self._outbox = _quote_table(outbox)
+        self._delivery = _quote_table(delivery)
+        self._subscription = _quote_table(subscription)
+
+    def emit(self, event, payload, aggregate_id):
+        """One outbox row, plus a pending delivery for each active subscriber.
+
+        Returns `{"outbox": id, "deliveries": n}`. `payload` is encoded with
+        `codec.dumps` and bound as `jsonb`. `aggregate_id` is a bigint, the column
+        the probe declared.
+        """
+        if isinstance(aggregate_id, bool) or not isinstance(aggregate_id, int):
+            raise ValueError("aggregate_id must be an int, got {!r}".format(aggregate_id))
+
+        created = self._db.query(
+            "INSERT INTO {} (evento, payload, aggregate_id) "
+            "VALUES ($1, $2, $3) RETURNING id".format(self._outbox),
+            [event, dumps(payload), aggregate_id],
+            ["text", "jsonb", "bigint"],
+        ).one()
+        deliveries = self._db.query(
+            "INSERT INTO {} (id_outbox, suscriptor) "
+            "SELECT $1, suscriptor FROM {} "
+            "WHERE evento = $2 AND activo "
+            "RETURNING id".format(self._delivery, self._subscription),
+            [created["id"], event],
+            ["bigint", "text"],
+        ).rows()
+        return {"outbox": created["id"], "deliveries": len(deliveries)}
+
+    def pump(self, deliver, limit, max_attempts=3):
+        """Deliver up to `limit` due rows. One subscriber's failure stops at that row.
+
+        Returns `{"seen", "delivered", "retrying", "dead_letter"}`. `limit` is at
+        least 1. `max_attempts` defaults to 3, the count the probe dead-lettered on.
+        """
+        limit = int(limit)
+        max_attempts = int(max_attempts)
+        if limit < 1:
+            raise ValueError("limit must be at least 1, got {}".format(limit))
+        if max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1, got {}".format(max_attempts))
+
+        due = self._db.query(
+            "SELECT id, id_outbox, suscriptor, attempts FROM {} "
+            "WHERE estado = 'pending' AND next_attempt_at <= now() "
+            "ORDER BY id LIMIT $1".format(self._delivery),
+            [limit],
+            ["integer"],
+        ).rows()
+
+        delivered = retrying = dead = 0
+        for row in due:
+            attempt = row["attempts"] + 1
+            try:
+                with self._plpy.subtransaction():
+                    deliver(row["suscriptor"], row["id_outbox"], attempt)
+                self._mark_done(row["id"], attempt)
+                delivered += 1
+            except Exception as exc:
+                message = str(exc)[:_ERROR_LIMIT]
+                if attempt >= max_attempts:
+                    self._mark_dead(row["id"], attempt, message)
+                    dead += 1
+                else:
+                    self._mark_retry(row["id"], attempt, message)
+                    retrying += 1
+        return {
+            "seen": len(due),
+            "delivered": delivered,
+            "retrying": retrying,
+            "dead_letter": dead,
+        }
+
+    def _mark_done(self, delivery_id, attempt):
+        self._db.query(
+            "UPDATE {} SET estado = 'done', attempts = $1, last_error = NULL "
+            "WHERE id = $2".format(self._delivery),
+            [attempt, delivery_id],
+            ["integer", "bigint"],
+        )
+
+    def _mark_dead(self, delivery_id, attempt, message):
+        self._db.query(
+            "UPDATE {} SET estado = 'dead', attempts = $1, last_error = $2 "
+            "WHERE id = $3".format(self._delivery),
+            [attempt, message, delivery_id],
+            ["integer", "text", "bigint"],
+        )
+
+    def _mark_retry(self, delivery_id, attempt, message):
+        self._db.query(
+            "UPDATE {} SET attempts = $1, last_error = $2, "
+            "next_attempt_at = now() + (interval '1 second' * $3) "
+            "WHERE id = $4".format(self._delivery),
+            [attempt, message, 2**attempt, delivery_id],
+            ["integer", "text", "integer", "bigint"],
+        )

aflib-0.0.7/src/aflib/workflow.py

@@ -0,0 +1,161 @@
+"""Start a workflow instance and see whether it is moving.
+
+    from aflib import workflow
+
+    started = workflow.start(plpy, "WFP_cadena", "case-58", {
+        "wf_probe_p1.p_entrada": ("STRING", "desde-aflib"),
+        "saltar": ("BOOLEAN", False),
+    })
+    state = workflow.status(plpy, "case-58")
+    wedged = workflow.stuck(plpy, "1 hour")
+
+`start` inserts one row into `Workflows.ProcessInstance` and one `Variable` row per
+entry, in the caller's transaction. The engine picks the instance up on its own poll
+and runs it outside that transaction. Observed on PRE, 2026-10-01: an insert with
+status `PENDING` was `IN_PROGRESS` within seconds and `FINISHED` without this
+function doing anything further.
+
+Three things about that insert are easy to get wrong, and all three were paid for
+on that run:
+
+- The engine reads a function argument from a variable named `<function>.<parameter>`.
+  This module stores the name it is given. `saltar` is a real name from that run: a
+  transition condition reads whatever name is written on it, prefix or none.
+- A function that needs its own instance id has to receive it as one of these
+  variables. The engine does not pass the id.
+- An activity with one outgoing transition that has no condition takes that
+  transition and leaves the conditional ones `PENDING` forever. An instance that
+  cannot move stays `PENDING` or `IN_PROGRESS`, with no error and no timeout.
+  `stuck` exists to list those.
+
+Values are bound. The only SQL literals are the enum labels the probe inserted
+(`PENDING`, `STRING`, `INTEGER`, `BOOLEAN`), which a bound `text` parameter does
+not cast to the engine's enum.
+"""
+
+from aflib.db import Db
+
+
+# Column and bind type for the three variable kinds the probe body wrote.
+# LONG, DOUBLE and DATE exist on the engine and were not in that body.
+_VALUE = {
+    "STRING": ("valueString", "text"),
+    "INTEGER": ("valueNumber", "integer"),
+    "BOOLEAN": ("valueBoolean", "boolean"),
+}
+
+_PROCESS = 'SELECT id FROM "Workflows"."Process" WHERE name = $1'
+
+_INSTANCE = (
+    'INSERT INTO "Workflows"."ProcessInstance" '
+    '(process, "businessKey", "creationDate", status) '
+    "VALUES ($1, $2, now(), 'PENDING') "
+    "RETURNING id"
+)
+
+_STATUS = (
+    "SELECT pi.id, pi.status::text AS status, "
+    '(SELECT a.name FROM "Workflows"."ActivityInstance" ai '
+    '   JOIN "Workflows"."Activity" a ON a.id = ai.activity '
+    '  WHERE ai."processInstance" = pi.id '
+    "    AND ai.status::text = 'IN_PROGRESS' "
+    "  LIMIT 1) AS current, "
+    '(SELECT ai.result FROM "Workflows"."ActivityInstance" ai '
+    '  WHERE ai."processInstance" = pi.id '
+    "    AND ai.status::text = 'ERROR' "
+    "  LIMIT 1) AS last_error "
+    'FROM "Workflows"."ProcessInstance" pi '
+    'WHERE pi."businessKey" = $1 '
+    "ORDER BY pi.id DESC "
+    "LIMIT 1"
+)
+
+_STUCK = (
+    "SELECT pi.id, pi.\"businessKey\" AS business_key, pi.status::text AS status, "
+    'round(extract(epoch FROM (now() - pi."creationDate")))::int AS seconds, '
+    '(SELECT a.name FROM "Workflows"."ActivityInstance" ai '
+    '   JOIN "Workflows"."Activity" a ON a.id = ai.activity '
+    '  WHERE ai."processInstance" = pi.id '
+    "    AND ai.status::text = 'IN_PROGRESS' "
+    "  LIMIT 1) AS stuck_at "
+    'FROM "Workflows"."ProcessInstance" pi '
+    "WHERE pi.status::text IN ('IN_PROGRESS', 'PENDING') "
+    '  AND pi."creationDate" < now() - $1::interval '
+    "ORDER BY pi.id"
+)
+
+
+def _checked(variables):
+    """Every variable is well-formed before the first insert.
+
+    A bad type raised halfway through the probe's loop. A body that catches the
+    exception and returns a failure envelope would then commit the instance with
+    only some of its variables, because a returned failure does not roll back.
+    Checking first means a bad call writes nothing.
+    """
+    if variables is None:
+        return []
+    if not isinstance(variables, dict):
+        raise ValueError("variables must be a dict of name to (type, value)")
+    checked = []
+    for name, spec in variables.items():
+        if not isinstance(spec, tuple) or len(spec) != 2:
+            raise ValueError("variable {!r} must be (type, value)".format(name))
+        kind, value = spec
+        if kind not in _VALUE:
+            raise ValueError(
+                "variable {!r} has type {!r}; this module writes STRING, INTEGER "
+                "and BOOLEAN".format(name, kind)
+            )
+        checked.append((name, kind, value))
+    return checked
+
+
+def start(plpy, process, business_key, variables=None):
+    """Insert a `PENDING` instance and its variables. Return its id.
+
+    `variables` maps a name to `(type, value)`. `type` is `STRING`, `INTEGER` or
+    `BOOLEAN`. Returns `{"instance": id, "variables": n}`. Raises `ValueError` when
+    `process` is not a row in `Workflows.Process`, and writes nothing in that case.
+    """
+    checked = _checked(variables)
+    db = Db(plpy)
+    found = db.query(_PROCESS, [process], ["text"]).one()
+    if found is None:
+        raise ValueError("no workflow process named {!r}".format(process))
+
+    created = db.query(
+        _INSTANCE, [found["id"], business_key], ["integer", "text"]
+    ).one()
+    instance_id = created["id"]
+    for name, kind, value in checked:
+        column, argtype = _VALUE[kind]
+        db.query(
+            'INSERT INTO "Workflows"."Variable" '
+            '(name, "processInstance", type, "{}") '
+            "VALUES ($1, $2, '{}', $3)".format(column, kind),
+            [name, instance_id, value],
+            ["text", "integer", argtype],
+        )
+    return {"instance": instance_id, "variables": len(checked)}
+
+
+def status(plpy, business_key):
+    """The newest instance with this business key, or `None`.
+
+    Keys are `id`, `status`, `current` (the activity `IN_PROGRESS`, or `None`) and
+    `last_error` (the `result` of an `ERROR` activity, or `None`). Several instances
+    may share a key; the highest id is the one a later start created.
+    """
+    return Db(plpy).query(_STATUS, [business_key], ["text"]).one()
+
+
+def stuck(plpy, older_than):
+    """Live instances older than `older_than`, a Postgres interval string.
+
+    `"1 hour"` is the value the probe passed. The result rows have `id`,
+    `business_key`, `status`, `seconds` and `stuck_at`.
+    """
+    if not isinstance(older_than, str) or not older_than:
+        raise ValueError("older_than must be an interval string, such as '1 hour'")
+    return Db(plpy).query(_STUCK, [older_than], ["text"]).rows()

{aflib-0.0.6 → aflib-0.0.7}/tests/conftest.py

@@ -70,9 +70,15 @@ class FakePlpy:
 
     Error = FakeError
 
-    def __init__(self, rows=None, colnames=None):
+    def __init__(self, rows=None, colnames=None, results=None):
         self.rows = rows if rows is not None else []
         self.colnames = colnames
+        # A queue of result sets, consumed one per execute(), for the callers that run
+        # more than one statement. `batch.run` is the first: an UPDATE … RETURNING and a
+        # count, which cannot both be the same canned rows because `scalar` refuses more
+        # than one row. When the queue is empty or absent, every execute() gets `rows`,
+        # which is what every earlier test relies on.
+        self.results = list(results) if results is not None else None
         self.executed = []
         self.prepared = []
         # Every sink is recorded SEPARATELY, because which one a line went to is the
@@ -132,6 +138,9 @@ class FakePlpy:
     def execute(self, sql_or_plan, args=None):
         self.executed.append((sql_or_plan, args))
         self.events.append("execute")
+        if self.results:
+            rows, colnames = self.results.pop(0)
+            return FakeResult(rows, colnames)
         return FakeResult(self.rows, self.colnames)
 
 
@@ -166,7 +175,7 @@ def make_plpy():
     from conftest directly does not work — `tests/` is not a package.
     """
 
-    def _make(rows=None, colnames=None):
-        return FakePlpy(rows=rows, colnames=colnames)
+    def _make(rows=None, colnames=None, results=None):
+        return FakePlpy(rows=rows, colnames=colnames, results=results)
 
     return _make

aflib-0.0.7/tests/test_batch.py

@@ -0,0 +1,145 @@
+"""What `batch` must do, and the one mistake it exists to prevent.
+
+Grounded in a production run on 2026-10-01: 16.207 receipts moved from `Planned` to
+`Pending` in 15 chunks of 1.000, at ~19 s per chunk against a 180 s `statement_timeout`.
+The second chunk of the first attempt **aborted**, because the predicate was only in the
+subquery and a user cancelled a receipt mid-batch: the update reached the re-read row and
+the trigger refused `Cancelled → Pending`. Repeating the predicate in the outer `WHERE`
+fixed it and the remaining 15 chunks ran clean.
+
+So the load-bearing assertion here is about the **shape of the SQL**, not about rows. The
+`plpy` double cannot prove the concurrency behaviour — only a real database can, and it
+did — but it can prove the predicate is placed twice, which is what makes the behaviour
+reachable.
+
+Probe: `ec-airflows` `Master.aflib_probe_batch`, case `carrera`: a competitor cancels three
+rows the chunk believes pending, and `canceladas_pisadas` comes back 0.
+"""
+
+import pytest
+
+from aflib.batch import Batch, Progress
+
+PENDING = "id_status = $1"
+TABLE = '"Economic"."Receipt"'
+SET = "id_status = $2"
+
+
+def _sql(entry):
+    """The SQL of one recorded execute.
+
+    With `types`, `Db` goes through `plpy.prepare`, so what the double recorded is the
+    plan tuple `("PLAN", sql, argtypes)` rather than the string. Reaching through it here
+    keeps the assertions about the statement, and incidentally proves the values really are
+    bound: an interpolating implementation would never reach `prepare` at all.
+    """
+    target = entry[0]
+    return target[1] if isinstance(target, tuple) else target
+
+
+def _plpy(make_plpy, updated, remaining):
+    """Two result sets: the UPDATE … RETURNING, then the count."""
+    return make_plpy(results=[
+        ([{"id": n} for n in range(updated)], ["id"]),
+        ([{"n": remaining}], ["n"]),
+    ])
+
+
+class TestThePredicateIsPlacedTwice:
+    """The whole point. A single placement is the bug that aborted a production run."""
+
+    def test_predicate_appears_in_the_outer_where_and_in_the_subquery(self, make_plpy):
+        fake = _plpy(make_plpy, 2, 8)
+        Batch(fake).run(TABLE, SET, PENDING, args=[1, 2], types=["integer"] * 2, limit=10)
+
+        sql = _sql(fake.executed[0])
+        assert sql.count(PENDING) == 2, (
+            "the predicate must guard the update AND select the ids; one placement lets "
+            "Postgres re-read a changed row and update it anyway (observed in production)"
+        )
+
+    def test_the_outer_placement_guards_the_updated_row(self, make_plpy):
+        fake = _plpy(make_plpy, 1, 0)
+        Batch(fake).run(TABLE, SET, PENDING, args=[1, 2], types=["integer"] * 2)
+
+        sql = _sql(fake.executed[0])
+        where = sql.split("SET")[1].split("AND")[0]
+        assert PENDING in where, "the first predicate must sit in the UPDATE's own WHERE"
+
+    def test_a_qualified_predicate_is_refused_rather_than_misplaced(self, make_plpy):
+        # It would resolve in the outer WHERE and break inside the subquery, so the
+        # helper must not accept it and quietly produce a statement that fails at runtime.
+        with pytest.raises(ValueError) as exc:
+            Batch(make_plpy()).run(TABLE, SET, "_t.id_status = $1")
+        assert "unqualified" in str(exc.value)
+
+
+class TestChunkBoundaries:
+    def test_limit_bounds_the_subquery_not_the_update(self, make_plpy):
+        fake = _plpy(make_plpy, 5, 0)
+        Batch(fake).run(TABLE, SET, PENDING, args=[1, 2], types=["integer"] * 2, limit=5)
+
+        sql = _sql(fake.executed[0])
+        assert "LIMIT 5" in sql
+        assert sql.index("LIMIT 5") > sql.index("SELECT"), "the LIMIT belongs to the subquery"
+
+    def test_ordering_defaults_to_the_key_so_chunks_are_disjoint(self, make_plpy):
+        fake = _plpy(make_plpy, 1, 0)
+        Batch(fake).run(TABLE, SET, PENDING, args=[1, 2], types=["integer"] * 2, key="id")
+        assert "ORDER BY id" in _sql(fake.executed[0])
+
+    def test_limit_is_coerced_so_it_cannot_carry_sql(self, make_plpy):
+        fake = _plpy(make_plpy, 0, 0)
+        Batch(fake).run(TABLE, SET, PENDING, args=[1, 2], types=["integer"] * 2, limit="10")
+        assert "LIMIT 10" in _sql(fake.executed[0])
+
+
+class TestProgress:
+    def test_done_is_what_the_update_returned(self, make_plpy):
+        p = Batch(_plpy(make_plpy, 7, 3)).run(TABLE, SET, PENDING, args=[1, 2],
+                                              types=["integer"] * 2)
+        assert p.done == 7
+
+    def test_remaining_is_counted_after_the_update(self, make_plpy):
+        # Counted in the same transaction, so it already excludes this chunk. A caller
+        # looping until `complete` therefore terminates without subtracting anything.
+        p = Batch(_plpy(make_plpy, 7, 3)).run(TABLE, SET, PENDING, args=[1, 2],
+                                              types=["integer"] * 2)
+        assert p.remaining == 3
+        assert p.complete is False
+
+    def test_complete_when_nothing_is_left(self, make_plpy):
+        p = Batch(_plpy(make_plpy, 2, 0)).run(TABLE, SET, PENDING, args=[1, 2],
+                                              types=["integer"] * 2)
+        assert p.complete is True
+
+    def test_reports_its_own_duration_because_chunk_size_is_measured(self, make_plpy):
+        # Cost per row is not guessable: the same 1.000-row chunk took 19 s on
+        # Economic.Receipt and 0.07 ms per row on a bare table. The caller needs the
+        # number to size the next chunk against the environment's statement_timeout.
+        p = Batch(_plpy(make_plpy, 1, 0)).run(TABLE, SET, PENDING, args=[1, 2],
+                                              types=["integer"] * 2)
+        assert p.seconds >= 0
+        assert "seconds" in p.as_dict()
+
+    def test_as_dict_is_serialisable_for_a_result_envelope(self, make_plpy):
+        d = Batch(_plpy(make_plpy, 4, 1)).run(TABLE, SET, PENDING, args=[1, 2],
+                                              types=["integer"] * 2).as_dict()
+        assert d == {"done": 4, "remaining": 1, "seconds": d["seconds"], "complete": False}
+
+
+class TestBindings:
+    def test_values_are_bound_not_interpolated(self, make_plpy):
+        fake = _plpy(make_plpy, 1, 0)
+        Batch(fake).run(TABLE, SET, PENDING, args=[29, 49], types=["integer", "integer"])
+        for entry in fake.executed:
+            sql = _sql(entry)
+            assert "29" not in sql and "49" not in sql, "values belong in args, not in the SQL"
+            assert entry[1] is not None
+
+    def test_the_count_query_gets_the_same_bindings(self, make_plpy):
+        # The predicate is the same text, so it needs the same parameters — a count that
+        # dropped them would fail with "there is no parameter $1".
+        fake = _plpy(make_plpy, 1, 0)
+        Batch(fake).run(TABLE, SET, PENDING, args=[29, 49], types=["integer", "integer"])
+        assert fake.executed[0][1] == fake.executed[1][1]

aflib-0.0.7/tests/test_events.py

@@ -0,0 +1,184 @@
+"""events.emit / pump, as the PRE probe ran them.
+
+Probe: `Master.aflib_probe_events`, marker `aflib-events-r3`. One subscriber
+delivered on attempt 1, one failed twice and delivered on attempt 3, one
+dead-lettered at attempt 3, and each effect landed once. The first body failed
+before that: `plpy.execute("savepoint s")` raised `SPI_ERROR_TRANSACTION`.
+"""
+
+import pytest
+
+from aflib.codec import dumps
+from aflib.events import Outbox
+
+
+OUTBOX = "public.aflib_outbox"
+DELIVERY = "public.aflib_delivery"
+SUBSCRIPTION = "public.aflib_sub"
+
+
+def _box(fake):
+    return Outbox(fake, OUTBOX, DELIVERY, SUBSCRIPTION)
+
+
+def _sql(entry):
+    target = entry[0]
+    return target[1] if isinstance(target, tuple) else target
+
+
+def _args(entry):
+    return entry[1]
+
+
+class TestEmit:
+    def test_inserts_the_event_and_one_delivery_per_active_subscriber(self, make_plpy):
+        fake = make_plpy(results=[
+            ([{"id": 1}], ["id"]),
+            ([{"id": 10}, {"id": 11}, {"id": 12}], ["id"]),
+        ])
+        out = _box(fake).emit("matricula.finalizada", {"id_tuition": 321633}, 321633)
+
+        assert out == {"outbox": 1, "deliveries": 3}
+        event_sql, delivery_sql = (_sql(e) for e in fake.executed)
+        assert '"public"."aflib_outbox"' in event_sql
+        assert '"public"."aflib_delivery"' in delivery_sql
+        assert '"public"."aflib_sub"' in delivery_sql
+        assert "activo" in delivery_sql
+        assert _args(fake.executed[0]) == [
+            "matricula.finalizada", dumps({"id_tuition": 321633}), 321633,
+        ]
+        assert fake.prepared[0][2] == ("text", "jsonb", "bigint")
+        assert _args(fake.executed[1]) == [1, "matricula.finalizada"]
+
+    def test_a_quote_in_the_event_name_is_bound(self, make_plpy):
+        fake = make_plpy(results=[
+            ([{"id": 1}], ["id"]),
+            ([], ["id"]),
+        ])
+        _box(fake).emit("it's", {"a": 1}, 1)
+        for entry in fake.executed:
+            assert "it's" not in _sql(entry)
+
+    def test_aggregate_id_must_be_an_int(self, make_plpy):
+        fake = make_plpy()
+        with pytest.raises(ValueError, match="aggregate_id"):
+            _box(fake).emit("e", {}, True)
+        assert fake.executed == []
+
+    def test_a_table_name_that_is_not_an_identifier_is_refused(self, make_plpy):
+        with pytest.raises(ValueError, match="identifier"):
+            Outbox(make_plpy(), "public.aflib_outbox", "bad name", "public.aflib_sub")
+
+
+class TestPump:
+    def _due(self, make_plpy, rows):
+        return make_plpy(results=[(rows, ["id", "id_outbox", "suscriptor", "attempts"])])
+
+    def test_a_success_commits_the_effect_then_marks_done(self, make_plpy):
+        fake = self._due(make_plpy, [
+            {"id": 10, "id_outbox": 1, "suscriptor": "bien", "attempts": 0},
+        ])
+        seen = []
+
+        def deliver(subscriber, outbox_id, attempt):
+            seen.append((subscriber, outbox_id, attempt))
+
+        out = _box(fake).pump(deliver, limit=50)
+
+        assert out == {"seen": 1, "delivered": 1, "retrying": 0, "dead_letter": 0}
+        assert seen == [("bien", 1, 1)]
+        assert fake.events == ["execute", "subtx_enter", "subtx_exit_commit", "execute"]
+        update = _sql(fake.executed[1])
+        assert "estado = 'done'" in update
+        assert _args(fake.executed[1]) == [1, 10]
+
+    def test_a_failure_rolls_back_and_still_records_the_attempt(self, make_plpy):
+        fake = self._due(make_plpy, [
+            {"id": 10, "id_outbox": 1, "suscriptor": "falla", "attempts": 0},
+            {"id": 11, "id_outbox": 1, "suscriptor": "bien", "attempts": 0},
+        ])
+        called = []
+
+        def deliver(subscriber, outbox_id, attempt):
+            called.append(subscriber)
+            if subscriber == "falla":
+                raise RuntimeError("it's broken")
+
+        out = _box(fake).pump(deliver, limit=50)
+
+        assert called == ["falla", "bien"]
+        assert out["delivered"] == 1
+        assert out["retrying"] == 1
+        assert fake.events[1:4] == ["subtx_enter", "subtx_exit_rollback", "execute"]
+        retry = _sql(fake.executed[1])
+        assert "interval '1 second'" in retry
+        assert "it's broken" not in retry
+        # attempt 1 waits 2**1 seconds. The message is bound, quotes included.
+        assert _args(fake.executed[1]) == [1, "it's broken", 2, 10]
+
+    def test_the_third_failure_dead_letters_without_a_backoff(self, make_plpy):
+        fake = self._due(make_plpy, [
+            {"id": 12, "id_outbox": 1, "suscriptor": "siempre_falla", "attempts": 2},
+        ])
+
+        def deliver(subscriber, outbox_id, attempt):
+            raise RuntimeError("fallo permanente")
+
+        out = _box(fake).pump(deliver, limit=50)
+
+        assert out["dead_letter"] == 1
+        assert out["retrying"] == 0
+        update = _sql(fake.executed[1])
+        assert "estado = 'dead'" in update
+        assert "interval" not in update
+        assert _args(fake.executed[1]) == [3, "fallo permanente", 12]
+
+    def test_the_second_failure_waits_four_seconds(self, make_plpy):
+        fake = self._due(make_plpy, [
+            {"id": 11, "id_outbox": 1, "suscriptor": "falla_dos_veces", "attempts": 1},
+        ])
+
+        def deliver(subscriber, outbox_id, attempt):
+            raise RuntimeError("transitorio")
+
+        _box(fake).pump(deliver, limit=50)
+        assert _args(fake.executed[1])[2] == 4
+
+    def test_plpy_error_is_a_failed_attempt_not_an_escaping_exception(self, make_plpy):
+        fake = self._due(make_plpy, [
+            {"id": 10, "id_outbox": 1, "suscriptor": "siempre_falla", "attempts": 0},
+        ])
+
+        def deliver(subscriber, outbox_id, attempt):
+            fake.error("fallo permanente")
+
+        out = _box(fake).pump(deliver, limit=50)
+        assert out["retrying"] == 1
+        assert _args(fake.executed[1])[1] == "fallo permanente"
+
+    def test_last_error_keeps_the_first_200_characters(self, make_plpy):
+        fake = self._due(make_plpy, [
+            {"id": 10, "id_outbox": 1, "suscriptor": "falla", "attempts": 0},
+        ])
+        text = "x" * 250
+
+        def deliver(subscriber, outbox_id, attempt):
+            raise RuntimeError(text)
+
+        _box(fake).pump(deliver, limit=50)
+        assert _args(fake.executed[1])[1] == "x" * 200
+
+    def test_limit_is_bound(self, make_plpy):
+        fake = self._due(make_plpy, [])
+        out = _box(fake).pump(lambda *a: None, limit=50)
+        assert out == {"seen": 0, "delivered": 0, "retrying": 0, "dead_letter": 0}
+        assert "LIMIT $1" in _sql(fake.executed[0])
+        assert _args(fake.executed[0]) == [50]
+        assert "savepoint" not in _sql(fake.executed[0]).lower()
+
+    def test_due_rows_are_the_pending_ones_whose_time_has_come(self, make_plpy):
+        fake = self._due(make_plpy, [])
+        _box(fake).pump(lambda *a: None, limit=1)
+        sql = _sql(fake.executed[0])
+        assert "estado = 'pending'" in sql
+        assert "next_attempt_at <= now()" in sql

{aflib-0.0.6 → aflib-0.0.7}/tests/test_public_api.py

@@ -73,6 +73,18 @@ def test_exports_trigger_functions_and_identity():
     assert "trigger" in aflib.__all__
 
 
+def test_exports_workflow_and_events():
+    from aflib import events, workflow
+
+    assert workflow.start is not None
+    assert workflow.status is not None
+    assert workflow.stuck is not None
+    assert events.Outbox is aflib.Outbox
+    assert "workflow" in aflib.__all__
+    assert "events" in aflib.__all__
+    assert "Outbox" in aflib.__all__
+
+
 def test_exports_bad_parameter_directly():
     # A body catches this by name. Re-exported so `from aflib import BadParameter` works
     # without knowing which module defines it — it moves to an `errors` module in slice 2,

aflib-0.0.7/tests/test_workflow.py

@@ -0,0 +1,133 @@
+"""workflow.start / status / stuck, as the PRE probe ran them.
+
+Probe: `Master.aflib_probe_wf`, marker `aflib-wf-r1`. It started instance 58 of
+`WFP_cadena`, followed it to FINISHED, and `stuck` returned an empty list. The
+variable rows on that call were three STRING values and one BOOLEAN.
+"""
+
+import pytest
+
+from aflib.workflow import start, status, stuck
+
+
+def _sql(entry):
+    target = entry[0]
+    return target[1] if isinstance(target, tuple) else target
+
+
+def _args(entry):
+    return entry[1]
+
+
+class TestStart:
+    def test_inserts_a_pending_instance_and_its_variables(self, make_plpy):
+        fake = make_plpy(results=[
+            ([{"id": 6}], ["id"]),
+            ([{"id": 58}], ["id"]),
+        ])
+        out = start(fake, "WFP_cadena", "case-58", {
+            "wf_probe_p1.p_entrada": ("STRING", "desde-aflib"),
+            "saltar": ("BOOLEAN", False),
+        })
+
+        assert out == {"instance": 58, "variables": 2}
+        process, instance, first, second = (_sql(e) for e in fake.executed)
+        assert '"Workflows"."Process"' in process
+        assert "PENDING" in instance
+        assert '"businessKey"' in instance
+        assert "valueString" in first
+        assert "'STRING'" in first
+        assert "valueBoolean" in second
+        assert "'BOOLEAN'" in second
+
+    def test_values_are_bound_and_a_boolean_stays_a_boolean(self, make_plpy):
+        fake = make_plpy(results=[
+            ([{"id": 6}], ["id"]),
+            ([{"id": 58}], ["id"]),
+        ])
+        start(fake, "WFP_cadena", "o'hara", {
+            "wf_probe_p1.p_entrada": ("STRING", "desde-aflib"),
+            "saltar": ("BOOLEAN", False),
+        })
+
+        assert _args(fake.executed[0]) == ["WFP_cadena"]
+        assert _args(fake.executed[1]) == [6, "o'hara"]
+        assert _args(fake.executed[3]) == ["saltar", 58, False]
+        assert fake.prepared[3][2][-1] == "boolean"
+        for entry in fake.executed:
+            assert "o'hara" not in _sql(entry)
+            assert "desde-aflib" not in _sql(entry)
+
+    def test_an_integer_variable_uses_the_number_column(self, make_plpy):
+        fake = make_plpy(results=[
+            ([{"id": 6}], ["id"]),
+            ([{"id": 58}], ["id"]),
+        ])
+        start(fake, "WFP_cadena", "case-58", {"paso": ("INTEGER", 3)})
+
+        sql = _sql(fake.executed[2])
+        assert "valueNumber" in sql
+        assert "'INTEGER'" in sql
+        assert _args(fake.executed[2]) == ["paso", 58, 3]
+        assert fake.prepared[2][2][-1] == "integer"
+
+    def test_a_missing_process_writes_nothing_else(self, make_plpy):
+        fake = make_plpy(results=[([], ["id"])])
+        with pytest.raises(ValueError, match="no workflow process"):
+            start(fake, "missing", "case-58", {"saltar": ("BOOLEAN", False)})
+        assert len(fake.executed) == 1
+
+    def test_a_bad_type_is_refused_before_any_insert(self, make_plpy):
+        fake = make_plpy()
+        with pytest.raises(ValueError, match="STRING, INTEGER"):
+            start(fake, "WFP_cadena", "case-58", {"cuando": ("DATE", "2026-10-01")})
+        assert fake.executed == []
+
+    def test_no_variables_still_inserts_the_instance(self, make_plpy):
+        fake = make_plpy(results=[
+            ([{"id": 6}], ["id"]),
+            ([{"id": 9}], ["id"]),
+        ])
+        assert start(fake, "WFP_cadena", "case-9") == {"instance": 9, "variables": 0}
+        assert len(fake.executed) == 2
+
+
+class TestStatus:
+    def test_returns_the_row_the_query_names(self, make_plpy):
+        row = {"id": 58, "status": "FINISHED", "current": None, "last_error": None}
+        fake = make_plpy(results=[([row], list(row))])
+        assert status(fake, "case-58") == row
+
+    def test_none_when_the_key_has_no_instance(self, make_plpy):
+        fake = make_plpy(results=[([], ["id", "status", "current", "last_error"])])
+        assert status(fake, "missing") is None
+
+    def test_the_newest_instance_wins_when_a_key_is_reused(self, make_plpy):
+        fake = make_plpy(results=[([], ["id", "status", "current", "last_error"])])
+        status(fake, "case-58")
+        sql = _sql(fake.executed[0])
+        assert "ORDER BY pi.id DESC" in sql
+        assert "LIMIT 1" in sql
+        assert _args(fake.executed[0]) == ["case-58"]
+
+
+class TestStuck:
+    def test_selects_live_instances_older_than_a_bound_interval(self, make_plpy):
+        row = {
+            "id": 7, "business_key": "left-behind", "status": "IN_PROGRESS",
+            "seconds": 7200, "stuck_at": "Generate Class",
+        }
+        fake = make_plpy(results=[([row], list(row))])
+        assert stuck(fake, "1 hour") == [row]
+
+        sql = _sql(fake.executed[0])
+        assert "'IN_PROGRESS'" in sql and "'PENDING'" in sql
+        assert "$1::interval" in sql
+        assert "1 hour" not in sql
+        assert _args(fake.executed[0]) == ["1 hour"]
+
+    def test_an_empty_interval_is_refused(self, make_plpy):
+        fake = make_plpy()
+        with pytest.raises(ValueError, match="interval"):
+            stuck(fake, "")
+        assert fake.executed == []