messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/config/models.py

@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Connector configuration models — the transport-level building blocks.
+
+A :class:`Source`/:class:`Destination` is a transport endpoint (type + free-form
+``settings`` validated by the connector plugin) plus delivery behaviour. The code-first
+wiring layer (:mod:`messagefoundry.config.wiring`) builds these from a connection's
+``ConnectionSpec`` to resolve connectors via the registry; routing/filtering/transforming
+is done in code-first Router/Handler scripts, not here.
+
+These models are intentionally transport-agnostic: adding a new transport never requires
+touching this file.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ConnectorType(str, Enum):
+    """Built-in transport connectors. Plugins may register additional values."""
+
+    MLLP = "mllp"
+    TCP = "tcp"  # raw TCP with configurable delimiter framing (X12 over TCP, ADR 0003)
+    FILE = "file"
+    REST = "rest"  # generic HTTP destination (ADR 0003)
+    DATABASE = "database"  # SQL destination — SQL Server first (ADR 0003)
+    SOAP = "soap"  # SOAP / web-service destination over HTTP (ADR 0003)
+    REMOTEFILE = "remotefile"  # remote-file transport — SFTP / FTP / FTPS (source + destination)
+    TIMER = "timer"  # clock-driven source — emits a configured body on a schedule (source only, ADR 0011)
+    X12 = "x12"  # raw-TCP X12 EDI — ISA/IEA-framed (no transport sentinel), source + destination (ADR 0012)
+    LOOPBACK = "loopback"  # inert inbound — messages arrive only via ingress_handoff (re-ingress, ADR 0013)
+    # DATABASE also has an inbound poll source (DatabasePoll, ADR 0003 §3 + 0004); REMOTEFILE is both
+    # source and destination. TIMER is source-only (it generates, never delivers). REST/SOAP sources
+    # (HTTP listeners) and TCP/FHIR are future.
+
+
+class ContentType(str, Enum):
+    """The payload format of an inbound connection (ADR 0004 — payload-agnostic ingress).
+
+    ``HL7V2`` (the default, so every existing config is unchanged) gets the full HL7 peek / optional
+    strict-validate / HL7-ACK ingress path and is routed to Routers/Handlers as a mutable
+    :class:`~messagefoundry.parsing.message.Message`. Any other value **skips** HL7 parsing/validation/
+    ACK: the decoded body is committed verbatim and routed as a
+    :class:`~messagefoundry.parsing.message.RawMessage` (``.raw`` / ``.text`` / ``.json()``)."""
+
+    HL7V2 = "hl7v2"
+    JSON = "json"
+    XML = "xml"
+    TEXT = "text"
+    X12 = "x12"  # ASC X12 EDI, relayed opaquely (no structured parse) — routes as RawMessage
+
+
+class AckMode(str, Enum):
+    """HL7 acknowledgement mode for MLLP/TCP sources."""
+
+    ORIGINAL = "original"  # MSA generated from the inbound message
+    ENHANCED = "enhanced"  # application + commit acks (MSH-15/16)
+    NONE = "none"
+
+
+class AckAfter(str, Enum):
+    """**When** an inbound connection sends its ACK, in the staged pipeline (ADR 0001).
+
+    ``INGEST`` (default): ACK-on-receipt — the ACK is sent as soon as the raw message is durably
+    committed to the ingress stage, before routing/transform/delivery run (decoupling intake from a
+    slow downstream). ``DELIVERED``: defer the ACK until outbound delivery succeeds (end-to-end
+    confirmation). ``DELIVERED`` is **not yet implemented** in Step A — wiring it raises
+    ``WiringError`` (it needs the listener to hold/replay the ACK from the delivery worker); the enum
+    + threading exist so the follow-up is a small change. Distinct from
+    :class:`AckMode` (which selects the ACK *code* family, not its timing)."""
+
+    INGEST = "ingest"
+    DELIVERED = "delivered"
+
+
+class OrderingMode(str, Enum):
+    """How an outbound connection's queue is drained.
+
+    ``FIFO`` (default): strict in-order per outbound connection — the worker delivers the oldest
+    enqueued message and **blocks the head on failure** (a stuck message holds the lane until it
+    succeeds, dead-letters, or is purged) so HL7 dependencies (ADT→ORM→ORU) are never reordered.
+    ``UNORDERED``: the legacy throughput mode — claim a batch and rotate past a failing message
+    (a failure backs off and later messages proceed), trading order for parallelism within the
+    connection.
+    """
+
+    FIFO = "fifo"
+    UNORDERED = "unordered"
+
+
+class InternalErrorPolicy(str, Enum):
+    """What an outbound delivery worker does when an **internal/code error** (a non-``DeliveryError``
+    exception escaping a connector's ``send`` — our bug, not the partner's) hits a message.
+
+    ``CONTINUE`` (default): error-and-continue — dead-letter the offending row (replayable) and move
+    on, so a code bug can't wedge the whole lane. ``STOP``: halt the connection's delivery worker and
+    raise a ``connection_stopped`` alert, leaving the message queued for replay — for operators who
+    would rather a lane freeze (and page someone) than auto-dead-letter on an unexpected error.
+    Partner rejections (``NegativeAckError``) and transport failures are unaffected — this governs
+    only the engine-internal-error case.
+    """
+
+    CONTINUE = "continue"
+    STOP = "stop"
+
+
+class Source(BaseModel):
+    """An inbound connector endpoint."""
+
+    type: ConnectorType
+    settings: dict[str, Any] = Field(default_factory=dict)
+    ack_mode: AckMode = AckMode.ORIGINAL
+
+
+class RetryPolicy(BaseModel):
+    """Outbound delivery retry/backoff. ``max_attempts`` is the number of delivery attempts before a
+    failure dead-letters; ``None`` (the default) means **retry forever** — the conservative posture
+    for transient failures (transport errors, ``AE`` NAKs), so nothing is silently lost. Under FIFO a
+    forever-retrying head blocks its lane until it succeeds or an operator purges it (a permanent
+    ``AR`` reject is the exception — it fails fast, see
+    :class:`~messagefoundry.transports.base.NegativeAckError`). Set a finite ``max_attempts`` to opt
+    back into retry-then-dead-letter."""
+
+    max_attempts: int | None = None
+    backoff_seconds: float = 5.0
+    backoff_multiplier: float = 2.0
+    max_backoff_seconds: float = 300.0
+
+
+class BuildupThreshold(BaseModel):
+    """When to raise a ``queue_buildup`` alert for an outbound lane (its backlog is not draining — a
+    retry-forever head blocking the lane is the classic cause).
+
+    A lane crosses the threshold when its **pending depth** reaches ``max_depth`` *or* its **oldest
+    pending message's age** reaches ``max_oldest_seconds``. ``None`` disables that dimension; both
+    ``None`` disables buildup alerting for the connection. The age dimension defaults on (a head stuck
+    over five minutes is a problem in any environment); depth is opt-in (a healthy ceiling depends on
+    the connection's throughput, so there's no safe universal default)."""
+
+    max_depth: int | None = None
+    max_oldest_seconds: float | None = 300.0
+
+
+class SignatureAlgorithm(str, Enum):
+    """JWS algorithm for opt-in per-connection outbound message signing (ASVS 4.1.5, ADR 0018).
+
+    All three are produced with the **core** ``cryptography`` dependency (no new package). ``RS256``
+    (RSASSA-PKCS1-v1_5) is **deterministic** — the same key + payload always yields the same signature;
+    ``PS256`` (RSASSA-PSS) and ``ES256`` (ECDSA P-256) are **randomized** (a fresh signature per call,
+    like the WS-Security nonce, ADR 0015) — all SHA-256."""
+
+    RS256 = "RS256"  # RSASSA-PKCS1-v1_5 + SHA-256 (RSA key; deterministic)
+    PS256 = "PS256"  # RSASSA-PSS + SHA-256 (RSA key; randomized)
+    ES256 = "ES256"  # ECDSA P-256 (secp256r1) + SHA-256 (EC key; randomized)
+
+
+class OutboundSigning(BaseModel):
+    """Opt-in per-connection message signing for a **REST/SOAP outbound** (ASVS 4.1.5, ADR 0018).
+
+    OFF unless configured. When set, the connector mints a **detached JWS** (RFC 7515 Appendix F) over
+    the exact outbound payload bytes in ``send()`` — past the queue boundary, like the WS-Security
+    timestamp/nonce (ADR 0015), so a retry re-mints it and routers/transforms stay pure — and carries it
+    in the ``header_name`` HTTP header. The receiver verifies it against the matching **public** key,
+    out-of-band per partner contract (the signing code's :func:`verify` counterpart does this). RSA
+    (``RS256``/``PS256``) or ECDSA (``ES256``) via the core ``cryptography`` library — no new dependency.
+
+    ``private_key`` is the signing key as **inline PEM** *(use* :func:`~messagefoundry.config.wiring.env`
+    *for the secret)* **or a path to a PEM file** (the file, like a TLS key, is protected by OS perms).
+    Put every secret — an inline key, or ``private_key_password`` for an encrypted key — in ``env()`` so
+    it is never stored in config. The key never leaves the box; only the public-verifiable signature does.
+
+    Authored code-first with :func:`~messagefoundry.transports.signing.with_signing` over a ``Rest()`` /
+    ``Soap()`` spec, or assembled from flat ``sign_*`` connector settings via :meth:`from_settings`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = True
+    algorithm: SignatureAlgorithm = SignatureAlgorithm.RS256
+    private_key: str  # inline PEM (use env() for the secret) or a path to a PEM private-key file
+    private_key_password: str | None = None  # passphrase for an encrypted key (secret — use env())
+    key_id: str | None = None  # JWS 'kid' so the receiver can select the verifying key
+    header_name: str = "X-JWS-Signature"  # the HTTP header that carries the detached JWS
+
+    @classmethod
+    def from_settings(cls, settings: Mapping[str, Any]) -> OutboundSigning | None:
+        """Build from flat ``sign_*`` connector settings, or ``None`` when signing isn't configured.
+
+        Signing is OFF (``None``) unless ``sign_private_key`` is present, so every existing outbound is
+        unchanged. The flat keys (vs a nested table) keep each value a top-level setting that ``env()``
+        resolution and ``connections.toml`` decoding already handle. Recognized keys: ``sign_enabled``,
+        ``sign_algorithm``, ``sign_private_key``, ``sign_private_key_password``, ``sign_key_id``,
+        ``sign_header``. An unknown/typo'd field raises (``extra='forbid'``)."""
+        key = settings.get("sign_private_key")
+        if not key:
+            return None
+        data: dict[str, Any] = {"private_key": key}
+        if "sign_enabled" in settings:
+            data["enabled"] = settings["sign_enabled"]
+        if settings.get("sign_algorithm"):
+            data["algorithm"] = settings["sign_algorithm"]
+        if settings.get("sign_private_key_password"):
+            data["private_key_password"] = settings["sign_private_key_password"]
+        if settings.get("sign_key_id"):
+            data["key_id"] = settings["sign_key_id"]
+        if settings.get("sign_header"):
+            data["header_name"] = settings["sign_header"]
+        return cls.model_validate(data)
+
+
+class Destination(BaseModel):
+    """An outbound connector endpoint. Each outbound connection queues independently
+    so a slow/failed one never blocks the others."""
+
+    name: str
+    type: ConnectorType
+    settings: dict[str, Any] = Field(default_factory=dict)
+    retry: RetryPolicy = Field(default_factory=RetryPolicy)
+    # Shadow / parallel-run mode (#15): when True the delivery worker runs the full pipeline + count-
+    # and-log but SUPPRESSES the real egress (no bytes/SQL leave the box) and finalizes the message
+    # PROCESSED, so a shadow instance can process real traffic without double-delivering to live
+    # partners. A deployment-wide [shadow].simulate_all_egress forces this on for every outbound.
+    simulate: bool = False
+    # ASVS 4.1.5 (ADR 0018): opt-in per-connection detached-JWS signing for REST/SOAP outbound. None
+    # (the default) = OFF — every existing outbound is byte-identical. Assembled from the env-resolved
+    # sign_* settings by the runner's _dest_config; the connector mints the signature in send().
+    sign: OutboundSigning | None = None
+
+
+class Validation(BaseModel):
+    """Parse/validate behaviour. Tolerant by default — non-conformant messages
+    still route; ``strict`` runs full hl7apy profile validation and NACKs on failure."""
+
+    hl7_version: str | None = None  # e.g. "2.5.1"; None = infer from MSH-12
+    strict: bool = False
+    profile: str | None = None  # path to a conformance profile, optional

