messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/auth/tokens.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Opaque session tokens: the client holds the secret; the store keeps only its SHA-256.
+
+Opaque server-side tokens (not JWT) are chosen so logout, expiry, and role changes take effect
+immediately — the ``sessions`` row is the source of truth and can be revoked. Only the hash is
+persisted, so reading the store never exposes a usable token.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+
+#: Bytes of entropy per token (urlsafe-base64 encoded to ~43 chars).
+_TOKEN_BYTES = 32
+
+
+def mint_token() -> str:
+    """Return a fresh, unguessable token to hand to the client (store only its :func:`hash_token`)."""
+    return secrets.token_urlsafe(_TOKEN_BYTES)
+
+
+def hash_token(token: str) -> str:
+    """Hash a token for storage/lookup. Plain SHA-256 is sufficient: tokens are high-entropy secrets."""
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()

messagefoundry/auth/totp.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""RFC 6238 TOTP — the local-account second factor (WP-14, ADR 0002 §3).
+
+Pure standard-library crypto (``hmac`` / ``hashlib`` / ``base64`` / ``secrets``) so MFA adds **no new
+dependency**: a software authenticator app (Google/Microsoft Authenticator, Authy, 1Password) and the
+engine independently compute the same short code from a shared base32 secret plus the current
+30-second time step. Used only for **local** users — AD/Kerberos MFA is delegated to the directory
+(see :class:`~messagefoundry.auth.service.AuthService`). This module is side-effect-free and unit-
+tested against the RFC 6238 vectors; it never touches the store, the event loop, or config.
+
+Security notes:
+
+- TOTP is a *shared-secret* factor: it satisfies OWASP ASVS 5.0 **6.3.3** at L2 but is phishable and
+  replayable inside its step window. The L3 preference for phishing-resistant factors (WebAuthn /
+  FIDO2) is the **WP-14b** follow-on, not implemented here.
+- Verification uses a constant-time compare (:func:`hmac.compare_digest`) over a fixed candidate set
+  and a small clock-skew window. The secret is high-entropy (160-bit); the caller stores it encrypted
+  at rest (the store cipher) and never logs it.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+import time
+from urllib.parse import quote, urlencode
+
+__all__ = [
+    "DEFAULT_DIGITS",
+    "DEFAULT_PERIOD",
+    "DEFAULT_WINDOW",
+    "generate_secret",
+    "totp",
+    "verify_totp",
+    "verify_totp_step",
+    "otpauth_uri",
+    "generate_recovery_codes",
+]
+
+#: Authenticator-app conventions (what Google/Microsoft Authenticator assume by default).
+DEFAULT_DIGITS = 6
+DEFAULT_PERIOD = 30  # seconds per time step
+#: ± steps of clock skew tolerated at verify time (one step each side ≈ 30 s).
+DEFAULT_WINDOW = 1
+
+_SECRET_BYTES = 20  # 160 bits — RFC 4226 recommends ≥ 128 bits, 160 for HMAC-SHA1
+
+# Recovery codes: human-legible groups from an unambiguous alphabet (no 0/O/1/I/L confusion).
+_RECOVERY_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
+_RECOVERY_GROUP_LEN = 5
+_RECOVERY_GROUPS = 3  # e.g. "K7QF2-9DMNA-3XZP4" → ~74 bits of entropy
+
+
+def generate_secret() -> str:
+    """Return a fresh base32-encoded TOTP secret (no padding) to share with the authenticator app."""
+    return base64.b32encode(secrets.token_bytes(_SECRET_BYTES)).decode("ascii").rstrip("=")
+
+
+def _decode_secret(secret: str) -> bytes:
+    """Decode a base32 secret tolerantly: ignore spaces/case and restore any stripped padding."""
+    cleaned = secret.strip().replace(" ", "").upper()
+    padding = "=" * (-len(cleaned) % 8)
+    return base64.b32decode(cleaned + padding, casefold=True)
+
+
+def _hotp(key: bytes, counter: int, digits: int) -> str:
+    """RFC 4226 HOTP: HMAC-SHA1 over the 8-byte counter, dynamically truncated to ``digits`` decimals."""
+    mac = hmac.new(key, counter.to_bytes(8, "big"), hashlib.sha1).digest()
+    offset = mac[-1] & 0x0F
+    truncated = int.from_bytes(mac[offset : offset + 4], "big") & 0x7FFFFFFF
+    return str(truncated % (10**digits)).zfill(digits)
+
+
+def totp(
+    secret: str,
+    *,
+    now: float | None = None,
+    period: int = DEFAULT_PERIOD,
+    digits: int = DEFAULT_DIGITS,
+) -> str:
+    """The current RFC 6238 TOTP code for ``secret`` (base32) at ``now`` (defaults to the wall clock)."""
+    moment = time.time() if now is None else now
+    counter = int(moment // period)
+    return _hotp(_decode_secret(secret), counter, digits)
+
+
+def verify_totp_step(
+    secret: str,
+    code: str,
+    *,
+    now: float | None = None,
+    period: int = DEFAULT_PERIOD,
+    digits: int = DEFAULT_DIGITS,
+    window: int = DEFAULT_WINDOW,
+) -> int | None:
+    """Return the time-step counter ``code`` matches within ±``window`` steps of ``now``, or ``None``.
+
+    Unlike :func:`verify_totp` this returns *which* step matched, so the caller can enforce single-use
+    by rejecting a step that was already consumed — RFC 6238 codes are otherwise replayable inside
+    their ~30 s step window (ASVS 6.5.1). Constant-time compared over a fixed set of candidate steps
+    (no early break) so a match near the window edge can't be distinguished by timing; a non-numeric
+    or wrong-length ``code`` returns ``None``.
+    """
+    candidate = code.strip()
+    if len(candidate) != digits or not candidate.isdigit():
+        return None
+    moment = time.time() if now is None else now
+    key = _decode_secret(secret)
+    counter = int(moment // period)
+    matched: int | None = None
+    for step in range(counter - window, counter + window + 1):
+        if step < 0:
+            continue
+        if hmac.compare_digest(_hotp(key, step, digits), candidate):
+            matched = step
+    return matched
+
+
+def verify_totp(
+    secret: str,
+    code: str,
+    *,
+    now: float | None = None,
+    period: int = DEFAULT_PERIOD,
+    digits: int = DEFAULT_DIGITS,
+    window: int = DEFAULT_WINDOW,
+) -> bool:
+    """True iff ``code`` matches the TOTP for ``secret`` within ±``window`` steps of ``now``.
+
+    A thin bool wrapper over :func:`verify_totp_step` (which also reports *which* step matched, for
+    single-use enforcement). Constant-time; rejects a non-numeric or wrong-length ``code`` outright.
+    """
+    return (
+        verify_totp_step(secret, code, now=now, period=period, digits=digits, window=window)
+        is not None
+    )
+
+
+def otpauth_uri(
+    secret: str,
+    account: str,
+    *,
+    issuer: str = "MessageFoundry",
+    period: int = DEFAULT_PERIOD,
+    digits: int = DEFAULT_DIGITS,
+) -> str:
+    """Build the ``otpauth://totp/…`` URI an authenticator app scans (the UI renders it as a QR code)."""
+    # The "issuer:account" colon is the conventional literal label separator (keep it; encode the rest).
+    label = quote(f"{issuer}:{account}", safe=":")
+    params = urlencode(
+        {
+            "secret": secret,
+            "issuer": issuer,
+            "algorithm": "SHA1",
+            "digits": digits,
+            "period": period,
+        }
+    )
+    return f"otpauth://totp/{label}?{params}"
+
+
+def generate_recovery_codes(count: int) -> list[str]:
+    """Return ``count`` fresh, single-use recovery codes in plaintext (the caller hashes before storing)."""
+    codes: list[str] = []
+    for _ in range(count):
+        groups = [
+            "".join(secrets.choice(_RECOVERY_ALPHABET) for _ in range(_RECOVERY_GROUP_LEN))
+            for _ in range(_RECOVERY_GROUPS)
+        ]
+        codes.append("-".join(groups))
+    return codes

messagefoundry/checks.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""The ``messagefoundry check`` commit/CI gate — one callable for the git hook and the IDE.
+
+``run_checks`` runs the project's checks against a config directory and reports a clear pass/fail,
+reusing the in-process ``validate``/``dry_run`` paths (no re-shelling for the MessageFoundry-native
+checks). Two checks are **required** (they can block a commit):
+
+* ``validate`` — every config module loads and every ``inbound → router`` reference resolves.
+* ``dryrun`` — *only when* a fixtures dir with ``*.hl7`` is given (searched recursively): each message
+  routes through its inbound's Router/Handler(s) without erroring. A fixture under a
+  ``<messages>/<inbound_name>/`` subdir is dry-run **only** against that feed (#11); a fixture not under
+  such a subdir runs against **every** inbound. Absent fixtures → skipped (never blocks).
+
+``ruff`` and ``mypy`` are **advisory**: run only when installed (``shutil.which``) and never block —
+a non-developer author shouldn't be stopped by a lint nit. Exit-code policy lives in the CLI
+(``__main__._check``): 0 iff no required check failed.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__all__ = ["CheckResult", "CheckReport", "run_checks"]
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """The outcome of one check."""
+
+    name: str
+    ok: bool
+    required: bool
+    skipped: bool = False
+    detail: str = ""
+
+    @property
+    def blocking(self) -> bool:
+        """A required check that ran and failed — the only thing that fails the gate."""
+        return self.required and not self.ok and not self.skipped
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "ok": self.ok,
+            "required": self.required,
+            "skipped": self.skipped,
+            "detail": self.detail,
+        }
+
+
+@dataclass(frozen=True)
+class CheckReport:
+    """All check outcomes for one run."""
+
+    results: list[CheckResult]
+
+    @property
+    def ok(self) -> bool:
+        """True unless a required check ran and failed."""
+        return not any(r.blocking for r in self.results)
+
+    def to_json(self) -> dict[str, Any]:
+        return {"ok": self.ok, "checks": [r.to_json() for r in self.results]}
+
+
+def run_checks(
+    config_dir: str | Path,
+    *,
+    messages_dir: str | Path | None = None,
+    run_lint: bool = True,
+) -> CheckReport:
+    """Run the gate against ``config_dir``; ``messages_dir`` enables the dry-run check when it has
+    fixtures. Set ``run_lint=False`` to skip the advisory ruff/mypy pass."""
+    results = [_check_validate(config_dir), _check_dryrun(config_dir, messages_dir)]
+    if run_lint:
+        results.append(_run_tool("ruff", ["ruff", "check", str(config_dir)]))
+        results.append(_run_tool("mypy", ["mypy", str(config_dir)]))
+    return CheckReport(results)
+
+
+def _check_validate(config_dir: str | Path) -> CheckResult:
+    from messagefoundry.config.wiring import validate_config
+
+    errors = [d for d in validate_config(config_dir) if d.severity == "error"]
+    if errors:
+        detail = f"{len(errors)} problem(s): " + "; ".join(
+            f"{d.file or '-'}: {d.message}" for d in errors[:5]
+        )
+        return CheckResult("validate", ok=False, required=True, detail=detail)
+    return CheckResult("validate", ok=True, required=True, detail="no problems")
+
+
+def _check_dryrun(config_dir: str | Path, messages_dir: str | Path | None) -> CheckResult:
+    from messagefoundry.config.wiring import WiringError, load_config
+    from messagefoundry.pipeline.dryrun import dry_run, read_message_sets
+    from messagefoundry.store import MessageStatus
+
+    if messages_dir is None:
+        return CheckResult(
+            "dryrun", ok=True, required=False, skipped=True, detail="no fixtures dir"
+        )
+    mpath = Path(messages_dir)
+    if not mpath.exists():
+        # An explicitly-given path that doesn't exist is a mistake (renamed/typo'd fixtures dir),
+        # not "no fixtures" — fail the gate rather than silently skip the required check (low-20).
+        return CheckResult(
+            "dryrun", ok=False, required=True, detail=f"messages path not found: {mpath}"
+        )
+    if mpath.is_dir() and not any(mpath.glob("**/*.hl7")):
+        # A real dir with no fixtures (searched recursively, since per-feed fixtures live in
+        # <messages>/<inbound>/ subdirs) is the documented "absent fixtures -> skipped" case. A single
+        # file (any extension) falls through and is dry-run like the `dryrun` CLI accepts (low-20).
+        return CheckResult(
+            "dryrun", ok=True, required=False, skipped=True, detail=f"no *.hl7 fixtures in {mpath}"
+        )
+    try:
+        reg = load_config(config_dir)
+    except WiringError as exc:
+        # validate already reports (and blocks on) this — don't double-fail here.
+        return CheckResult(
+            "dryrun", ok=True, required=False, skipped=True, detail=f"config did not load: {exc}"
+        )
+    if not reg.inbound:
+        return CheckResult(
+            "dryrun", ok=True, required=False, skipped=True, detail="no inbound connections"
+        )
+
+    # Per-feed mapping (#11): a fixture under <messages>/<inbound_name>/ is dry-run only against that
+    # feed; an unmapped fixture (top-level, or under a non-feed subdir) cross-products every inbound.
+    inbound_names = list(reg.inbound)
+    message_sets = read_message_sets(mpath, inbound_names)
+    errors: list[str] = []
+    total = 0
+    pinned = 0
+    for label, _path, raw, target in message_sets:
+        targets = [target] if target is not None else inbound_names
+        if target is not None:
+            pinned += 1
+        for ic_name in targets:
+            total += 1
+            result = dry_run(reg, raw, inbound=ic_name)
+            if result.error or result.disposition is MessageStatus.ERROR:
+                errors.append(f"{label} @ {ic_name}: {result.error or result.disposition.value}")
+    if errors:
+        detail = f"{len(errors)}/{total} run(s) errored: " + "; ".join(errors[:5])
+        return CheckResult("dryrun", ok=False, required=True, detail=detail)
+    pin_note = f", {pinned} feed-pinned" if pinned else ""
+    detail = f"{total} run(s) clean across {len(message_sets)} message(s){pin_note}"
+    return CheckResult("dryrun", ok=True, required=True, detail=detail)
+
+
+def _run_tool(name: str, cmd: list[str]) -> CheckResult:
+    """Advisory: run ``cmd`` only if its executable resolves; absent → skipped, never blocking."""
+    if shutil.which(cmd[0]) is None:
+        return CheckResult(name, ok=True, required=False, skipped=True, detail="not installed")
+    try:
+        # nosec: cmd[0] is a fixed tool name (ruff/mypy), no shell; args are repo paths (low-27).
+        proc = subprocess.run(cmd, capture_output=True, text=True, check=False, timeout=120)  # nosec B603 B607
+    except subprocess.TimeoutExpired:
+        # A wedged advisory tool must not block a commit forever — degrade to a skip (low-21).
+        return CheckResult(name, ok=True, required=False, skipped=True, detail="timed out (120s)")
+    except OSError as exc:
+        return CheckResult(
+            name, ok=True, required=False, skipped=True, detail=f"could not run: {exc}"
+        )
+    if proc.returncode == 0:
+        return CheckResult(name, ok=True, required=False, detail="passed")
+    detail = (proc.stdout or proc.stderr).strip().replace("\n", " ")[:300] or "failed"
+    return CheckResult(name, ok=False, required=False, detail=detail)

messagefoundry/config/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Configuration: connector models + the code-first wiring layer.
+
+Connectors are described by :class:`Source`/:class:`Destination` (type + free-form
+``settings``). The message graph is authored code-first in
+:mod:`messagefoundry.config.wiring` — declare ``inbound``/``outbound`` Connections and
+decorate ``@router``/``@handler`` scripts; a directory of such modules loads via
+``load_config`` into a :class:`~messagefoundry.config.wiring.Registry`.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.config.models import (
+    AckMode,
+    ConnectorType,
+    Destination,
+    RetryPolicy,
+    Source,
+    Validation,
+)
+
+__all__ = [
+    "Source",
+    "Destination",
+    "Validation",
+    "RetryPolicy",
+    "ConnectorType",
+    "AckMode",
+]

messagefoundry/config/active_environment.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""The active **environment** name, readable inside a transform (per-face logic).
+
+A migrated feed sometimes branches on which deployment it is running as — e.g. stamp MSH-11 (Processing
+Id) ``P`` in production vs ``T`` in test (Corepoint's ``If #Environment[ActiveFace]="Test"``). The
+engine's single active-environment selector is ``[ai].environment`` / ``serve --env`` (a free-form
+name, ADR 0017); this module makes that name readable synchronously inside a Router or Handler via
+:func:`current_environment`.
+
+It is shaped like :mod:`messagefoundry.config.state` / :mod:`messagefoundry.config.reference`: a
+ContextVar the runner publishes around each router/transform run, read synchronously by the accessor.
+Unlike ``env()`` — which is a *deferred reference* resolved only when a **connection** spec is built
+(using it inside a handler is an always-truthy object, a bug) — :func:`current_environment` returns the
+**string** name, usable in handler control flow.
+
+**Re-run-safe.** The active environment is fixed for the life of the engine process (a crash-re-run
+restarts in the same environment; a config reload swaps the graph, not the environment), so reading it
+is deterministic — pure, and compatible with the staged-pipeline re-run invariant (ADR 0001 /
+CLAUDE.md §2). Distinct from ``env()`` *values*, which may differ per environment but are resolved at
+connection-build time, not in a transform.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any
+
+__all__ = [
+    "current_environment",
+    "set_active",
+    "reset",
+    "activated",
+]
+
+# Active environment name as a ContextVar (mirrors state._active): the runner publishes it around each
+# router/transform run so a call-time current_environment() inside a Handler resolves, and a clean
+# reset restores the prior value (no leak across runs / tests). None = "no active environment" (outside
+# a run / a dry-run with no live engine).
+_active: ContextVar[str | None] = ContextVar("mefor_active_environment", default=None)
+
+
+def set_active(name: str | None) -> Any:
+    """Publish ``name`` as the active environment and return a reset token (pass it to :func:`reset`)."""
+    return _active.set(name)
+
+
+def reset(token: Any) -> None:
+    """Restore the active environment to what it was before the matching :func:`set_active`."""
+    _active.reset(token)
+
+
+@contextmanager
+def activated(name: str | None) -> Iterator[None]:
+    """Make ``name`` the active environment for the duration of the ``with`` block, then restore.
+
+    The runner brackets each router/transform run with it, so :func:`current_environment` resolves at
+    call time and the prior value is always restored — no leak."""
+    token = _active.set(name)
+    try:
+        yield
+    finally:
+        _active.reset(token)
+
+
+def current_environment() -> str | None:
+    """The active environment name (a free-form string, e.g. ``"prod"``/``"test"``), or ``None`` outside a run.
+
+    Read it inside a Router/Handler for per-face logic::
+
+        # Corepoint: If ActiveFace="Test" Then MSH-11.1 = "T"
+        if current_environment() in ("staging", "dev"):
+            msg.set("MSH-11.1", "T")
+
+    Returns ``None`` in a dry-run / outside a run (no live engine) — a transform should default
+    sensibly (treat None as the production / leave-as-is case). The value is a deployment constant, so
+    the read is pure + re-run-safe (unlike a per-message external call)."""
+    return _active.get()

messagefoundry/config/ai_policy.py

@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""AI-assistance **policy model** — the authoritative two-axis policy and its clamping algorithm.
+
+A central operator governs how much AI coding assistance is permitted across a spectrum from
+**OFF** to **PHI-safe**, expressed as two independent axes bounded by a posture ceiling:
+
+* **mode** (:class:`AiMode`) — *whether and how* assistance runs: ``off`` (none), ``byo``
+  (the user's own provider; this extension version's only working path), or the engine-brokered
+  ``managed_claude`` / ``managed_claude_baa`` (P1/P2 — not built here, but a policy may already
+  declare them so the IDE refuses rather than silently downgrading).
+* **data_scope** (:class:`AiDataScope`) — *how sensitive* the context attached to a request may be,
+  ordered least→most sensitive: ``code_only`` < ``synthetic`` < ``deidentified`` < ``phi``.
+
+The instance's **production** posture flag imposes a ceiling on ``data_scope`` so the same config
+behaves conservatively on a non-production instance and only reaches ``phi`` on a production instance
+under a BAA mode. ``mode`` itself is never clamped — a central ``off`` is honored everywhere. Posture
+is **decoupled from the environment *name*** (ADR 0017): an instance is ``production`` (and/or
+PHI-carrying, see :class:`DataClass`) regardless of whether it is literally named ``prod`` — so an
+org can name instances ``poc``/``test``/… while choosing posture explicitly.
+
+This module is **pure** (no I/O) and imports nothing from :mod:`messagefoundry.config.settings`
+(the dependency is one-way: settings imports these enums, not the reverse, to avoid a cycle). It is
+consumed by the ``GET /ai/policy`` API endpoint and the ``messagefoundry ai-policy`` CLI, which both
+serialize :class:`EffectivePolicy` to the shared snake_case wire shape.
+
+Note: the ``deidentified`` scope depends on a de-identification framework that **does not exist in
+this repo** (roadmap only); :func:`resolve_effective_policy` therefore always clamps it down rather
+than pretending it is reachable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class AiMode(str, Enum):
+    """Whether and how AI assistance runs. The value is the wire/storage string."""
+
+    OFF = "off"  # no assistance at all
+    BYO = "byo"  # bring-your-own provider (the only working path in this MVP)
+    MANAGED_CLAUDE = "managed_claude"  # engine-brokered Claude (P1; not built here)
+    MANAGED_CLAUDE_BAA = "managed_claude_baa"  # brokered Claude under a BAA (P2; unlocks phi scope)
+
+
+class AiDataScope(str, Enum):
+    """How sensitive the context attached to an AI request may be. The value is the wire string."""
+
+    CODE_ONLY = "code_only"  # graph names + editor code only (PHI-safe by construction)
+    SYNTHETIC = "synthetic"  # plus synthetic/sample HL7
+    DEIDENTIFIED = "deidentified"  # de-identified PHI (needs the unbuilt de-id framework)
+    PHI = "phi"  # real message bodies (only over a BAA + zero-retention provider)
+
+
+class DataClass(str, Enum):
+    """Whether an instance handles real PHI, **independent of its (free-form) environment name**.
+
+    Drives the at-rest-encryption + open-egress startup advisories (a synthetic instance stays quiet;
+    a ``phi`` instance is warned). The AI data-scope ceiling keys off the separate ``production`` flag,
+    not this. Decoupling the data class from the environment name (ADR 0017) lets an org name instances
+    freely (``poc``/``test``/…) while choosing posture explicitly. The value is the wire string."""
+
+    SYNTHETIC = "synthetic"  # synthetic/sample data only — relaxed at-rest/egress posture
+    PHI = "phi"  # carries real PHI — encryption + egress advisories apply
+
+
+#: Scope ordering, least→most sensitive. Used to take the *lower* of (requested, ceiling).
+_SCOPE_ORDER: dict[AiDataScope, int] = {
+    AiDataScope.CODE_ONLY: 0,
+    AiDataScope.SYNTHETIC: 1,
+    AiDataScope.DEIDENTIFIED: 2,
+    AiDataScope.PHI: 3,
+}
+
+
+@dataclass(frozen=True)
+class EffectivePolicy:
+    """The clamped, enforceable policy returned by :func:`resolve_effective_policy`.
+
+    ``reason`` is a human-readable, ``"; "``-joined note of every clamp applied (``None`` when the
+    requested policy passed through unchanged) — surfaced in the API/CLI so an operator can see *why*
+    the effective scope differs from what was configured. The environment *name* and the posture
+    (``data_class``/``production``) are carried by the caller's wire model, not here.
+    """
+
+    mode: AiMode
+    data_scope: AiDataScope
+    reason: str | None
+
+
+def resolve_effective_policy(
+    *, mode: AiMode, data_scope: AiDataScope, production: bool
+) -> EffectivePolicy:
+    """Clamp a requested (mode, data_scope) to the enforceable effective policy for this instance.
+
+    The algorithm (in order): apply the production-posture data-scope ceiling; defensively block
+    ``phi`` unless the mode is BAA-managed; block ``deidentified`` (the de-id framework is unbuilt);
+    and normalize scope to ``code_only`` when the mode is ``off``. ``mode`` is never clamped — a
+    central ``off``/managed choice is honored regardless of posture. ``production`` is the instance's
+    posture flag (decoupled from the environment *name*, ADR 0017), not whether it is literally named
+    ``prod``.
+    """
+    reasons: list[str] = []
+
+    # 1. Posture data-scope ceiling. A non-production instance never exceeds synthetic; a production
+    #    instance reaches phi only under a BAA-managed mode, otherwise it floors at code_only.
+    if production:
+        ceiling = AiDataScope.PHI if mode is AiMode.MANAGED_CLAUDE_BAA else AiDataScope.CODE_ONLY
+    else:
+        ceiling = AiDataScope.SYNTHETIC
+
+    eff = data_scope
+    if _SCOPE_ORDER[ceiling] < _SCOPE_ORDER[eff]:
+        eff = ceiling
+        tier = "production" if production else "non-production"
+        reasons.append(f"data scope capped to {eff.value} by a {tier} instance")
+
+    # 2. phi hard rule (defensive): phi requires a BAA-managed mode. The ceiling already enforces
+    #    this on a production instance; this guards any path that reached phi outside it.
+    if eff is AiDataScope.PHI and mode is not AiMode.MANAGED_CLAUDE_BAA:
+        eff = AiDataScope.CODE_ONLY
+        reasons.append("phi scope requires managed_claude_baa mode; fell back to code_only")
+
+    # 3. deidentified hard rule: the de-id framework is roadmap only, so this scope is never live.
+    if eff is AiDataScope.DEIDENTIFIED:
+        eff = AiDataScope.CODE_ONLY
+        reasons.append(
+            "deidentified scope requires the (unbuilt) de-id framework; fell back to code_only"
+        )
+
+    # 4. off normalization: when AI is off the scope is irrelevant — pin it to the safe floor.
+    if mode is AiMode.OFF:
+        eff = AiDataScope.CODE_ONLY
+
+    return EffectivePolicy(
+        mode=mode,
+        data_scope=eff,
+        reason="; ".join(reasons) if reasons else None,
+    )