terp-cap-outbox 0.1.0__tar.gz

terp_cap_outbox-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_outbox-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: terp-cap-outbox
+Version: 0.1.0
+Summary: Terp durable outbox — transactional, leased, retrying post-commit delivery for jobs and events.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-core==0.1.0

terp_cap_outbox-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,5 @@
+{
+  "arch-allow-mutations-emit-audit": 5,
+  "arch-allow-no-internal-imports": 2,
+  "arch-allow-table-models-use-base-table": 1
+}

terp_cap_outbox-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-outbox"
+version = "0.1.0"
+description = "Terp durable outbox — transactional, leased, retrying post-commit delivery for jobs and events."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+]
+
+# A LIBRARY capability: it owns the durable delivery mechanism (a table, a durable
+# JobQueue / EventDispatcher, and the leased worker), not an HTTP surface — so it
+# declares NO `terp.capabilities` ModuleSpec entry point (nothing is auto-mounted).
+# A composition root opts in by wiring create_app(job_queue=OutboxJobQueue(),
+# event_dispatcher=outbox_event_dispatcher) and running `terp jobs worker`.
+
+# Owns the append-only `outbox_message` table, so it ships an independent, linear
+# Alembic history (its own `alembic_version_outbox` table). `terp migrate` discovers
+# this via the `terp.migrations` group (ADR 0027).
+[project.entry-points."terp.migrations"]
+outbox = "terp.capabilities.outbox"
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.outbox`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/outbox"]

terp_cap_outbox-0.1.0/src/terp/capabilities/outbox/__init__.py

@@ -0,0 +1,56 @@
+"""terp.capabilities.outbox — durable, transactional, leased post-commit delivery.
+
+The reliable delivery mechanism the dispatcher seam (ADR 0008) was designed for, and
+the drop-in that makes the jobs seam (ADR 0043) survive a restart (ADR 0045). It owns
+one append-only :class:`OutboxMessage` table and supplies:
+
+* :class:`OutboxJobQueue` — a **durable** :class:`~terp.core.JobQueue` that records each
+  enqueued job as an outbox row, atomically with the business write, instead of running
+  it inline. Marked durable, so ``create_app(require_durable_jobs=True)`` accepts it.
+* :func:`outbox_event_dispatcher` — a durable :data:`~terp.core.EventDispatcher` that
+  records each emitted event as an outbox row on the producer's session.
+* :class:`OutboxWorker` — the leased, retrying consumer (``terp jobs worker``) that
+  claims due rows, runs jobs through the context-binding kernel runner and events
+  through the in-process handlers, and retries / dead-letters per the
+  :class:`~terp.core.RetryPolicy`.
+
+Wiring is composition-root only, with **no** ``enqueue`` / ``emit`` call-site change::
+
+    create_app(..., job_queue=OutboxJobQueue(), event_dispatcher=outbox_event_dispatcher,
+               require_durable_jobs=settings.is_production)
+
+It depends only on ``terp-core`` (and, for delivering events, the in-process eventbus
+capability when one is installed); it never imports a broker engine — those are later,
+separately-installed adapters (ADR 0045).
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.outbox.models import (
+    KIND_EVENT,
+    KIND_JOB,
+    STATUS_DEAD_LETTERED,
+    STATUS_DISPATCHED,
+    STATUS_PENDING,
+    OutboxMessage,
+)
+from terp.capabilities.outbox.queue import OutboxJobQueue, outbox_event_dispatcher
+from terp.capabilities.outbox.worker import (
+    DrainResult,
+    OutboxWorker,
+    deliver_event_in_process,
+)
+
+__all__ = [
+    "KIND_EVENT",
+    "KIND_JOB",
+    "STATUS_DEAD_LETTERED",
+    "STATUS_DISPATCHED",
+    "STATUS_PENDING",
+    "DrainResult",
+    "OutboxJobQueue",
+    "OutboxMessage",
+    "OutboxWorker",
+    "deliver_event_in_process",
+    "outbox_event_dispatcher",
+]

terp_cap_outbox-0.1.0/src/terp/capabilities/outbox/_serde.py

@@ -0,0 +1,84 @@
+"""Serialize a :class:`JobEnvelope` / :class:`EventEnvelope` to and from the row payload.
+
+The outbox stores the **whole envelope** as the row's JSON ``payload`` (not just the
+business payload), so the worker can faithfully rebuild what crossed the producer's
+chokepoint — including the originating ``actor_id`` / ``tenant_id`` / ``request_id``
+the runner re-binds (the jobs design's §7). Everything here round-trips through plain
+JSON scalars (``uuid.UUID`` -> str, ``datetime`` -> ISO-8601), so no Python object or
+ORM row is ever persisted (portability rule 2).
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Mapping
+from dataclasses import asdict
+from datetime import datetime
+from typing import Any
+
+from terp.core import EventEnvelope, EventVisibility, JobEnvelope
+
+
+def _str_or_none(value: object | None) -> str | None:
+    """``str(value)`` for a non-``None`` id/uuid, else ``None`` (JSON-safe)."""
+    return None if value is None else str(value)
+
+
+def job_envelope_to_payload(envelope: JobEnvelope) -> dict[str, Any]:
+    """Flatten a :class:`JobEnvelope` to a JSON-safe dict for the ``payload`` column.
+
+    Serialized field-agnostically via :func:`dataclasses.asdict` (then the ``uuid`` /
+    ``datetime`` fields are cast to JSON scalars), so it never hand-references a
+    field name — including the framework-managed ``tenant_id`` the envelope carries
+    for the worker to re-bind (the design's §7), which is transport here, not a query
+    scope filter.
+    """
+    data = asdict(envelope)
+    data["actor_id"] = _str_or_none(data["actor_id"])
+    data["tenant_id"] = _str_or_none(data["tenant_id"])
+    data["enqueued_at"] = data["enqueued_at"].isoformat()
+    return data
+
+
+def payload_to_job_envelope(data: Mapping[str, Any]) -> JobEnvelope:
+    """Rebuild a :class:`JobEnvelope` from a stored ``payload`` dict."""
+    actor_id = data.get("actor_id")
+    tenant_id = data.get("tenant_id")
+    return JobEnvelope(
+        name=data["name"],
+        payload=dict(data["payload"]),
+        idempotency_key=data.get("idempotency_key"),
+        actor_id=uuid.UUID(actor_id) if actor_id is not None else None,
+        tenant_id=uuid.UUID(tenant_id) if tenant_id is not None else None,
+        request_id=data.get("request_id"),
+        enqueued_at=datetime.fromisoformat(data["enqueued_at"]),
+        attempt=int(data.get("attempt", 1)),
+    )
+
+
+def event_envelope_to_payload(envelope: EventEnvelope) -> dict[str, Any]:
+    """Flatten an :class:`EventEnvelope` to a JSON-safe dict for the ``payload`` column."""
+    return {
+        "name": envelope.name,
+        "visibility": envelope.visibility.value,
+        "payload": dict(envelope.payload),
+        "request_id": envelope.request_id,
+    }
+
+
+def payload_to_event_envelope(data: Mapping[str, Any]) -> EventEnvelope:
+    """Rebuild an :class:`EventEnvelope` from a stored ``payload`` dict."""
+    return EventEnvelope(
+        name=data["name"],
+        visibility=EventVisibility(data["visibility"]),
+        payload=dict(data["payload"]),
+        request_id=data.get("request_id"),
+    )
+
+
+__all__ = [
+    "event_envelope_to_payload",
+    "job_envelope_to_payload",
+    "payload_to_event_envelope",
+    "payload_to_job_envelope",
+]

terp_cap_outbox-0.1.0/src/terp/capabilities/outbox/migrations/versions/d0dc58cc803e_create_outbox_tables.py

@@ -0,0 +1,67 @@
+"""create outbox tables
+
+Revision ID: d0dc58cc803e
+Revises: 
+Create Date: 2026-06-29 17:34:15.286303
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'd0dc58cc803e'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('outbox_message',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('kind', sqlmodel.sql.sqltypes.AutoString(length=8), nullable=False),
+    sa.Column('name', sqlmodel.sql.sqltypes.AutoString(length=200), nullable=False),
+    sa.Column('payload', sa.JSON(), nullable=False),
+    sa.Column('idempotency_key', sqlmodel.sql.sqltypes.AutoString(length=200), nullable=True),
+    sa.Column('status', sqlmodel.sql.sqltypes.AutoString(length=16), nullable=False),
+    sa.Column('attempts', sa.Integer(), nullable=False),
+    sa.Column('available_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('locked_by', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=True),
+    sa.Column('locked_until', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('dispatched_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('dead_lettered_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('last_error', sqlmodel.sql.sqltypes.AutoString(length=2000), nullable=True),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_outbox_message'))
+    )
+    with op.batch_alter_table('outbox_message', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_outbox_message_available_at'), ['available_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_outbox_message_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_outbox_message_idempotency_key'), ['idempotency_key'], unique=False)
+        batch_op.create_index(batch_op.f('ix_outbox_message_kind'), ['kind'], unique=False)
+        batch_op.create_index(batch_op.f('ix_outbox_message_locked_by'), ['locked_by'], unique=False)
+        batch_op.create_index(batch_op.f('ix_outbox_message_name'), ['name'], unique=False)
+        batch_op.create_index(batch_op.f('ix_outbox_message_status'), ['status'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('outbox_message', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_outbox_message_status'))
+        batch_op.drop_index(batch_op.f('ix_outbox_message_name'))
+        batch_op.drop_index(batch_op.f('ix_outbox_message_locked_by'))
+        batch_op.drop_index(batch_op.f('ix_outbox_message_kind'))
+        batch_op.drop_index(batch_op.f('ix_outbox_message_idempotency_key'))
+        batch_op.drop_index(batch_op.f('ix_outbox_message_created_at'))
+        batch_op.drop_index(batch_op.f('ix_outbox_message_available_at'))
+
+    op.drop_table('outbox_message')
+    # ### end Alembic commands ###

terp_cap_outbox-0.1.0/src/terp/capabilities/outbox/models.py

@@ -0,0 +1,123 @@
+"""The durable outbox table — one row per post-commit unit of delivery.
+
+A row is one piece of work the framework promised to deliver *after* the
+producing transaction committed: a queued background **job** (``kind="job"``) or a
+domain **event** (``kind="event"``). It is written **transactionally, on the
+business write's own session** (see :mod:`terp.capabilities.outbox.store`), so the
+row commits atomically with the mutation that produced it and a rollback drops both
+— the no-dual-write guarantee the dispatcher seam (ADR 0008) was designed for.
+
+Append-only + status updates only: a row is inserted ``pending`` and then only ever
+transitions ``pending -> dispatched`` (delivered) or ``pending -> dead_lettered``
+(failed ``max_attempts`` times); its ``payload`` (the serialized envelope) never
+changes. Like :class:`~terp.capabilities.audit.AuditEvent` it therefore composes
+:class:`~terp.core.UUIDPrimaryKeyMixin` rather than ``BaseTable`` — there is no
+optimistic-concurrency ``version`` (the lease, not OCC, arbitrates concurrent
+workers) and no ``updated_at`` (the explicit ``dispatched_at`` / ``dead_lettered_at``
+stamps are the meaningful timeline). Every caller-influenceable ``str`` column caps
+its length so an oversized payload can never break the INSERT.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any, Final
+
+from sqlalchemy import JSON, DateTime
+from sqlmodel import Column, Field, SQLModel
+
+from terp.core import UUIDPrimaryKeyMixin
+
+# The two kinds of work the outbox carries (a plain str column, never a higher-layer
+# enum — this leaf stays dependency-light, like AuditEvent.action).
+KIND_EVENT: Final[str] = "event"
+KIND_JOB: Final[str] = "job"
+
+# The lifecycle a row moves through: inserted ``pending``, then terminally either
+# ``dispatched`` (delivered) or ``dead_lettered`` (failed past its retry budget).
+STATUS_PENDING: Final[str] = "pending"
+STATUS_DISPATCHED: Final[str] = "dispatched"
+STATUS_DEAD_LETTERED: Final[str] = "dead_lettered"
+
+# Hard caps so a hostile / oversized value can never break the INSERT or the trail.
+_NAME_MAX: Final[int] = 200
+_KEY_MAX: Final[int] = 200
+_LOCK_MAX: Final[int] = 128
+_ERROR_MAX: Final[int] = 2000
+
+
+def _utc_now() -> datetime:
+    """UTC ``now`` provider for this non-``BaseTable`` append-only row."""
+    return datetime.now(UTC)
+
+
+class OutboxMessage(UUIDPrimaryKeyMixin, SQLModel, table=True):  # arch-allow-table-models-use-base-table: append-only delivery infra (like AuditEvent) — the lease, not OCC version/updated_at, arbitrates writers (see module docstring)
+    __tablename__ = "outbox_message"
+
+    kind: str = Field(max_length=8, index=True)  # KIND_EVENT | KIND_JOB
+    name: str = Field(max_length=_NAME_MAX, index=True)
+    payload: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON, nullable=False))
+    idempotency_key: str | None = Field(default=None, max_length=_KEY_MAX, index=True)
+    status: str = Field(default=STATUS_PENDING, max_length=16, index=True)
+    attempts: int = Field(default=0)
+    available_at: datetime = Field(
+        default_factory=_utc_now,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=False,
+        index=True,
+    )
+    locked_by: str | None = Field(default=None, max_length=_LOCK_MAX, index=True)
+    locked_until: datetime | None = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=True,
+    )
+    created_at: datetime = Field(
+        default_factory=_utc_now,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=False,
+        index=True,
+    )
+    dispatched_at: datetime | None = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=True,
+    )
+    dead_lettered_at: datetime | None = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),  # type: ignore[call-overload]
+        nullable=True,
+    )
+    last_error: str | None = Field(default=None, max_length=_ERROR_MAX)
+
+    def assert_within_column_bounds(self) -> None:
+        """Reject a caller-influenced string that exceeds its ``VARCHAR(n)`` column bound.
+
+        SQLite does **not** enforce ``VARCHAR`` length, but PostgreSQL does — so an
+        over-length value the SQLite-backed tests silently accept would fail the INSERT
+        on PostgreSQL and, because the outbox row rides the business write's own
+        transaction (see :mod:`terp.capabilities.outbox.store`), fail that business
+        write. Validate up front so the behaviour is identical on every backend: a clear,
+        early :class:`ValueError` rather than a vendor-specific mid-transaction failure.
+        """
+        for column, value, limit in (
+            ("name", self.name, _NAME_MAX),
+            ("idempotency_key", self.idempotency_key, _KEY_MAX),
+        ):
+            if value is not None and len(value) > limit:
+                raise ValueError(
+                    f"outbox message {column!r} is {len(value)} characters, exceeding "
+                    f"its {limit}-character column bound (a PostgreSQL INSERT would "
+                    f"reject it and fail the business write the row rides)"
+                )
+
+
+__all__ = [
+    "KIND_EVENT",
+    "KIND_JOB",
+    "STATUS_DEAD_LETTERED",
+    "STATUS_DISPATCHED",
+    "STATUS_PENDING",
+    "OutboxMessage",
+]

terp_cap_outbox-0.1.0/src/terp/capabilities/outbox/queue.py

@@ -0,0 +1,82 @@
+"""The durable producers: a job queue and an event dispatcher that persist an outbox row.
+
+These are the drop-in backends a composition root wires to make post-commit delivery
+survive a restart — with **no** change to any ``enqueue`` / ``emit`` call site (ADR
+0008's promise)::
+
+    create_app(..., job_queue=OutboxJobQueue(), event_dispatcher=outbox_event_dispatcher,
+               require_durable_jobs=settings.is_production)
+
+:meth:`OutboxJobQueue.enqueue` and :func:`outbox_event_dispatcher` both append an
+:class:`~terp.capabilities.outbox.models.OutboxMessage` on the **session they already
+receive** — the business write's session — so the row commits in the same transaction
+as the mutation that produced it (no dual-write). The job queue marks itself durable
+(:func:`~terp.core.mark_durable_job_queue`), so ``create_app(require_durable_jobs=True)``
+accepts it where the in-process default is refused.
+"""
+
+from __future__ import annotations
+
+from sqlmodel import Session
+
+from terp.core import (
+    EventDefinition,
+    EventEnvelope,
+    JobEnvelope,
+    JobQueue,
+    mark_durable_job_queue,
+)
+
+from terp.capabilities.outbox._serde import (
+    event_envelope_to_payload,
+    job_envelope_to_payload,
+)
+from terp.capabilities.outbox.models import KIND_EVENT, KIND_JOB, OutboxMessage
+from terp.capabilities.outbox.store import append
+
+
+class OutboxJobQueue(JobQueue):
+    """A durable :class:`~terp.core.JobQueue` that records each job as an outbox row.
+
+    Unlike :class:`~terp.core.InProcessJobQueue` (which runs the handler inline), this
+    only *records* the envelope — atomically with the business write on the caller's
+    session — for a leased :class:`~terp.capabilities.outbox.OutboxWorker` to drain
+    off-request, surviving a restart. It marks itself durable, so
+    ``create_app(require_durable_jobs=True)`` accepts it.
+    """
+
+    def __init__(self) -> None:
+        mark_durable_job_queue(self)
+
+    def enqueue(self, session: Session, envelope: JobEnvelope) -> str:
+        """Persist *envelope* as a ``pending`` outbox row on *session*; return its id."""
+        message = OutboxMessage(
+            kind=KIND_JOB,
+            name=envelope.name,
+            payload=job_envelope_to_payload(envelope),
+            idempotency_key=envelope.idempotency_key,
+        )
+        append(session, message)
+        return str(message.id)
+
+
+def outbox_event_dispatcher(
+    session: Session, envelope: EventEnvelope, definition: EventDefinition
+) -> None:
+    """A durable :data:`~terp.core.EventDispatcher`: record each event as an outbox row.
+
+    Installed at ``create_app(event_dispatcher=outbox_event_dispatcher)``. It records
+    the envelope on the producer's session — atomic with the business write — for the
+    :class:`~terp.capabilities.outbox.OutboxWorker` to deliver to in-process handlers
+    off-request. *definition* satisfies the dispatcher seam contract; the stored
+    envelope already carries the canonical name / visibility / payload.
+    """
+    message = OutboxMessage(
+        kind=KIND_EVENT,
+        name=envelope.name,
+        payload=event_envelope_to_payload(envelope),
+    )
+    append(session, message)
+
+
+__all__ = ["OutboxJobQueue", "outbox_event_dispatcher"]

terp_cap_outbox-0.1.0/src/terp/capabilities/outbox/store.py

@@ -0,0 +1,120 @@
+"""The outbox's raw persistence — the one module that writes the delivery table.
+
+Three operations, deliberately isolated here so every governed ``# arch-allow-*``
+opt-out lives in one place:
+
+* :func:`append` stages a row on the **business write's own session**, riding the
+  audited write unit so it commits atomically with the mutation that produced it (a
+  nested enqueue defers to the outer ``BaseService`` commit; a standalone enqueue is
+  its own durable unit). It cannot route through ``BaseService`` —
+  :class:`~terp.capabilities.outbox.models.OutboxMessage` is not a ``BaseTable`` — so
+  it appends directly, exactly like the durable audit sink at the base of the write
+  stack.
+* :func:`claim_due` leases a batch of due rows with a single atomic UPDATE (portable
+  across SQLite and PostgreSQL; ``SKIP LOCKED`` is added on a backend that supports
+  it), so N workers drain one outbox without double-dispatch.
+* :func:`finalize` commits a worker's status transition (dispatched / rescheduled /
+  dead-lettered) on the outbox's own table.
+
+The worker drives :func:`claim_due` / :func:`finalize` on a **plain** session, but the
+session is still a :class:`~terp.core._internal.session_guard.WriteGuardedSession`
+(handed out by the same session factory as the request session), so both ride
+:func:`~terp.core._internal.session_guard.enter_write_unit` too, exactly like
+:func:`append` — the lease UPDATE and the status-transition commit are themselves
+unaudited, infrastructure-only writes on the outbox's own table, not a business
+mutation, but the guard cannot tell that from an ``# arch-allow-*`` comment alone.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import or_, update
+from sqlmodel import Session, col, select
+
+# The outbox is framework delivery infrastructure: its row must ride the audited write
+# unit to commit atomically with the business write (the no-dual-write guarantee), a
+# scope kept under _internal so an app module cannot open it to wave a write past the
+# audit guard. The capability legitimately reaches it, like the audit sink reaches the
+# base of the write stack.
+from terp.core._internal.session_guard import enter_write_unit  # arch-allow-no-internal-imports: durable delivery infra must ride the audited write unit to append atomically with the business write; the scope primitive is _internal so app modules cannot open it
+
+from terp.capabilities.outbox.models import STATUS_PENDING, OutboxMessage
+
+
+def append(session: Session, message: OutboxMessage) -> OutboxMessage:
+    """Append *message* to the outbox inside the caller's audited write unit.
+
+    Rides :func:`~terp.core._internal.session_guard.enter_write_unit` so the INSERT
+    joins whatever transaction is open on *session*: enqueued from within a
+    ``BaseService`` write (the common case), the row commits atomically with the
+    business mutation and a rollback drops both; enqueued standalone, it is its own
+    outermost, committed unit. Returns *message* (its id is assigned at construction).
+    """
+    message.assert_within_column_bounds()
+    with enter_write_unit() as outermost:
+        session.add(message)  # arch-allow-mutations-emit-audit: append-only delivery infra at the base of the write stack (like the audit sink); OutboxMessage is not a BaseTable, so it cannot route through BaseService
+        if outermost:
+            session.commit()  # arch-allow-mutations-emit-audit: a standalone enqueue is its own durable unit; a nested enqueue defers to the outer BaseService commit
+    return message
+
+
+def claim_due(
+    session: Session,
+    *,
+    claim_id: str,
+    now: datetime,
+    lease_until: datetime,
+    limit: int,
+    skip_locked: bool = False,
+) -> list[OutboxMessage]:
+    """Atomically lease up to *limit* due, unlocked rows to *claim_id*; return them.
+
+    A single UPDATE marks the due rows (``pending``, ``available_at`` reached, lease
+    free or expired) with this worker's unique *claim_id* and *lease_until*, so two
+    workers never grab the same row — portable across SQLite and PostgreSQL, with
+    ``SELECT ... FOR UPDATE SKIP LOCKED`` added on a backend that supports it
+    (*skip_locked*; SQLite silently ignores the clause, the atomic UPDATE still
+    serialises writers). The follow-up SELECT returns exactly the rows this claim won
+    (its *claim_id* is unique per cycle). A crashed worker's rows are reclaimed once
+    ``lease_until`` passes (the ``locked_until < now`` branch) — at-least-once.
+    """
+    due = (
+        select(OutboxMessage.id)
+        .where(
+            col(OutboxMessage.status) == STATUS_PENDING,
+            col(OutboxMessage.available_at) <= now,
+            or_(
+                col(OutboxMessage.locked_until).is_(None),
+                col(OutboxMessage.locked_until) < now,
+            ),
+        )
+        .order_by(col(OutboxMessage.available_at), col(OutboxMessage.id))
+        .limit(limit)
+    )
+    if skip_locked:
+        due = due.with_for_update(skip_locked=True)
+    with enter_write_unit() as outermost:
+        session.execute(  # arch-allow-mutations-emit-audit: the atomic lease claim on the outbox's own table — a portable SKIP-LOCKED-style lock, not a business mutation
+            update(OutboxMessage)
+            .where(col(OutboxMessage.id).in_(due))
+            .values(locked_by=claim_id, locked_until=lease_until)
+        )
+        if outermost:
+            session.commit()  # arch-allow-mutations-emit-audit: commit the lease so concurrent workers observe it
+    return list(
+        session.exec(
+            select(OutboxMessage)
+            .where(col(OutboxMessage.locked_by) == claim_id)
+            .order_by(col(OutboxMessage.available_at), col(OutboxMessage.id))
+        ).all()
+    )
+
+
+def finalize(session: Session) -> None:
+    """Commit a worker's in-place status transition on the outbox's own table."""
+    with enter_write_unit():
+        session.commit()  # arch-allow-mutations-emit-audit: persist the worker's status transition (dispatched / rescheduled / dead-lettered)
+
+
+__all__ = ["append", "claim_due", "finalize"]

terp_cap_outbox-0.1.0/src/terp/capabilities/outbox/worker.py

@@ -0,0 +1,310 @@
+"""The leased, retrying outbox worker — the consumer that drains pending rows.
+
+``terp jobs worker`` (or a worker-container entrypoint) runs this loop. Each cycle it
+**claims** a batch of due rows with a lease (so N workers drain one outbox without
+double-dispatch), **executes** each — a job through the context-binding
+:func:`~terp.core._internal.job_runtime.run_job` (so its writes stay audited +
+actor / tenant stamped, the jobs design's §7), an event through the in-process
+handlers — and records the outcome: ``dispatched`` on success, a **retry** with
+exponential backoff, or ``dead_lettered`` once the job's
+:class:`~terp.core.RetryPolicy` ``max_attempts`` is exhausted.
+
+Delivery is **at-least-once**: a worker that crashes mid-flight loses its lease at
+``locked_until``, and another reclaims and re-runs the row — so a handler must be
+idempotent (its ``idempotency_key`` + the business unique keys). To stay correct on
+SQLite (where a held read transaction blocks a writer on another connection), the
+worker **claims a batch and detaches it**, then executes and finalizes each row in its
+own short transaction — so a long-running job never keeps the bookkeeping connection's
+lock open, and each job runs in its **own** audited unit opened by ``run_job``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, replace
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from sqlmodel import Session
+
+from terp.core import EventEnvelope, RetryPolicy
+from terp.core.jobs import active_job_catalog
+
+# run_job is the kernel's context-binding executor; only a JobQueue / the durable
+# worker drives it (it stays _internal so an app module reaches background work solely
+# through the typed enqueue chokepoint, never by running a job directly).
+from terp.core._internal.job_runtime import run_job  # arch-allow-no-internal-imports: the durable worker is the consumer half of the jobs seam; run_job is the kernel's context-binding executor, kept _internal so app modules cannot run jobs directly
+
+from terp.capabilities.outbox._serde import (
+    payload_to_event_envelope,
+    payload_to_job_envelope,
+)
+from terp.capabilities.outbox.models import (
+    KIND_JOB,
+    STATUS_DEAD_LETTERED,
+    STATUS_DISPATCHED,
+    STATUS_PENDING,
+    OutboxMessage,
+)
+from terp.capabilities.outbox.store import claim_due, finalize
+
+_ERROR_MAX = 2000
+
+# Outcome of a finalize whose lease was lost mid-execution: the job outran its lease and
+# another worker reclaimed + finalized the row, so this (stale) worker discards its result
+# rather than clobbering the new owner. Re-delivery already happened (at-least-once); this
+# only protects the bookkeeping. Distinct from every STATUS_* value.
+_LOST = "lost"
+
+
+def _utc_now() -> datetime:
+    """UTC ``now`` provider (the worker's default clock; injectable for tests)."""
+    return datetime.now(UTC)
+
+
+def _clip(value: str) -> str:
+    """Strip NUL bytes and clamp an error message to the ``last_error`` column bound."""
+    return value.replace("\x00", "")[:_ERROR_MAX]
+
+
+def _backoff_seconds(attempts: int, retry: RetryPolicy) -> float:
+    """Exponential backoff for the *attempts*-th failure, capped at the policy max."""
+    delay = retry.backoff_seconds * (retry.backoff_multiplier ** (attempts - 1))
+    return min(delay, retry.max_backoff_seconds)
+
+
+def deliver_event_in_process(envelope: EventEnvelope) -> None:
+    """Deliver *envelope* to every in-process handler subscribed to its event.
+
+    The worker's default terminal delivery for a ``kind="event"`` row: it fans the
+    event out to the eventbus capability's handlers (the **real** in-process dispatch,
+    never the active dispatcher — which is the outbox itself). An event with no
+    subscribers is a no-op success. If the eventbus capability is not installed the
+    import fails and the row retries / dead-letters — you should not produce events
+    without a consumer.
+    """
+    from terp.capabilities.eventbus.registry import handlers_for
+
+    for handler in handlers_for(envelope.name):
+        handler(envelope)
+
+
+@dataclass(frozen=True)
+class _Claimed:
+    """A detached snapshot of one claimed row: enough to execute and finalize it.
+
+    Captured before the claim session closes, so the long-running execution never
+    holds the bookkeeping connection's transaction open (SQLite-safe). Carries the
+    cycle's *claim_id* so finalize can verify this worker still holds the lease.
+    """
+
+    id: uuid.UUID
+    kind: str
+    name: str
+    payload: Mapping[str, Any]
+    attempts: int
+    claim_id: str
+
+
+@dataclass(frozen=True)
+class DrainResult:
+    """The tally of one or more drain cycles (for the CLI loop and tests)."""
+
+    claimed: int = 0
+    dispatched: int = 0
+    retried: int = 0
+    dead_lettered: int = 0
+    lost: int = 0
+
+
+class OutboxWorker:
+    """Claim, execute, and finalize due outbox rows; retry with backoff; dead-letter.
+
+    Construct it with a *session_factory* for its own plain bookkeeping session (the
+    outbox is infrastructure, not an audited business write) and an optional
+    *job_session_factory* passed to :func:`run_job` for each job's own audited unit.
+    The clock / lease / batch size / retry budget / SKIP-LOCKED flag are injectable for
+    tests and for tuning a deployment.
+    """
+
+    def __init__(
+        self,
+        session_factory: Callable[[], Session],
+        *,
+        job_session_factory: Callable[[], Session] | None = None,
+        event_dispatcher: Callable[[EventEnvelope], None] = deliver_event_in_process,
+        worker_id: str | None = None,
+        clock: Callable[[], datetime] = _utc_now,
+        lease_seconds: float = 30.0,
+        batch_size: int = 10,
+        retry: RetryPolicy | None = None,
+        skip_locked: bool = False,
+    ) -> None:
+        self._session_factory = session_factory
+        self._job_session_factory = job_session_factory
+        self._event_dispatcher = event_dispatcher
+        self._worker_id = worker_id or f"outbox-worker-{uuid.uuid4().hex[:8]}"
+        self._clock = clock
+        self._lease_seconds = lease_seconds
+        self._batch_size = batch_size
+        self._retry = retry or RetryPolicy()
+        self._skip_locked = skip_locked
+
+    def drain_once(self) -> DrainResult:
+        """Claim one batch of due rows, process each, and return the tally."""
+        claimed = self._claim_batch()
+        dispatched = retried = dead_lettered = lost = 0
+        for message in claimed:
+            outcome = self._process(message)
+            if outcome == STATUS_DISPATCHED:
+                dispatched += 1
+            elif outcome == STATUS_DEAD_LETTERED:
+                dead_lettered += 1
+            elif outcome == _LOST:
+                lost += 1
+            else:
+                retried += 1
+        return DrainResult(
+            claimed=len(claimed),
+            dispatched=dispatched,
+            retried=retried,
+            dead_lettered=dead_lettered,
+            lost=lost,
+        )
+
+    def run(self, *, max_cycles: int | None = None) -> DrainResult:
+        """Drain repeatedly until no rows remain (or *max_cycles* is reached); return totals.
+
+        The worker-container entrypoint runs with ``max_cycles=None``, draining batches
+        until the outbox holds no *due* row, then returns — a scheduler / supervisor
+        re-invokes it (the design's external-trigger model; a rescheduled row waits out
+        its backoff). Tests pass a finite *max_cycles*.
+        """
+        totals = DrainResult()
+        cycles = 0
+        while max_cycles is None or cycles < max_cycles:
+            result = self.drain_once()
+            totals = DrainResult(
+                claimed=totals.claimed + result.claimed,
+                dispatched=totals.dispatched + result.dispatched,
+                retried=totals.retried + result.retried,
+                dead_lettered=totals.dead_lettered + result.dead_lettered,
+                lost=totals.lost + result.lost,
+            )
+            cycles += 1
+            if result.claimed == 0:
+                break
+        return totals
+
+    def _claim_batch(self) -> list[_Claimed]:
+        """Lease a batch and snapshot it, then close the session (release the lock)."""
+        now = self._clock()
+        claim_id = f"{self._worker_id}:{uuid.uuid4().hex}"
+        lease_until = now + timedelta(seconds=self._lease_seconds)
+        with self._session_factory() as session:
+            rows = claim_due(
+                session,
+                claim_id=claim_id,
+                now=now,
+                lease_until=lease_until,
+                limit=self._batch_size,
+                skip_locked=self._skip_locked,
+            )
+            return [
+                _Claimed(
+                    id=row.id,
+                    kind=row.kind,
+                    name=row.name,
+                    payload=dict(row.payload),
+                    attempts=row.attempts,
+                    claim_id=claim_id,
+                )
+                for row in rows
+            ]
+
+    def _process(self, message: _Claimed) -> str:
+        """Execute one claimed *message*, then finalize its status; return that status."""
+        try:
+            self._execute(message)
+        except Exception as exc:  # noqa: BLE001 - any handler failure becomes a retry / dead-letter
+            return self._finalize_failure(message, exc)
+        return self._finalize_success(message)
+
+    def _execute(self, message: _Claimed) -> None:
+        """Run the message: a job through :func:`run_job`, an event through the dispatcher."""
+        if message.kind == KIND_JOB:
+            envelope = payload_to_job_envelope(message.payload)
+            run_job(
+                replace(envelope, attempt=message.attempts + 1),
+                session_factory=self._job_session_factory,
+            )
+        else:
+            self._event_dispatcher(payload_to_event_envelope(message.payload))
+
+    def _finalize_success(self, message: _Claimed) -> str:
+        """Mark *message* dispatched (only while this worker still holds the lease)."""
+
+        def _mutate(row: OutboxMessage) -> str:
+            row.status = STATUS_DISPATCHED
+            row.dispatched_at = self._clock()
+            return STATUS_DISPATCHED
+
+        return self._finalize(message, _mutate)
+
+    def _finalize_failure(self, message: _Claimed, exc: Exception) -> str:
+        """Retry *message* with backoff, or dead-letter it once its budget is spent."""
+        retry = self._retry_for(message)
+
+        def _mutate(row: OutboxMessage) -> str:
+            row.attempts += 1
+            row.last_error = _clip(f"{type(exc).__name__}: {exc}")
+            if row.attempts >= retry.max_attempts:
+                row.status = STATUS_DEAD_LETTERED
+                row.dead_lettered_at = self._clock()
+                return STATUS_DEAD_LETTERED
+            row.status = STATUS_PENDING
+            row.available_at = self._clock() + timedelta(
+                seconds=_backoff_seconds(row.attempts, retry)
+            )
+            return STATUS_PENDING
+
+        return self._finalize(message, _mutate)
+
+    def _finalize(
+        self, message: _Claimed, mutate: Callable[[OutboxMessage], str]
+    ) -> str:
+        """Persist a status transition — but only while this worker still holds the lease.
+
+        A job that outran ``lease_seconds`` may have been reclaimed and finalized by
+        another worker; persisting this now-stale worker's outcome would clobber the new
+        owner — resurrecting a ``dispatched`` row into ``pending`` (a redundant
+        re-dispatch, potentially looping for a consistently slow job) or flipping it to
+        ``dead_lettered``, and releasing a lease another worker still holds. So the
+        transition is guarded: if ``locked_by`` no longer matches this claim, the worker
+        **discards** its outcome (:data:`_LOST`) and the new owner wins (a row that has
+        since vanished — e.g. a retention purge between claim and finalize — is likewise
+        treated as :data:`_LOST` rather than crashing the cycle). Re-*delivery* already
+        happened (at-least-once); this protects only the bookkeeping. Tune
+        ``lease_seconds`` above the longest expected job to avoid the redundant work.
+        """
+        with self._session_factory() as session:
+            row = session.get(OutboxMessage, message.id)
+            if row is None or row.locked_by != message.claim_id:
+                return _LOST
+            outcome = mutate(row)
+            row.locked_by = None
+            row.locked_until = None
+            finalize(session)
+        return outcome
+
+    def _retry_for(self, message: _Claimed) -> RetryPolicy:
+        """The retry budget governing *message*: the job's own, or the worker default."""
+        if message.kind == KIND_JOB:
+            job = active_job_catalog().get(message.name)
+            if job is not None:
+                return job.retry
+        return self._retry
+
+
+__all__ = ["DrainResult", "OutboxWorker", "deliver_event_in_process"]