messagefoundry/config/reference.py

@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Synchronous **read side** for reference sets (external-data enrichment, ADR 0006 Tier 1).
+
+A **reference set** is a managed, versioned, read-only lookup snapshot the engine *materializes* from
+an external source **off the message path** (a provider directory, a DB-backed translation table — the
+Corepoint Data Point / DB Association pattern). A Handler/Router reads it **purely** at call time via
+``reference("name").get(key)`` — a twin of :func:`~messagefoundry.config.wiring.code_set`, but the data
+comes from a periodic sync (the :class:`~messagefoundry.pipeline.reference_sync.ReferenceSyncRunner`),
+not a file in the bundle.
+
+Because the snapshot lives in the **store** (encrypted at rest, it may carry PHI), this is shaped like
+:mod:`messagefoundry.config.state`, not :mod:`messagefoundry.config.code_sets`: the store owns the
+read-through cache and exposes it as a :data:`ReferenceView`; the runner publishes
+``store.reference_view()`` as the active view around each router/transform run; :func:`reference`
+resolves against it synchronously. This config-layer module owns only the active-view holder + the
+accessor + the publish helpers, and does **not** import the store (one-way dependency, CLAUDE.md §4).
+
+**Re-run-safe (ADR 0006 / ADR 0001).** A read carries no side effect, so re-run-identity reduces to
+"does the snapshot change between a run and a crash-re-run?" The sync writes each new snapshot with a
+build-new-then-atomic-flip and the read view swaps wholesale only after a sync commits — so the only
+non-determinism is a flip landing in the narrow window between a run and its re-run, the **same**
+already-accepted caveat as a code-set hot-reload (see :mod:`messagefoundry.config.code_sets`).
+
+**Call-time only.** Unlike ``code_set()`` (file-loaded at config load, capturable at a module's top
+level), a reference snapshot exists only once the store is open and synced — so call :func:`reference`
+**inside a Handler/Router at run time**, like :func:`~messagefoundry.config.state.state_get`, not at
+module import.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any
+
+__all__ = [
+    "ReferenceSet",
+    "ReferenceView",
+    "ReferenceError",
+    "reference",
+    "set_active",
+    "reset",
+    "activated",
+]
+
+#: The engine-published read view: a read-only mapping ``{refset_name: {key: value}}`` of the **active**
+#: snapshots. The store builds it (decrypting at load), so the config layer needs no store import.
+ReferenceView = Mapping[str, Mapping[str, Any]]
+
+
+class ReferenceError(ValueError):
+    """A reference set was read but isn't available (no active view, or no such synced set).
+
+    A subclass of :class:`ValueError`. Raised at **handler run time** (a reference is read inside a
+    transform), so it surfaces as that message's ``ERROR`` disposition / dead-letter — fail loud, never
+    a silent empty table — not as a load-time ``WiringError``."""
+
+
+class ReferenceSet(Mapping[str, Any]):
+    """A frozen, read-only reference snapshot: ``name`` + an immutable ``key → value`` mapping.
+
+    Behaves like a read-only ``dict`` (``rs[key]``, ``rs.get(key, default)``, ``key in rs``,
+    ``len(rs)``, iteration) but rejects mutation — one snapshot is shared across every transform, so a
+    Handler must never edit it. ``rs[missing]`` raises a :class:`KeyError` naming the set;
+    ``rs.get(missing, default)`` returns the default (sparse external data). Wraps the snapshot mapping
+    **by reference** (no copy) — the view is already read-only and the sync swaps it wholesale, so a
+    large table isn't copied on every lookup."""
+
+    __slots__ = ("_name", "_data")
+
+    def __init__(self, name: str, data: Mapping[str, Any]) -> None:
+        self._name = name
+        self._data = data
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def __getitem__(self, key: str) -> Any:
+        try:
+            return self._data[key]
+        except KeyError:
+            raise KeyError(f"key {key!r} not in reference set {self._name!r}") from None
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._data
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        return f"ReferenceSet(name={self._name!r}, entries={len(self._data)})"
+
+
+# Active view as a ContextVar (mirrors state._active): the runner re-publishes the live snapshot view
+# around each router/transform run so a call-time reference(...) inside a Handler resolves, and a clean
+# reset restores the prior view (no leak across runs / overlapping reloads). Defaults to None = "no
+# active view" so reference() can distinguish "not running" from "set not synced".
+_active: ContextVar[ReferenceView | None] = ContextVar("mefor_active_reference", default=None)
+
+
+def set_active(view: ReferenceView | None) -> Any:
+    """Publish ``view`` as the active reference view and return a reset token (pass it to :func:`reset`).
+
+    For callers that can't bracket the active span with a ``with`` (e.g. an async worker publishing
+    around a single transform call). Prefer :func:`activated` where a ``with`` block fits."""
+    return _active.set(view)
+
+
+def reset(token: Any) -> None:
+    """Restore the active reference view to what it was before the matching :func:`set_active`."""
+    _active.reset(token)
+
+
+@contextmanager
+def activated(view: ReferenceView | None) -> Iterator[None]:
+    """Make ``view`` the active reference view for the duration of the ``with`` block, then restore.
+
+    The runner brackets each router/transform run with it (and dry-run mirrors that), so
+    :func:`reference` resolves at call time and the prior view is always restored — no leak."""
+    token = _active.set(view)
+    try:
+        yield
+    finally:
+        _active.reset(token)
+
+
+def reference(name: str) -> ReferenceSet:
+    """Return the active reference set ``name`` (a frozen, read-only :class:`ReferenceSet`).
+
+    Call it inside a Handler/Router at run time::
+
+        npi = reference("provider_npi").get(msg["PV1-7.1"])
+
+    Resolves against the engine-published snapshot view the runner brackets around the run. A missing
+    **key** is not an error (use ``.get(key, default)`` — external data is sparse). A missing **set**
+    (no active view, or the named set hasn't synced) raises :class:`ReferenceError` (fail loud) — it
+    surfaces as that message's ``ERROR`` disposition, like any transform error."""
+    view = _active.get()
+    if view is None:
+        raise ReferenceError(
+            f"reference({name!r}) called with no active reference view — reference sets resolve only "
+            "inside a Handler/Router while the graph is running (call it at run time, not at import)"
+        )
+    try:
+        data = view[name]
+    except KeyError:
+        available = ", ".join(sorted(view)) or "(none synced)"
+        raise ReferenceError(
+            f"no such reference set {name!r} — declare it with Reference({name!r}, source=…) and let "
+            f"it sync; available: {available}"
+        ) from None
+    return ReferenceSet(name, data)

