docketry 0.1.0__py3-none-any.whl

docketry/gates/notice.py

@@ -0,0 +1,59 @@
+"""Notice-parser gate: fail-loud recognition of court notification emails.
+
+Not a match at all is fine (ordinary mail just flows on). A match that cannot
+extract a field its adapter declared required is the loud failure: it means
+the source changed its template, and the message parks for a human instead of
+flowing through with silent holes.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..envelope import Envelope
+from ..pipeline import Finding, SEVERITY_FAIL, SEVERITY_INFO
+from .. import notices
+from . import register
+
+
+@register
+class NoticeParser:
+    id = "notice-parser"
+    allowed_stages = {"ingest"}
+
+    _cache: tuple[str | None, list] | None = None
+
+    def _adapters(self, options: dict) -> list:
+        adapters_file = options.get("adapters_file")
+        if adapters_file and not Path(adapters_file).exists():
+            raise notices.AdapterError(f"adapters_file not found: {adapters_file}")
+        cache = type(self)._cache
+        if cache is not None and cache[0] == adapters_file:
+            return cache[1]
+        stack = notices.stack(adapters_file)
+        type(self)._cache = (adapters_file, stack)
+        return stack
+
+    def check(self, env: Envelope, options: dict) -> list[Finding]:
+        result = notices.parse(env, self._adapters(options))
+        if result is None:
+            return []
+        findings = [
+            Finding(
+                self.id,
+                SEVERITY_INFO,
+                f"{result.notice_type} via {result.adapter}: "
+                + json.dumps(result.fields, ensure_ascii=False)[:400],
+            )
+        ]
+        for fname in result.missing:
+            findings.append(
+                Finding(
+                    self.id,
+                    SEVERITY_FAIL,
+                    f"adapter '{result.adapter}' matched but required field"
+                    f" '{fname}' did not extract — the source may have changed"
+                    " its template",
+                )
+            )
+        return findings

docketry/lint.py

@@ -0,0 +1,172 @@
+"""Brief linter: deterministic writing checks for litigation drafts.
+
+Lint drafts like code: cheap, deterministic checks run before a human spends
+review time — the human reviews findings, not raw text. Every rule here is
+an editor, not a lawyer: nothing asserts what the law is, only what the
+document does to itself.
+
+Built-in rules:
+- credibility-language: in a summary-judgment context, words that accuse the
+  other side of lying (misrepresented, concealed, intentionally, conveniently
+  omitted) invite "that's a jury question" — flagged only when the draft is
+  SJ briefing.
+- uncited-testimony: a line asserting sworn testimony with no record pin cite
+  on that line.
+- date-contradiction: the draft asserts a deadline closed/expired on a date
+  that is AFTER the draft's own certificate-of-service date.
+- reporter-spacing: So.2d/So.3d written without the space (So. 2d / So. 3d).
+
+Firm rulepacks are TOML: pattern rules with an id, message, and severity,
+validated at load. Packs are shareable the way linter configs are.
+"""
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+
+class RulepackError(ValueError):
+    pass
+
+
+@dataclass
+class LintFinding:
+    rule: str
+    severity: str    # error | warn
+    line: int        # 1-based; 0 = document-level
+    message: str
+    excerpt: str = ""
+
+
+_SJ_CONTEXT = re.compile(
+    r"summary\s+judgment|rule\s+1\.510|fed\.?\s*r\.?\s*civ\.?\s*p\.?\s*56|rule\s+56\b",
+    re.IGNORECASE,
+)
+_CREDIBILITY = re.compile(
+    r"\b(misrepresent(?:s|ed|ation|ing)?|conceal(?:s|ed|ment|ing)?|"
+    r"intentionally\s+(?:misled|omitted|hid)|conveniently\s+omit(?:s|ted)?|"
+    r"lie[sd]?\b|lying|self-serving)\b",
+    re.IGNORECASE,
+)
+_TESTIMONY = re.compile(
+    r"\b(testified|testifies|swore|sworn\s+testimony|admitted\s+(?:at|in|during)|"
+    r"stated\s+(?:at|in)\s+(?:his|her|their)\s+deposition)\b",
+    re.IGNORECASE,
+)
+_PIN_CITE = re.compile(
+    r"(\bEx(?:h)?\.\s|\bExhibit\s+[A-Z0-9]|¶|\bp\.\s*\d|\bpp\.\s*\d|"
+    r"\bat\s+\d+|\d+:\d+|\bDep\.|\bT\.\s*(?:at\s*)?\d|\bR\.\s*(?:at\s*)?\d)",
+)
+_REPORTER_SPACING = re.compile(r"\bSo\.([23])d\b")
+
+_DATE_RX = re.compile(
+    r"((?:January|February|March|April|May|June|July|August|September|October|"
+    r"November|December)\s+\d{1,2},\s+\d{4}|\d{1,2}/\d{1,2}/\d{4})"
+)
+_CLOSED_RX = re.compile(
+    r"(?:discovery|disclosure)s?\s+(?:period\s+)?(?:has\s+)?"
+    r"(?:closed|expired|ended|passed)\s+on\s+" + _DATE_RX.pattern,
+    re.IGNORECASE,
+)
+_CERT_RX = re.compile(r"certificate\s+of\s+service", re.IGNORECASE)
+
+
+def _parse_date(s: str) -> datetime | None:
+    for fmt in ("%B %d, %Y", "%m/%d/%Y"):
+        try:
+            return datetime.strptime(s, fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def _is_heading(line: str) -> bool:
+    stripped = line.strip()
+    return bool(stripped) and stripped == stripped.upper() and len(stripped) < 80
+
+
+def lint(text: str, rulepack: list[dict] | None = None) -> list[LintFinding]:
+    lines = text.splitlines()
+    findings: list[LintFinding] = []
+    sj = bool(_SJ_CONTEXT.search(text))
+
+    for n, line in enumerate(lines, start=1):
+        if _is_heading(line):
+            continue
+        if sj:
+            m = _CREDIBILITY.search(line)
+            if m and '"' not in line[: m.start()]:  # quoted testimony is fair game
+                findings.append(LintFinding(
+                    "credibility-language", "warn", n,
+                    f"'{m.group(0)}' in summary-judgment briefing invites a"
+                    " credibility question a court cannot resolve on SJ —"
+                    " recast as absence of competent evidence",
+                    line.strip()[:120],
+                ))
+        if _TESTIMONY.search(line) and not _PIN_CITE.search(line):
+            findings.append(LintFinding(
+                "uncited-testimony", "error", n,
+                "sworn-testimony assertion with no record pin cite on the line",
+                line.strip()[:120],
+            ))
+        for m in _REPORTER_SPACING.finditer(line):
+            findings.append(LintFinding(
+                "reporter-spacing", "warn", n,
+                f"'So.{m.group(1)}d' should be 'So. {m.group(1)}d'",
+                line.strip()[:120],
+            ))
+
+    closed = _CLOSED_RX.search(text)
+    if closed:
+        closed_date = _parse_date(closed.group(1))
+        cert = _CERT_RX.search(text)
+        if closed_date and cert:
+            cert_dates = _DATE_RX.findall(text[cert.start():cert.start() + 600])
+            for ds in cert_dates:
+                cert_date = _parse_date(ds)
+                if cert_date and cert_date < closed_date:
+                    findings.append(LintFinding(
+                        "date-contradiction", "error", 0,
+                        f"the draft says discovery closed on"
+                        f" {closed.group(1)} but its certificate of service"
+                        f" is dated {ds} — it asserts a past event that has"
+                        " not happened yet",
+                    ))
+                    break
+
+    for rule in rulepack or []:
+        rx = rule["_compiled"]
+        for n, line in enumerate(lines, start=1):
+            m = rx.search(line)
+            if m:
+                findings.append(LintFinding(
+                    rule["id"], rule.get("severity", "warn"), n,
+                    rule["message"], line.strip()[:120],
+                ))
+    findings.sort(key=lambda f: (f.line or 10**9, f.rule))
+    return findings
+
+
+def load_rulepack(path: str | Path) -> list[dict]:
+    data = tomllib.loads(Path(path).read_text())
+    rules = []
+    for i, r in enumerate(data.get("rule", [])):
+        rid = r.get("id")
+        if not rid:
+            raise RulepackError(f"rule #{i + 1} has no id")
+        if r.get("severity", "warn") not in ("error", "warn"):
+            raise RulepackError(f"rule '{rid}': severity must be error or warn")
+        pattern = r.get("pattern")
+        if not pattern:
+            raise RulepackError(f"rule '{rid}' has no pattern")
+        if not r.get("message"):
+            raise RulepackError(f"rule '{rid}' has no message")
+        try:
+            r["_compiled"] = re.compile(pattern, re.IGNORECASE)
+        except re.error as e:
+            raise RulepackError(f"rule '{rid}': pattern does not compile: {e}")
+        rules.append(r)
+    return rules

docketry/mailbox.py

@@ -0,0 +1,77 @@
+"""Drain a dedicated intake mailbox over IMAP.
+
+Plan-1 intake: the firm creates a mailbox that exists solely to be the port,
+points forwarding rules at it, and this module reads it with credentials the
+firm holds. Strictly read-only: the folder is opened readonly, nothing is
+marked, moved, or deleted, and a UID cursor (with UIDVALIDITY tracking) makes
+every sweep idempotent.
+"""
+from __future__ import annotations
+
+import imaplib
+from dataclasses import dataclass
+from typing import Iterator
+
+
+@dataclass
+class MailboxConfig:
+    host: str
+    user: str
+    password: str
+    folder: str = "INBOX"
+    port: int = 993
+
+
+class IntakeMailbox:
+    def __init__(self, cfg: MailboxConfig):
+        self.cfg = cfg
+        self.conn: imaplib.IMAP4_SSL | None = None
+
+    def __enter__(self) -> "IntakeMailbox":
+        self.conn = imaplib.IMAP4_SSL(self.cfg.host, self.cfg.port)
+        self.conn.login(self.cfg.user, self.cfg.password)
+        typ, _ = self.conn.select(self.cfg.folder, readonly=True)
+        if typ != "OK":
+            raise RuntimeError(f"cannot open folder {self.cfg.folder!r}")
+        return self
+
+    def __exit__(self, *exc) -> None:
+        if self.conn is not None:
+            try:
+                self.conn.logout()
+            except Exception:
+                pass
+            self.conn = None
+
+    @property
+    def label(self) -> str:
+        return f"{self.cfg.user}/{self.cfg.folder}@{self.cfg.host}"
+
+    def uidvalidity(self) -> int | None:
+        typ, data = self.conn.response("UIDVALIDITY")
+        try:
+            return int(data[0])
+        except (TypeError, ValueError, IndexError):
+            return None
+
+    def new_messages(self, last_uid: int) -> Iterator[tuple[int, bytes]]:
+        """Yield (uid, raw_rfc822) for every message with uid > last_uid."""
+        typ, data = self.conn.uid("SEARCH", None, f"UID {last_uid + 1}:*")
+        if typ != "OK" or not data or not data[0]:
+            return
+        for uid_b in data[0].split():
+            uid = int(uid_b)
+            if uid <= last_uid:
+                # IMAP quirk: "n:*" matches the highest-numbered message even
+                # when n exceeds it; skip anything we've already swept.
+                continue
+            typ, msg_data = self.conn.uid("FETCH", str(uid), "(RFC822)")
+            if typ != "OK" or not msg_data or msg_data[0] is None:
+                continue
+            raw = None
+            for part in msg_data:
+                if isinstance(part, tuple) and len(part) >= 2:
+                    raw = part[1]
+                    break
+            if raw:
+                yield uid, raw

docketry/manifest.py

@@ -0,0 +1,105 @@
+"""Load and validate the guardrail manifest (TOML).
+
+The manifest is where a firm declares its pipeline stages and which gate runs
+where. Validation is strict and load-time: unknown gates, unknown stages, a
+gate bound outside its declared allowed_stages, or a bare on_fail value all
+refuse to load — a misconfigured pipeline never runs half-enforced.
+"""
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from . import gates as gate_registry
+from .pipeline import GateBinding, ON_FAIL, Pipeline
+
+DEFAULT_MANIFEST = """\
+# Docketry guardrail manifest.
+# Stages run left to right; each [[gate]] declares where it binds, what
+# happens on failure (block | bounce | warn), and which role can approve.
+
+[pipeline]
+stages = ["ingest", "review"]
+
+[[gate]]
+id = "attachment-policy"
+binds_to = ["ingest"]
+on_fail = "bounce"
+authority = "paralegal"
+
+[gate.options]
+max_size_mb = 25
+
+[[gate]]
+id = "provenance-stamp"
+binds_to = ["ingest"]
+on_fail = "warn"
+authority = "paralegal"
+"""
+
+
+class ManifestError(ValueError):
+    pass
+
+
+def load_manifest(path: str | Path) -> Pipeline:
+    data = tomllib.loads(Path(path).read_text())
+    return build_pipeline(data)
+
+
+def build_pipeline(data: dict) -> Pipeline:
+    stages = data.get("pipeline", {}).get("stages", [])
+    if not stages or not all(isinstance(s, str) and s for s in stages):
+        raise ManifestError("[pipeline].stages must be a non-empty list of stage names")
+    if len(set(stages)) != len(stages):
+        raise ManifestError("duplicate stage names in [pipeline].stages")
+
+    bindings: list[GateBinding] = []
+    for i, g in enumerate(data.get("gate", [])):
+        gid = g.get("id")
+        if not gid:
+            raise ManifestError(f"gate #{i + 1} has no id")
+        try:
+            cls = gate_registry.get(gid)
+        except KeyError as e:
+            raise ManifestError(str(e)) from None
+
+        binds_to = g.get("binds_to", [])
+        if not binds_to:
+            raise ManifestError(f"gate '{gid}' declares no binds_to stages")
+        unknown = [s for s in binds_to if s not in stages]
+        if unknown:
+            raise ManifestError(f"gate '{gid}' binds to unknown stage(s): {unknown}")
+
+        allowed = getattr(cls, "allowed_stages", None)
+        if allowed is not None:
+            out_of_scope = [s for s in binds_to if s not in allowed]
+            if out_of_scope:
+                raise ManifestError(
+                    f"gate '{gid}' is not meant for stage(s) {out_of_scope};"
+                    f" it belongs in: {sorted(allowed)}"
+                )
+
+        on_fail = g.get("on_fail", "bounce")
+        if on_fail not in ON_FAIL:
+            raise ManifestError(
+                f"gate '{gid}' has on_fail='{on_fail}' (must be one of {ON_FAIL})"
+            )
+
+        gate = cls()
+        validator = getattr(gate, "validate_options", None)
+        if validator is not None:
+            problems = validator(g.get("options", {}))
+            if problems:
+                raise ManifestError(f"gate '{gid}' options invalid: {'; '.join(problems)}")
+
+        bindings.append(
+            GateBinding(
+                gate=gate,
+                binds_to=list(binds_to),
+                on_fail=on_fail,
+                authority=g.get("authority", "attorney"),
+                options=g.get("options", {}),
+            )
+        )
+    return Pipeline(stages=list(stages), bindings=bindings)

docketry/notices.py

@@ -0,0 +1,268 @@
+"""Court-notice parsing: adapters turn notification emails into typed notices.
+
+An adapter recognizes one source system's notification email (by sender and
+format fingerprint) and extracts its facts into a common schema. Built-in
+adapters cover the big systems; firms add their own local courts as TOML
+config — no code — and firm adapters are consulted first so a local template
+can override a built-in.
+
+Design rules, enforced here:
+- Format parsing only. An adapter that matches but cannot extract a field it
+  declared required reports the miss loudly (the gate bounces the message)
+  instead of passing a notice through with silent holes.
+- Capture, never consume. A PACER NEF's one-time "free look" document link is
+  extracted as data; nothing in this module fetches URLs, ever — an automated
+  fetch would silently burn the single free access.
+- Extraction is open; judgment is not. A hearing notice yields date, time,
+  judge, location. What lands on whose calendar is a human decision that
+  happens downstream of this code.
+"""
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .envelope import Envelope
+
+NOTICE_TYPES = ("service_notice", "filing_receipt", "hearing_notice")
+
+
+class AdapterError(ValueError):
+    """A misdeclared adapter refuses to load; it never half-parses."""
+
+
+@dataclass
+class NoticeResult:
+    adapter: str
+    notice_type: str
+    fields: dict
+    missing: list[str] = field(default_factory=list)
+
+
+def _searchable(env: Envelope) -> str:
+    return f"{env.subject}\n{env.body_text}"
+
+
+@dataclass
+class PatternAdapter:
+    """One source system: match rules + anchored field patterns.
+
+    Both built-in and TOML-defined adapters are instances of this class, so
+    a firm's config adapter has exactly the powers of a shipped one.
+    """
+
+    name: str
+    notice_type: str
+    from_endswith: tuple[str, ...] = ()
+    subject_contains: tuple[str, ...] = ()
+    body_contains: tuple[str, ...] = ()
+    fields: dict[str, re.Pattern] = field(default_factory=dict)
+    list_fields: dict[str, re.Pattern] = field(default_factory=dict)
+    required: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.notice_type not in NOTICE_TYPES:
+            raise AdapterError(
+                f"adapter '{self.name}': notice_type '{self.notice_type}'"
+                f" is not one of {NOTICE_TYPES}"
+            )
+        if not (self.from_endswith or self.subject_contains or self.body_contains):
+            raise AdapterError(f"adapter '{self.name}' declares no match rules")
+        for fname in self.required:
+            if fname not in self.fields and fname not in self.list_fields:
+                raise AdapterError(
+                    f"adapter '{self.name}' requires field '{fname}' but has no pattern for it"
+                )
+
+    def match(self, env: Envelope) -> bool:
+        sender = env.from_addr.lower()
+        if self.from_endswith and not any(sender.endswith(s.lower()) for s in self.from_endswith):
+            return False
+        subject = env.subject.lower()
+        if self.subject_contains and not any(s.lower() in subject for s in self.subject_contains):
+            return False
+        if self.body_contains:
+            body = env.body_text.lower()
+            if not any(s.lower() in body for s in self.body_contains):
+                return False
+        return True
+
+    def extract(self, env: Envelope) -> NoticeResult:
+        text = _searchable(env)
+        out: dict = {}
+        for fname, pat in self.fields.items():
+            m = pat.search(text)
+            if m:
+                out[fname] = m.group(1).strip()
+        for fname, pat in self.list_fields.items():
+            hits = [h.strip() for h in pat.findall(text) if h.strip()]
+            if hits:
+                out[fname] = hits
+        missing = [f for f in self.required if f not in out]
+        return NoticeResult(
+            adapter=self.name, notice_type=self.notice_type, fields=out, missing=missing
+        )
+
+
+def _rx(pattern: str, *, name: str, fname: str) -> re.Pattern:
+    try:
+        pat = re.compile(pattern, re.IGNORECASE | re.MULTILINE)
+    except re.error as e:
+        raise AdapterError(f"adapter '{name}': field '{fname}' pattern does not compile: {e}")
+    if pat.groups != 1:
+        raise AdapterError(
+            f"adapter '{name}': field '{fname}' pattern must have exactly one capture group"
+        )
+    return pat
+
+
+# ---------------------------------------------------------------------------
+# Built-in adapters. Template fingerprints for the major systems; formats
+# vary by district/circuit, so patterns are anchored and conservative, and a
+# firm TOML adapter can always override (firm adapters run first).
+# ---------------------------------------------------------------------------
+
+def builtin_adapters() -> list[PatternAdapter]:
+    return [
+        PatternAdapter(
+            name="fl-eportal-service",
+            notice_type="service_notice",
+            from_endswith=("@myflcourtaccess.com",),
+            subject_contains=("service of court document", "notice of service"),
+            fields={
+                "case_number": _rx(r"^\s*Case\s*(?:Number|#)\s*:?\s*([A-Z0-9-]{6,25})",
+                                   name="fl-eportal-service", fname="case_number"),
+                "case_style": _rx(r"^\s*Case Style\s*:?\s*(.+)",
+                                  name="fl-eportal-service", fname="case_style"),
+                "court": _rx(r"^\s*Court\s*:?\s*(.+)", name="fl-eportal-service", fname="court"),
+            },
+            list_fields={
+                "documents": _rx(r"^\s*Document(?:s)?\s*:?\s*(.+)$",
+                                 name="fl-eportal-service", fname="documents"),
+                "served": _rx(r"^\s*Served\s*:?\s*(.+@.+)$",
+                              name="fl-eportal-service", fname="served"),
+            },
+            required=("case_number",),
+        ),
+        PatternAdapter(
+            name="pacer-nef",
+            notice_type="service_notice",
+            from_endswith=("uscourts.gov",),
+            subject_contains=("activity in case",),
+            fields={
+                "case_number": _rx(r"Activity in Case\s+(\S+)",
+                                   name="pacer-nef", fname="case_number"),
+                "case_name": _rx(r"Activity in Case\s+\S+\s+(.+?)(?:\s{2,}|$)",
+                                 name="pacer-nef", fname="case_name"),
+                "docket_text": _rx(r"^\s*Docket Text\s*:?\s*(.+)",
+                                   name="pacer-nef", fname="docket_text"),
+                "document_number": _rx(r"^\s*Document Number\s*:?\s*(\d+)",
+                                       name="pacer-nef", fname="document_number"),
+                # Captured as data only. NEVER fetched: the NEF link is the
+                # recipient's one-time free look, and an automated fetch
+                # silently consumes it.
+                "document_link": _rx(r"(https?://ecf\.\S*uscourts\.gov/\S+)",
+                                     name="pacer-nef", fname="document_link"),
+            },
+            required=("case_number",),
+        ),
+        PatternAdapter(
+            name="jacs-hearing",
+            notice_type="hearing_notice",
+            body_contains=("judicial automated calendaring system", "jacs"),
+            fields={
+                "hearing_date": _rx(r"^\s*(?:Hearing\s+)?Date\s*:?\s*(\d{1,2}/\d{1,2}/\d{2,4})",
+                                    name="jacs-hearing", fname="hearing_date"),
+                "hearing_time": _rx(r"^\s*Time\s*:?\s*(\d{1,2}:\d{2}\s*(?:AM|PM)?)",
+                                    name="jacs-hearing", fname="hearing_time"),
+                "judge": _rx(r"^\s*Judge\s*:?\s*(.+)", name="jacs-hearing", fname="judge"),
+                "case_number": _rx(r"^\s*Case\s*(?:Number|#|No\.?)\s*:?\s*([A-Z0-9-]{6,25})",
+                                   name="jacs-hearing", fname="case_number"),
+                "matter": _rx(r"^\s*Matter\s*:?\s*(.+)", name="jacs-hearing", fname="matter"),
+            },
+            required=("hearing_date",),
+        ),
+        PatternAdapter(
+            name="jaws-hearing",
+            notice_type="hearing_notice",
+            body_contains=("judicial automated workflow system", "jaws"),
+            fields={
+                "hearing_date": _rx(r"^\s*(?:Hearing\s+)?Date\s*:?\s*(\d{1,2}/\d{1,2}/\d{2,4})",
+                                    name="jaws-hearing", fname="hearing_date"),
+                "hearing_time": _rx(r"^\s*Time\s*:?\s*(\d{1,2}:\d{2}\s*(?:AM|PM)?)",
+                                    name="jaws-hearing", fname="hearing_time"),
+                "judge": _rx(r"^\s*Judge\s*:?\s*(.+)", name="jaws-hearing", fname="judge"),
+                "case_number": _rx(r"^\s*Case\s*(?:Number|#|No\.?)\s*:?\s*([A-Z0-9-]{6,25})",
+                                   name="jaws-hearing", fname="case_number"),
+            },
+            required=("hearing_date",),
+        ),
+        PatternAdapter(
+            name="efile-receipt",
+            notice_type="filing_receipt",
+            from_endswith=("efilingmail.tylertech.cloud", "tylerhost.net"),
+            subject_contains=("filing",),
+            fields={
+                "envelope_number": _rx(r"^\s*Envelope\s*(?:Number|#)\s*:?\s*(\d+)",
+                                       name="efile-receipt", fname="envelope_number"),
+                "case_number": _rx(r"^\s*Case\s*(?:Number|#)\s*:?\s*([A-Z0-9-]{6,25})",
+                                   name="efile-receipt", fname="case_number"),
+                "status": _rx(r"\bFiling\s+(Accepted|Submitted|Rejected|Returned)\b",
+                              name="efile-receipt", fname="status"),
+                "filing_description": _rx(r"^\s*Filing\s+(?:Description|Type)\s*:?\s*(.+)",
+                                          name="efile-receipt", fname="filing_description"),
+            },
+            required=("envelope_number",),
+        ),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Firm-defined adapters: TOML in, PatternAdapter out, validated at load.
+# ---------------------------------------------------------------------------
+
+def load_adapters_file(path: str | Path) -> list[PatternAdapter]:
+    data = tomllib.loads(Path(path).read_text())
+    adapters: list[PatternAdapter] = []
+    for i, a in enumerate(data.get("adapter", [])):
+        name = a.get("name")
+        if not name:
+            raise AdapterError(f"adapter #{i + 1} has no name")
+        match = a.get("match", {})
+
+        def _tuple(val) -> tuple[str, ...]:
+            if val is None:
+                return ()
+            return (val,) if isinstance(val, str) else tuple(val)
+
+        adapters.append(
+            PatternAdapter(
+                name=name,
+                notice_type=a.get("notice_type", ""),
+                from_endswith=_tuple(match.get("from")),
+                subject_contains=_tuple(match.get("subject_contains")),
+                body_contains=_tuple(match.get("body_contains")),
+                fields={
+                    fname: _rx(pat, name=name, fname=fname)
+                    for fname, pat in a.get("fields", {}).items()
+                },
+                required=tuple(a.get("required", [])),
+            )
+        )
+    return adapters
+
+
+def parse(env: Envelope, adapters: list[PatternAdapter]) -> NoticeResult | None:
+    """First matching adapter wins; callers put firm adapters before built-ins."""
+    for adapter in adapters:
+        if adapter.match(env):
+            return adapter.extract(env)
+    return None
+
+
+def stack(adapters_file: str | Path | None = None) -> list[PatternAdapter]:
+    """Firm adapters (if any) first, then built-ins."""
+    firm = load_adapters_file(adapters_file) if adapters_file else []
+    return firm + builtin_adapters()