messagefoundry/config/response.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Synchronous **read side** for captured request/response replies (ADR 0013).
+
+A capturing outbound's reply is persisted (immutably, per message) by the delivery worker; a
+Router/Handler reads a *prior committed* reply back synchronously via :func:`response_get`. Like
+:mod:`messagefoundry.config.state` / :mod:`messagefoundry.config.reference`, the engine publishes a
+read-only **view** as a :class:`~contextvars.ContextVar` for the duration of each run, and the
+accessor resolves against it without awaiting the store (handlers are pure synchronous functions).
+
+**Increment 1 scope.** A message has no captured reply *during its own transform* (capture happens
+later, at delivery), so the engine currently publishes **no** view for a normal run — ``response_get``
+returns its default, and the provider is a registered no-op that establishes the seam, the accessor,
+and the registration order (between ``state`` and ``environment``). Increment 2 (re-ingress
+orchestration) is where a re-ingressed answer's run publishes a per-message view bound to its
+correlation lineage — at which point this accessor resolves a real reply. The view it reads is
+**immutable committed** state, so it is re-run-stable by construction (ADR 0009).
+
+**Layering (information hiding, CLAUDE.md §4).** This config-layer module owns only the active-view
+holder + the accessor + the publish helpers; it does **not** import the store. The runner bridges the
+two by publishing a store-derived view here around each run, so the config layer stays store-free.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any
+
+__all__ = [
+    "ResponseView",
+    "response_get",
+    "set_active",
+    "reset",
+    "activated",
+]
+
+#: The engine-published read view: a read-only mapping ``{destination_name: latest_reply}`` for the
+#: message in scope (Increment 2 populates it). The value shape is whatever the runner publishes; the
+#: config layer only reads it, so it needs no store import. ``None`` means "no active view".
+ResponseView = Mapping[str, Any]
+
+# Active view as a ContextVar (mirrors state._active). Defaults to None = "no active view" so
+# response_get distinguishes "not running / nothing captured" from a real reply.
+_active: ContextVar[ResponseView | None] = ContextVar("mefor_active_response", default=None)
+
+
+def set_active(view: ResponseView | None) -> Any:
+    """Publish ``view`` as the active response view and return a reset token (pass it to :func:`reset`)."""
+    return _active.set(view)
+
+
+def reset(token: Any) -> None:
+    """Restore the active response view to what it was before the matching :func:`set_active`."""
+    _active.reset(token)
+
+
+@contextmanager
+def activated(view: ResponseView | None) -> Iterator[None]:
+    """Make ``view`` the active response view for the duration of the ``with`` block, then restore.
+
+    The run-context registry brackets each transform run with it (via the ``response`` provider), so
+    :func:`response_get` resolves at call time and the prior view is always restored — no leak."""
+    token = _active.set(view)
+    try:
+        yield
+    finally:
+        _active.reset(token)
+
+
+def response_get(destination_name: str, default: Any = None) -> Any:
+    """Read the latest captured reply for ``destination_name`` from the active response view (ADR
+    0013); ``default`` on a miss or with no active view.
+
+    Synchronous (no ``await``) so it is callable inside a Handler. In Increment 1 there is no active
+    view during a normal run, so this returns ``default``; Increment 2 publishes a per-message view a
+    re-ingressed answer's handler can read. The view is immutable committed state, so a re-run reads
+    the identical value (the re-run-stability the staged pipeline requires)."""
+    view = _active.get()
+    if view is None:
+        return default
+    return view.get(destination_name, default)

messagefoundry/config/run_context.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Run-scoped context providers — the one seam that activates per-run engine state for a Router/Handler.
+
+Routers and Handlers read engine-published state at call time through **synchronous accessors**
+(``code_set()``, ``reference()``, ``state_get()``, ``current_environment()``, …). Each resolves against
+a :class:`~contextvars.ContextVar` the engine *activates* for the duration of one router/transform run.
+Before this module, every call site — the router worker, the transform worker, and the dry-run path —
+repeated its own ``with (activated(...), activated(...), …)`` tuple, so adding a new run-scoped accessor
+meant **editing all three tuples**, which collided with every other feature doing the same.
+
+This module replaces those tuples with a single registry of **providers**. A provider is a callable
+``(RunContext) -> AbstractContextManager`` tagged with the phase(s) it applies to. The engine and the
+dry-run path both call :func:`run_contexts` to enter every provider for a phase; a new run-scoped
+accessor just calls :func:`register_run_context` once at import — it never edits a call site again.
+
+**Layering (CLAUDE.md §4).** This lives in ``config/`` (not ``pipeline/``) so config-layer accessors —
+e.g. ``config.db_lookup`` — can register a provider without importing ``pipeline/`` (which would invert
+the one-way dependency). It depends only on the config activation helpers it pre-registers.
+
+**Order = nesting.** Providers are entered in **registration order** via one
+:class:`contextlib.ExitStack`, so registration order *is* the context-manager nesting order. The four
+built-ins register at import here, before any feature module; a feature that must nest *inside* another
+(e.g. an ingest-time provider inside ``db_lookup``'s executor scope) imports after it.
+
+**Re-run stability (CLAUDE.md §2).** At-least-once re-runs a router/transform and relies on identical
+output, so every provider's published state must be re-run-stable. The built-ins are (code sets /
+reference snapshots / committed state / the deployment environment name); a provider exposing live,
+non-deterministic data (``config.db_lookup``) is the documented exception and must refuse to run where
+determinism is assumed. See docs/adr/0009-run-scoped-context-providers.md.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, ExitStack, contextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from messagefoundry.config.active_environment import activated as _environment_activated
+from messagefoundry.config.code_sets import activated as _code_sets_activated
+from messagefoundry.config.reference import activated as _reference_activated
+from messagefoundry.config.response import activated as _response_activated
+from messagefoundry.config.state import activated as _state_activated
+
+__all__ = [
+    "RunContext",
+    "RunContextProvider",
+    "ROUTER",
+    "TRANSFORM",
+    "register_run_context",
+    "run_contexts",
+    "registered_providers",
+]
+
+# The two points a router/transform runs. Routers see code sets / references / environment; transforms
+# additionally see committed transform state (state is transform-only — see the built-in phases below).
+ROUTER = "router"
+TRANSFORM = "transform"
+_PHASES = frozenset({ROUTER, TRANSFORM})
+
+
+@dataclass(frozen=True)
+class RunContext:
+    """The per-run views a provider may read. The engine builds one per run from its live store/registry;
+    the dry-run path builds one from its simulated views. A provider reads only the fields it needs (a
+    phase that omits a provider never reads that provider's field — e.g. ``state_view`` in the router
+    phase), so a caller may leave unused fields at their default."""
+
+    code_sets: Any = None
+    reference_view: Any = None
+    state_view: Any = None
+    response_view: Any = (
+        None  # ADR 0013: per-message captured-reply view (transform phase; Increment 2 feeds it)
+    )
+    active_environment: str | None = None
+    ingest_time: float | None = (
+        None  # the message's re-run-stable enqueue time (ingest-time provider)
+    )
+
+
+# A provider turns a run context into a context manager that activates one accessor's view for the run.
+RunContextProvider = Callable[[RunContext], AbstractContextManager[Any]]
+
+# (name, provider, phases) in REGISTRATION ORDER == ExitStack nesting order. Module-global, populated at
+# IMPORT time: engine modules import once per process and user config modules never register here, so a
+# config reload never re-appends. Keyed by `name` for idempotency + clear diagnostics.
+_providers: list[tuple[str, RunContextProvider, frozenset[str]]] = []
+
+
+def register_run_context(
+    name: str, provider: RunContextProvider, *, phases: frozenset[str] | set[str]
+) -> None:
+    """Register a run-scoped context ``provider`` under ``name``, applied in the given ``phases``.
+
+    Call **once at module import** (an engine module's top level), not per config load. Idempotent on
+    ``name``: a second registration with the same name replaces the first **in place** (preserving
+    order), so a re-imported engine module can't double-register. ``phases`` ⊆ {``"router"``,
+    ``"transform"``}. Registration order is the runtime nesting order (see module docstring)."""
+    ph = frozenset(phases)
+    unknown = ph - _PHASES
+    if unknown:
+        raise ValueError(f"register_run_context({name!r}): unknown phase(s) {sorted(unknown)}")
+    if not ph:
+        raise ValueError(f"register_run_context({name!r}): phases must not be empty")
+    for i, (existing, _, _) in enumerate(_providers):
+        if existing == name:
+            _providers[i] = (name, provider, ph)
+            return
+    _providers.append((name, provider, ph))
+
+
+@contextmanager
+def run_contexts(context: RunContext, *, phase: str) -> Iterator[None]:
+    """Activate every provider registered for ``phase`` (in registration order) for the ``with`` body.
+
+    Replaces the hand-written ``with (activated(...), …)`` tuples the router worker, transform worker,
+    and dry-run path each used. Enters via one :class:`~contextlib.ExitStack`, so providers nest in
+    registration order and unwind cleanly (each accessor's prior view restored) on exit — including on
+    an exception raised inside the body."""
+    with ExitStack() as stack:
+        for _name, provider, phases in _providers:
+            if phase in phases:
+                stack.enter_context(provider(context))
+        yield
+
+
+def registered_providers() -> list[str]:
+    """The registered provider names in registration (nesting) order — for diagnostics / tests."""
+    return [name for name, _, _ in _providers]
+
+
+# --- built-in providers (pre-registered so the seam is byte-identical to the old `with` tuples) -------
+# Registration order below IS the nesting the workers used: code_sets (outermost) → reference → state →
+# environment (innermost). `state` is transform-only; the other three apply in both phases. The dry-run
+# path runs router+transform in one block under phase="transform" and supplies active_environment=None,
+# so environment activates None — exactly the value current_environment() had when dry-run left it unset.
+register_run_context(
+    "code_sets", lambda c: _code_sets_activated(c.code_sets), phases={ROUTER, TRANSFORM}
+)
+register_run_context(
+    "reference", lambda c: _reference_activated(c.reference_view), phases={ROUTER, TRANSFORM}
+)
+register_run_context("state", lambda c: _state_activated(c.state_view), phases={TRANSFORM})
+# ADR 0013: the captured-reply view (transform phase only — a Handler reconciling an answer is a
+# transform concern). Registered AFTER state and BEFORE environment, so the nesting order is
+# code_sets → reference → state → response → environment (asserted by a registration-order test).
+register_run_context("response", lambda c: _response_activated(c.response_view), phases={TRANSFORM})
+register_run_context(
+    "environment",
+    lambda c: _environment_activated(c.active_environment),
+    phases={ROUTER, TRANSFORM},
+)