spot-sdk-python 2.0.0b1__tar.gz → 2.0.0b2__tar.gz

{spot_sdk_python-2.0.0b1 → spot_sdk_python-2.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b1
+Version: 2.0.0b2
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
 License: Apache-2.0
 Author: SPOT Project
@@ -49,7 +49,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b1
+pip install spot-sdk-python==2.0.0b2
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b1 → spot_sdk_python-2.0.0b2}/README.md

@@ -26,7 +26,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b1
+pip install spot-sdk-python==2.0.0b2
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b1 → spot_sdk_python-2.0.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spot-sdk-python"
-version = "2.0.0b1"
+version = "2.0.0b2"
 description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
 authors = ["SPOT Project <spot@sonn.lu>"]
 license = "Apache-2.0"

{spot_sdk_python-2.0.0b1 → spot_sdk_python-2.0.0b2}/spot_sdk/__init__.py

@@ -1,13 +1,12 @@
 """SPOT SDK: the plugin contract v2, the plugin runtime and its clients."""
 
-from .app import SyncState, create_plugin_app
-from .clients import SpotAPIError, SpotClient
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
 from .config import ConfigOption, ConfigStatus, ConfigUpdateRequest
 from .email import Address, Anomaly, AuthResult, EmailView, Envelope, Header, Part, Url
 from .errors import ErrorResponse
-from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
 from .knowledge_tags import KnowledgeTag
-from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
 from .logging import configure_logging, get_logger, get_logging_config
 from .manifest import (
     CONTRACT_VERSION,
@@ -42,6 +41,41 @@ from .workflow import (
     WorkflowStage,
 )
 
+if TYPE_CHECKING:
+    from .app import SyncState, create_plugin_app
+    from .clients import SpotAPIError, SpotClient
+    from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
+    from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
+
+# The modules that import FastAPI, Starlette or httpx load on first use, so importing
+# `spot_sdk.mime` or the models stays light (PEP 562).
+_LAZY = {
+    **dict.fromkeys(("SyncState", "create_plugin_app"), ".app"),
+    **dict.fromkeys(("SpotAPIError", "SpotClient"), ".clients"),
+    **dict.fromkeys(
+        ("KnowledgeClient", "KnowledgeDocument", "chunk_text", "content_hash"),
+        ".knowledge",
+    ),
+    **dict.fromkeys(
+        ("LLMClient", "LLMOutputError", "LLMToolCall", "LLMToolCalls", "LLMToolRound"),
+        ".llm",
+    ),
+}
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_LAZY})
+
+
 __all__ = [
     # Email view
     "Address",

spot_sdk_python-2.0.0b2/spot_sdk/_json.py

@@ -0,0 +1,46 @@
+"""Strings measured and cut by the size of their JSON.
+
+The view and the LLM client's rendering are sent as JSON, where escapes make
+a string larger than its text: a control character takes six bytes
+(``\\u0001``). ``json.dumps`` with ``ensure_ascii=False`` and pydantic's
+``model_dump_json`` escape strings alike, so sizes here are theirs.
+"""
+
+from __future__ import annotations
+
+import json
+
+_MAX_CHARACTER_BYTES = 6
+"""The most bytes one character takes: a control character's escape."""
+
+
+def json_size(text: str) -> int:
+    """The UTF-8 bytes of ``text``'s JSON string between its quotes, escapes
+    included; a lone surrogate (possible in a string built in Python) counts
+    as three."""
+    escaped = json.dumps(text, ensure_ascii=False)[1:-1]
+    return len(escaped.encode("utf-8", "surrogatepass"))
+
+
+def cut_json(text: str, max_bytes: int) -> tuple[str, bool]:
+    """The longest start of ``text`` whose JSON string takes at most
+    ``max_bytes`` bytes between its quotes (``json_size``), and whether that
+    cut anything.
+
+    A character is kept or dropped whole, so neither an escape nor a
+    character's UTF-8 bytes are split. The text is measured in chunks that
+    surely fit, a sixth of the room left each, then character by character:
+    the work follows ``max_bytes``, whatever the text's length.
+    """
+    if len(text) * _MAX_CHARACTER_BYTES <= max_bytes:
+        return text, False  # it surely fits
+    kept = 0
+    room = max_bytes
+    while kept < len(text):
+        chunk = text[kept : kept + max(room // _MAX_CHARACTER_BYTES, 1)]
+        used = json_size(chunk)
+        if used > room:  # one character, which does not fit
+            break
+        kept += len(chunk)
+        room -= used
+    return text[:kept], kept < len(text)

{spot_sdk_python-2.0.0b1 → spot_sdk_python-2.0.0b2}/spot_sdk/email.py

@@ -88,11 +88,12 @@ class Anomaly(BaseModel):
     code: str = Field(description="One of the spot_sdk.mime anomaly codes")
     location: str | None = Field(
         default=None,
-        description='"part:1.2", "header:Subject@1", "param:Content-Type.boundary@1.2", ...',
+        description='"part:1.2", "header:Subject@1", "param:Content-Type.boundary@1.2",'
+        ' ..., "envelope", "source": at most 200 bytes of JSON',
     )
     detail: str | None = Field(
         default=None,
-        description="The values concerned, as JSON strings: at most 200 characters",
+        description="The values concerned, as JSON strings: at most 200 bytes of JSON",
     )
 
 
@@ -118,7 +119,8 @@ class EmailView(BaseModel):
     sha256: str = Field(description="Of the raw message")
     envelope: Envelope | None = None
     headers: list[Header] = Field(
-        description="Every header, in order, X-SPOT-* removed"
+        description="The headers in order, within their budget, X-SPOT-* removed;"
+        " those left out are noted as header_limit"
     )
     subject: str = ""
     from_: Address | None = Field(default=None, alias="from")

{spot_sdk_python-2.0.0b1 → spot_sdk_python-2.0.0b2}/spot_sdk/llm.py

@@ -35,7 +35,6 @@ from __future__ import annotations
 
 import json
 import secrets
-from bisect import bisect_right
 from collections.abc import Mapping, Sequence
 from datetime import UTC, datetime
 from typing import Any, Self, TypeVar, overload
@@ -51,6 +50,7 @@ from pydantic import (
     model_validator,
 )
 
+from ._json import cut_json
 from .clients import json_body
 from .email import EmailView
 
@@ -417,18 +417,9 @@ def _cap(value: Any) -> tuple[Any, bool]:
 
 
 def _cap_text(text: str) -> tuple[str, bool]:
-    """The longest start of ``text`` whose JSON form, as ``json.dumps`` writes
-    it with escapes, takes at most ``_STRING_BYTES`` UTF-8 bytes between its
-    quotes, and whether that cut anything. A character is kept or dropped
-    whole, a lone surrogate counting as three bytes. The work is bounded
-    whatever the text's length: no character takes less than a byte."""
-    head = text[:_STRING_BYTES]
-    kept = bisect_right(
-        range(1, len(head) + 1),
-        _STRING_BYTES,
-        key=lambda end: _size(json.dumps(head[:end], ensure_ascii=False)) - 2,
-    )
-    return head[:kept], kept < len(text)
+    """``text`` cut to ``_STRING_BYTES`` of JSON (``cut_json``), and whether
+    that cut anything."""
+    return cut_json(text, _STRING_BYTES)
 
 
 _IDENTITY_FIELDS = ("from", "reply_to", "subject")

{spot_sdk_python-2.0.0b1 → spot_sdk_python-2.0.0b2}/spot_sdk/mime.py

@@ -21,7 +21,9 @@ Anyone can send a message, so the parser never fails on its content:
   header values are cut at ``max_text_bytes``, and at most ``MAX_URLS`` URLs
   are kept. Each bound hit is an anomaly; the ones that leave content out set
   ``EmailView.truncated``. At most ``MAX_ANOMALIES`` anomalies are recorded,
-  ``MAX_ANOMALIES_PER_CODE`` of each code, but always the first of each.
+  ``MAX_ANOMALIES_PER_CODE`` of each code, but always the first of each;
+- the view is bounded: its JSON takes at most ``MAX_VIEW_BYTES``, the sum of
+  the budgets of its lists and long strings (see :func:`parse`).
 
 The standard library builds the MIME tree with the ``compat32`` policy, whose
 headers are plain strings: the ``default`` policy parses each header it reads
@@ -41,7 +43,7 @@ import json
 import math
 import re
 from array import array
-from collections import Counter
+from collections import Counter, defaultdict
 from collections.abc import Collection, Iterable, Iterator
 from dataclasses import dataclass
 from datetime import datetime
@@ -49,13 +51,16 @@ from email.message import Message
 from email.policy import Compat32, Policy, compat32
 from email.utils import decode_params, getaddresses, parsedate_to_datetime, unquote
 from html import unescape as unescape_html
-from itertools import chain, islice
-from typing import Any, Literal, NamedTuple, TypeAlias, cast
+from itertools import chain
+from typing import Any, Literal, NamedTuple, TypeAlias, TypeVar, cast
 from urllib.parse import urlsplit
 from uuid import UUID
 
+from pydantic import BaseModel
+from pydantic_core import to_json
 from selectolax.lexbor import LexborHTMLParser, LexborNode
 
+from ._json import cut_json, json_size
 from .email import (
     Address,
     Anomaly,
@@ -77,6 +82,33 @@ MAX_BOUNDARY_LENGTH = 1_000
 MAX_ANOMALIES = 1_000
 MAX_ANOMALIES_PER_CODE = 100
 MAX_URLS = 10_000
+# The view's budgets, in bytes of its JSON as model_dump_json(by_alias=True)
+# writes it: UTF-8, escapes included. A list keeps its first entries within
+# its budget (the headers each one that fits), a string its start; each cut is
+# an anomaly.
+MAX_TEXT_BYTES = 1 << 20  # the text, the HTML and the visible text, each
+MAX_HEADERS_BYTES = 1 << 20
+MAX_PARTS_BYTES = 1 << 20
+MAX_URLS_BYTES = 1 << 20
+_URL_BYTES = 8 << 10  # each URL
+_SUBJECT_BYTES = 16 << 10
+# Each other string of an entry or a field: a part's, a URL's host and anchor
+# text, an address's, a message id, a reference, an authentication result's,
+# the envelope's, the source.
+_STRING_BYTES = 1 << 10
+# Each list of a field: reply_to, to, cc, references, authentication, and the
+# envelope's rcpt_to.
+_LIST_BYTES = 64 << 10
+# An anomaly's location and detail, each; the detail reads that many
+# characters of each value.
+_MAX_DETAIL = 200
+# The fields read from the headers, the envelope and the source: the subject,
+# six lists, and ten strings (the sender's three, two message ids, the
+# envelope's four, the source).
+MAX_FIELDS_BYTES = _SUBJECT_BYTES + 6 * _LIST_BYTES + 10 * _STRING_BYTES
+# The keys, the punctuation and the fields of fixed size: the id, the dates,
+# the sizes, the digest and truncated.
+_FIXED_BYTES = 1 << 10
 # The HTML budget, checked before the tree is built (_html_budget). Lexbor, as
 # the HTML standard, never caps the tree, and some of its work is quadratic:
 # each tag or comment makes nodes to walk; a tag may walk the whole stack of
@@ -124,11 +156,19 @@ boundaries: mail clients may split it either way."""
 DEPTH_LIMIT = "depth_limit"
 """Nesting goes deeper than MAX_DEPTH: the deeper parts are not read."""
 HEADER_LIMIT = "header_limit"
-"""A part has more than MAX_HEADERS headers: the later ones are not read."""
+"""A part has more than MAX_HEADERS headers: the later ones are not kept, but
+the view's fields are still read from them. Or a header does not fit the room
+left in MAX_HEADERS_BYTES: it is left out of the view's headers, but the
+fields read from it are not."""
 PART_LIMIT = "part_limit"
-"""The message has more than MAX_PARTS parts: the later ones are not read."""
+"""The message has more than MAX_PARTS parts: the later ones are not read. Or
+its parts take more than MAX_PARTS_BYTES: the later ones are left out of the
+view's parts, but they are read."""
 TEXT_TRUNCATED = "text_truncated"
-"""The text, the HTML or a header value was cut at max_text_bytes."""
+"""A string was cut at its budget: the text, the HTML or the visible text at
+max_text_bytes of JSON (noted at their part), a header value at max_text_bytes
+bytes or a field read from it (at the header), a string of a part (at the
+part), the envelope or the source."""
 HEADER_DUPLICATE = "header_duplicate"
 """A part has more than one Content-Type, Content-Disposition,
 Content-Transfer-Encoding or MIME-Version header: the first one counts."""
@@ -150,7 +190,9 @@ HTML_STYLE_UNRESOLVED = "html_style_unresolved"
 known when rendering (var(), env(), attr(), a calc() that is not a literal):
 the text was kept visible. The detail names the properties."""
 URL_LIMIT = "url_limit"
-"""The message has more than MAX_URLS URLs: the later ones are not recorded."""
+"""The message has more than MAX_URLS URLs, or they take more than
+MAX_URLS_BYTES: the later ones are not recorded. Or a URL was cut at 8 KiB of
+JSON, or its host or anchor text at 1 KiB."""
 ANOMALY_LIMIT = "anomaly_limit"
 """More than MAX_ANOMALIES anomalies were met: the later ones are not recorded."""
 ANOMALY_CODES = (
@@ -175,6 +217,30 @@ ANOMALY_CODES = (
 )
 """Every anomaly code, in the order above."""
 
+# The anomalies, and the one that says more were met: each with the longest
+# code, a location and a detail, and a comma.
+MAX_ANOMALIES_BYTES = (MAX_ANOMALIES + 1) * (
+    len(
+        Anomaly(
+            code=max(ANOMALY_CODES, key=len), location="", detail=""
+        ).model_dump_json()
+    )
+    + 2 * _MAX_DETAIL
+    + 1
+) + 1
+# The most bytes the view's JSON takes, whatever the message, with
+# max_text_bytes at most its default: the sum of the budgets, about 6.84 MiB.
+# Core refuses a view over 8 MiB.
+MAX_VIEW_BYTES = (
+    _FIXED_BYTES
+    + 3 * MAX_TEXT_BYTES
+    + MAX_HEADERS_BYTES
+    + MAX_PARTS_BYTES
+    + MAX_URLS_BYTES
+    + MAX_FIELDS_BYTES
+    + MAX_ANOMALIES_BYTES
+)
+
 _ENCODED_WORD = re.compile(r"=\?([^?\s]+)\?([bq])\?([^?\s]*)\?=", re.IGNORECASE)
 _URL = re.compile(r"\b(?:https?://|www\.)[^\s<>\"'`]+", re.IGNORECASE)
 _URL_TRAILER = ".,;:!?)]}'\""
@@ -205,7 +271,10 @@ _BASE64_RUN = re.compile(rb"([A-Za-z0-9+/]+)|(=+)")
 _STRUCTURAL_HEADERS = frozenset(
     {"content-type", "content-disposition", "content-transfer-encoding", "mime-version"}
 )
-_MAX_DETAIL = 200
+# The headers the view reads a field from: the first of each name.
+_FIELD_HEADERS = frozenset(
+    "subject from reply-to to cc date message-id in-reply-to references".split()
+)
 _DISPOSITIONS: dict[str | None, Literal["inline", "attachment"]] = {
     "inline": "inline",
     "attachment": "attachment",
@@ -422,21 +491,56 @@ def parse(
     received_at: datetime,
     envelope: Envelope | None = None,
     trusted_authserv_ids: Collection[str] = (),
-    max_text_bytes: int = 1 << 20,
+    max_text_bytes: int = MAX_TEXT_BYTES,
 ) -> EmailView:
     """Parse a raw RFC 5322 message into the email view.
 
     ``trusted_authserv_ids`` are the authserv-ids of our own MTAs: only their
     ``Authentication-Results`` count. ``max_text_bytes`` caps the text, the
-    HTML and each header value.
+    HTML and the visible text, each in bytes of its JSON (escapes included),
+    and each header value in bytes. The text and the HTML are read from at
+    most that many bytes of their part, and their URLs and the visible text
+    from all of what was read, not from the cut the view stores.
+
+    The view's JSON (``model_dump_json(by_alias=True)``, in UTF-8) takes at
+    most ``MAX_VIEW_BYTES``, about 6.84 MiB, whatever the message, with
+    ``max_text_bytes`` at most its default. Each list and each long string has
+    a budget, in bytes of its JSON, escapes included:
+
+    - the text, the HTML and the visible text: ``MAX_TEXT_BYTES`` (1 MiB) each;
+    - the headers, the parts and the URLs: ``MAX_HEADERS_BYTES``,
+      ``MAX_PARTS_BYTES`` and ``MAX_URLS_BYTES`` (1 MiB each); each URL 8 KiB,
+      and each other string of a part or a URL 1 KiB;
+    - the fields read from the headers, the envelope and the source:
+      ``MAX_FIELDS_BYTES`` (410 KiB). The subject takes 16 KiB, each other
+      string 1 KiB, and each list (``reply_to``, ``to``, ``cc``,
+      ``references``, ``authentication``, the envelope's ``rcpt_to``) 64 KiB;
+    - the anomalies: ``MAX_ANOMALIES_BYTES`` (about 450 KiB), each location
+      and detail 200 bytes;
+    - the keys and the fields of fixed size: 1 KiB.
+
+    A list keeps its first entries, but the headers each one that fits the
+    room left; a string keeps its start, and no value is altered. The fields
+    read from the headers come from the first header of each name in the
+    whole header block, past ``MAX_HEADERS`` too, whatever headers the list
+    keeps. Each cut sets ``truncated`` and is an anomaly: ``text_truncated``
+    for a string, ``header_limit``, ``part_limit`` or ``url_limit`` for a
+    list (a URL cut is ``url_limit`` too).
     """
     root = _read(raw)
     nodes, left_out = _walk(root, budget=len(raw))
     _note_ambiguous_boundaries(nodes)
     fields, cut_headers = _fields(root, max_text_bytes)
-    first: dict[str, str] = {}
-    for name, value in fields:
-        first.setdefault(name.lower(), value)
+    read, cut_from = _header_fields(
+        root.firsts,
+        fields,
+        {authserv_id.lower() for authserv_id in trusted_authserv_ids},
+        max_text_bytes,
+    )
+    given = {"source": _Cutter(), "envelope": _Cutter()}
+    source = given["source"](source)
+    if envelope is not None:
+        envelope = _envelope(envelope, given["envelope"])
 
     parts: list[Part] = []
     bodies: dict[str, _Body] = {}
@@ -451,44 +555,68 @@ def parse(
             and part.disposition != "attachment"
             and not node.enclosed
         ):
-            content = _decode_text(data[:max_text_bytes], part.charset)
+            # The charset as written: a cut one may name another codec.
+            charset = _param(node.part, "charset")
+            content = _decode_text(data[:max_text_bytes], charset)
             bodies[part.content_type] = _Body(part.part_id, node.part, content)
             if len(data) > max_text_bytes:
-                node.part.note(TEXT_TRUNCATED)
+                node.part.note_cut()
 
+    # The URLs and the visible text are read from the whole decoded bodies;
+    # the view stores each body cut to its budget.
     text = bodies.get("text/plain")
     html = bodies.get("text/html")
-    found = [_header_urls(fields)]  # the URLs, built as they are kept
+    cut_urls = _Cutter()
+    found = [_header_urls(fields, cut_urls)]  # the URLs, built as they are kept
     if text:
-        found.append(_urls_in(text.content, "text", text.part_id))
-    visible_text = text.content if text and text.content.strip() else ""
+        found.append(_urls_in(text.content, "text", text.part_id, cut_urls))
+    shown = text if text and text.content.strip() else None  # the visible text's
+    visible_text = shown.content if shown else ""
     if html:
         reader = _read_html(html.content)
-        found.append(_html_urls(reader.links, html.part_id))
+        found.append(_html_urls(reader.links, html.part_id, cut_urls))
         html_text = reader.text
-        found.append(_urls_in(html_text, "html_text", html.part_id))
-        visible_text = visible_text or html_text
+        found.append(_urls_in(html_text, "html_text", html.part_id, cut_urls))
+        if shown is None:
+            shown, visible_text = html, html_text
         if reader.hidden_text:
             html.part.note(HTML_HIDDEN_TEXT)
         if reader.limit:
             html.part.note(HTML_LIMIT, None, reader.limit)
         if reader.unresolved:
             html.part.note(HTML_STYLE_UNRESOLVED, None, *sorted(reader.unresolved))
-    # Each note with the id of its part: the header ones are the message's.
-    notes = [(_Note(TEXT_TRUNCATED, subject), "1") for subject in cut_headers]
+    stored_text = _cut_body(text, text.content, max_text_bytes) if text else None
+    stored_html = _cut_body(html, html.content, max_text_bytes) if html else None
+    if shown:
+        visible_text = _cut_body(shown, visible_text, max_text_bytes)
+    # Each note with the id of its part: the header ones are the message's,
+    # once per header; the source and the envelope are no part's.
+    notes: list[tuple[_Note, str | None]] = [
+        (_Note(TEXT_TRUNCATED, subject), "1")
+        for subject in dict.fromkeys(cut_headers + cut_from)
+    ]
+    notes += [
+        (_Note(TEXT_TRUNCATED, name), None) for name, cut in given.items() if cut.cut
+    ]
     notes += [(note, node.part_id) for node in nodes for note in node.part.notes]
+    parts, left_out_part = _listed(parts, MAX_PARTS_BYTES)
+    if left_out_part is not None:
+        notes.append((_Note(PART_LIMIT), left_out_part.part_id))
     if left_out:
         notes.append((_Note(PART_LIMIT), left_out))
-    urls = list(islice(chain.from_iterable(found), MAX_URLS + 1))
-    if len(urls) > MAX_URLS:
-        urls.pop()
+    urls, left_out_url = _listed(
+        chain.from_iterable(found), MAX_URLS_BYTES, limit=MAX_URLS
+    )
+    if left_out_url is not None or cut_urls.cut:
         notes.append((_Note(URL_LIMIT), "1"))
+    headers, header_left_out = _headers(fields)
+    if header_left_out:
+        notes.append((_Note(HEADER_LIMIT), "1"))
     kept = _kept(notes)
     anomalies = [_anomaly(note, part_id) for note, part_id in kept]
     if len(kept) < len(notes):
         anomalies.append(Anomaly(code=ANOMALY_LIMIT))
 
-    senders = _addresses(first.get("from", ""))
     return EmailView(
         id=email_id,
         received_at=received_at,
@@ -496,26 +624,20 @@ def parse(
         size_bytes=len(raw),
         sha256=hashlib.sha256(raw).hexdigest(),
         envelope=envelope,
-        headers=[
-            Header(name=name, value=_decode_words(value))
-            for name, value in fields
-            if not name.lower().startswith("x-spot-")
-        ],
-        subject=_decode_words(first.get("subject", "")),
-        from_=senders[0] if senders else None,
-        reply_to=_addresses(first.get("reply-to", "")),
-        to=_addresses(first.get("to", "")),
-        cc=_addresses(first.get("cc", "")),
-        date=_date(first.get("date", "")),
-        message_id=first.get("message-id", "").strip() or None,
-        in_reply_to=first.get("in-reply-to", "").strip() or None,
-        references=_MESSAGE_ID.findall(first.get("references", "")),
-        authentication=_authentication(
-            fields, {authserv_id.lower() for authserv_id in trusted_authserv_ids}
-        ),
+        headers=headers,
+        subject=read.subject,
+        from_=read.from_,
+        reply_to=read.reply_to,
+        to=read.to,
+        cc=read.cc,
+        date=read.date,
+        message_id=read.message_id,
+        in_reply_to=read.in_reply_to,
+        references=read.references,
+        authentication=read.authentication,
         parts=parts,
-        text=text.content if text else None,
-        html=html.content if html else None,
+        text=stored_text,
+        html=stored_html,
         visible_text=visible_text,
         urls=urls,
         truncated=any(note.code in _LIMIT_CODES for note, _ in notes),
@@ -536,6 +658,86 @@ def part_bytes(raw: bytes, part_id: str) -> tuple[bytes, str]:
     raise PartNotFoundError(part_id)
 
 
+# ----------------------------------------------------------------------- #
+# The view's budgets
+# ----------------------------------------------------------------------- #
+
+
+_Entry = TypeVar("_Entry", bound=BaseModel | str)
+
+
+def _listed(
+    entries: Iterable[_Entry], budget: int, limit: int | None = None
+) -> tuple[list[_Entry], _Entry | None]:
+    """The first ``entries``, at most ``limit``, whose JSON array takes at
+    most ``budget`` bytes; and the first one left out, if any. Each entry is
+    measured as it comes, so the work stops at the budget."""
+    kept: list[_Entry] = []
+    size = 1  # "[", then each entry and the "," or "]" after it
+    for entry in entries:
+        size += _size(entry) + 1
+        if size > budget or len(kept) == limit:
+            return kept, entry
+        kept.append(entry)
+    return kept, None
+
+
+def _headers(fields: list[tuple[str, str]]) -> tuple[list[Header], bool]:
+    """The headers in order, without ``X-SPOT-*``, each kept if it fits the
+    room left in ``MAX_HEADERS_BYTES``; and whether one was left out.
+
+    A header that does not fit is left out alone, so one long header does not
+    hide the ones after it. A character takes a byte at least: a header whose
+    name and decoded value are longer than the room left is left out without
+    measuring it.
+    """
+    headers: list[Header] = []
+    left_out = False
+    room = MAX_HEADERS_BYTES - 1  # "[", then each entry and the "," or "]" after it
+    for name, value in fields:
+        if name.lower().startswith("x-spot-"):
+            continue
+        value = _decode_words(value)
+        if len(name) + len(value) < room:
+            header = Header(name=name, value=value)
+            size = _size(header) + 1
+            if size <= room:
+                headers.append(header)
+                room -= size
+                continue
+        left_out = True
+    return headers, left_out
+
+
+class _Cutter:
+    """Cuts strings to their budget, and remembers whether it cut one."""
+
+    def __init__(self) -> None:
+        self.cut = False
+
+    def __call__(self, text: str, max_bytes: int = _STRING_BYTES) -> str:
+        text, cut = cut_json(text, max_bytes)
+        self.cut = self.cut or cut
+        return text
+
+    def optional(self, text: str | None) -> str | None:
+        return None if text is None else self(text)
+
+    def listed(self, entries: Iterable[_Entry]) -> list[_Entry]:
+        """The first entries within ``_LIST_BYTES``; a list cut short counts as
+        a cut."""
+        kept, left_out = _listed(entries, _LIST_BYTES)
+        self.cut = self.cut or left_out is not None
+        return kept
+
+
+def _size(value: BaseModel | str) -> int:
+    """The bytes of a value's JSON, as the view's."""
+    if isinstance(value, str):
+        return json_size(value) + 2  # and its quotes
+    return len(to_json(value, by_alias=True))
+
+
 # ----------------------------------------------------------------------- #
 # The MIME tree
 # ----------------------------------------------------------------------- #
@@ -556,14 +758,24 @@ class _Part(Message):
     candidates: list[str] | None = None  # usable boundaries, preferred first
     raw_body: str | None = None  # as read, raw bytes as surrogate escapes
     headers_dropped = False
+    content_cut = False
 
     def __init__(self, policy: Policy[Any] = compat32) -> None:
         super().__init__(policy)
         self.notes: list[_Note] = []
+        # By lower-cased name, the first header of each _FIELD_HEADERS name as
+        # read (name, raw value): past MAX_HEADERS too.
+        self.firsts: dict[str, tuple[str, str]] = {}
 
     def note(self, code: str, subject: str | None = None, *values: str) -> None:
         self.notes.append(_Note(code, subject, values))
 
+    def note_cut(self) -> None:
+        """Note, once, that content read from this part was cut at its budget."""
+        if not self.content_cut:
+            self.content_cut = True
+            self.note(TEXT_TRUNCATED)
+
     def attach(self, payload: Message | str) -> None:
         if isinstance(payload, _Part):
             payload.depth = self.depth + 1
@@ -576,6 +788,9 @@ class _Part(Message):
         super().set_payload(payload, charset)
 
     def set_raw(self, name: str, value: str) -> None:
+        key = name.lower()
+        if key in _FIELD_HEADERS:
+            self.firsts.setdefault(key, (name, value))
         if len(self) < MAX_HEADERS:
             super().set_raw(name, value)
         elif not self.headers_dropped:
@@ -662,6 +877,15 @@ class _Body:
     content: str
 
 
+def _cut_body(body: _Body, content: str, max_bytes: int) -> str:
+    """``content`` read from a body, cut to ``max_bytes`` of JSON; a cut is
+    noted on the body's part."""
+    content, cut = cut_json(content, max_bytes)
+    if cut:
+        body.part.note_cut()
+    return content
+
+
 def _read(raw: bytes) -> _Part:
     return cast(_Part, email.message_from_bytes(raw, policy=_POLICY))
 
@@ -832,22 +1056,27 @@ def _decode_base64(text: str) -> tuple[bytes, str]:
 
 
 def _describe(node: _Node, data: bytes) -> Part:
+    """A part as the view lists it, each string cut to ``_STRING_BYTES``."""
     part = node.part
     charset = _param(part, "charset")
     filename = _param(part, "filename", "content-disposition")
     name = _param(part, "name")
     if filename and name and filename != name:
         part.note(PARAM_CONFLICT, "param:Content-Disposition.filename", filename, name)
-    return Part(
+    cut = _Cutter()
+    described = Part(
         part_id=node.part_id,
-        content_type=_content_type(part),
-        charset=charset.lower() if charset else None,
+        content_type=cut(_content_type(part)),
+        charset=cut.optional(charset.lower() if charset else None),
         disposition=_DISPOSITIONS.get(part.get_content_disposition()),
-        filename=filename or name,
-        content_id=_clean(part.get("content-id") or "").strip() or None,
+        filename=cut.optional(filename or name),
+        content_id=cut.optional(_clean(part.get("content-id") or "").strip() or None),
         size_bytes=len(data),
         sha256=None if part.is_multipart() else hashlib.sha256(data).hexdigest(),
     )
+    if cut.cut:
+        part.note_cut()
+    return described
 
 
 def _content_type(part: _Part) -> str:
@@ -1081,15 +1310,23 @@ def _fields(message: _Part, limit: int) -> tuple[list[tuple[str, str]], list[str
     for name, raw_value in message.items():
         key = name.lower()
         seen[key] += 1
-        value = _clean(raw_value)
-        data = value.encode()
-        if len(data) > limit:
-            value = data[:limit].decode(errors="ignore")
+        value, was_cut = _header_value(raw_value, limit)
+        if was_cut:
             cut.append(_header_subject(name, seen[key]))
         fields.append((name, value))
     return fields, cut
 
 
+def _header_value(raw_value: str, limit: int) -> tuple[str, bool]:
+    """A header value as the view reads it, cut at ``limit`` bytes; and
+    whether it was cut."""
+    value = _clean(raw_value)
+    data = value.encode()
+    if len(data) > limit:
+        return data[:limit].decode(errors="ignore"), True
+    return value, False
+
+
 def _note_repeated_headers(part: _Part) -> None:
     """Note each structural header a part gives again: the first one counts."""
     seen: Counter[str] = Counter()
@@ -1109,7 +1346,9 @@ def _header_subject(name: str, occurrence: int) -> str:
     return f"header:{name}[{occurrence}]" if occurrence > 1 else f"header:{name}"
 
 
-def _kept(notes: list[tuple[_Note, str]]) -> list[tuple[_Note, str]]:
+def _kept(
+    notes: list[tuple[_Note, str | None]],
+) -> list[tuple[_Note, str | None]]:
     """The notes recorded, in order: the first of each code, then the others
     while their code has fewer than ``MAX_ANOMALIES_PER_CODE``, and all fewer
     than ``MAX_ANOMALIES``. Cheap, common notes do not push out rare ones."""
@@ -1118,7 +1357,7 @@ def _kept(notes: list[tuple[_Note, str]]) -> list[tuple[_Note, str]]:
         first.setdefault(note.code, index)
     room = MAX_ANOMALIES - len(first)  # for the notes after the first of a code
     counts: Counter[str] = Counter()
-    kept: list[tuple[_Note, str]] = []
+    kept: list[tuple[_Note, str | None]] = []
     for index, (note, part_id) in enumerate(notes):
         if index != first[note.code]:
             if not room or counts[note.code] >= MAX_ANOMALIES_PER_CODE:
@@ -1129,18 +1368,20 @@ def _kept(notes: list[tuple[_Note, str]]) -> list[tuple[_Note, str]]:
     return kept
 
 
-def _anomaly(note: _Note, part_id: str) -> Anomaly:
+def _anomaly(note: _Note, part_id: str | None) -> Anomaly:
     """An anomaly as the view carries it: its values JSON-quoted in the detail."""
     detail = ", ".join(
         json.dumps(_clean(value[:_MAX_DETAIL]), ensure_ascii=False)
         for value in note.values
     )
+    if part_id is None:
+        location = note.subject
+    else:
+        location = f"{note.subject}@{part_id}" if note.subject else f"part:{part_id}"
     return Anomaly(
         code=note.code,
-        location=_clean(
-            f"{note.subject}@{part_id}" if note.subject else f"part:{part_id}"
-        ),
-        detail=detail[:_MAX_DETAIL] or None,
+        location=cut_json(_clean(location), _MAX_DETAIL)[0] if location else None,
+        detail=cut_json(detail, _MAX_DETAIL)[0] or None,
     )
 
 
@@ -1159,20 +1400,21 @@ def _domain(host: str) -> str:
         return host
 
 
-def _addresses(value: str) -> list[Address]:
-    """The mailboxes of an address header; a value that does not parse is kept whole."""
+def _addresses(value: str, cut: _Cutter) -> Iterator[Address]:
+    """The mailboxes of an address header, each string cut to its budget; a
+    value that does not parse is kept whole."""
     mailboxes = getaddresses([value])
     if not mailboxes or not all("@" in address for _, address in mailboxes):
         value = value.strip()
-        return [Address(address=value)] if value else []
-    return [
-        Address(
-            display_name=_decode_words(name),
-            address=address,
-            domain=_domain(address.rpartition("@")[2]),
+        if value:
+            yield Address(address=cut(value))
+        return
+    for name, address in mailboxes:
+        yield Address(
+            display_name=cut(_decode_words(name)),
+            address=cut(address),
+            domain=cut(_domain(address.rpartition("@")[2])),
         )
-        for name, address in mailboxes
-    ]
 
 
 def _date(value: str) -> datetime | None:
@@ -1182,6 +1424,86 @@ def _date(value: str) -> datetime | None:
         return None
 
 
+class _HeaderFields(NamedTuple):
+    """The view's fields read from the headers."""
+
+    subject: str
+    from_: Address | None
+    reply_to: list[Address]
+    to: list[Address]
+    cc: list[Address]
+    date: datetime | None
+    message_id: str | None
+    in_reply_to: str | None
+    references: list[str]
+    authentication: list[AuthResult]
+
+
+def _header_fields(
+    firsts: dict[str, tuple[str, str]],
+    fields: list[tuple[str, str]],
+    trusted: set[str],
+    limit: int,
+) -> tuple[_HeaderFields, list[str]]:
+    """The view's fields read from the first header of each name (``firsts``,
+    the whole header block's, each value cut at ``limit`` bytes), and the
+    authentication results from the trusted headers on top: within their
+    budgets. Each string is cut to ``_STRING_BYTES``, the subject to
+    ``_SUBJECT_BYTES``, and each list to ``_LIST_BYTES``.
+
+    Also the headers a field was cut from, as ``header:`` subjects.
+    """
+    # By lower-cased name: the name as written, and the value.
+    first: dict[str, tuple[str, str]] = {}
+    cuts: defaultdict[str, _Cutter] = defaultdict(_Cutter)  # by header
+    for key, (name, raw_value) in firsts.items():
+        value, cut = _header_value(_POLICY.header_fetch_parse(name, raw_value), limit)
+        first[key] = (name, value)
+        cuts[key].cut = cut
+
+    def header(name: str) -> str:
+        return first.get(name, ("", ""))[1]
+
+    def addresses(name: str) -> list[Address]:
+        return cuts[name].listed(_addresses(header(name), cuts[name]))
+
+    def message_id(name: str) -> str | None:
+        return cuts[name](header(name).strip()) or None
+
+    authentication, authentication_cut = _authentication(fields, trusted)
+    read = _HeaderFields(
+        subject=cuts["subject"](_decode_words(header("subject")), _SUBJECT_BYTES),
+        from_=next(_addresses(header("from"), cuts["from"]), None),
+        reply_to=addresses("reply-to"),
+        to=addresses("to"),
+        cc=addresses("cc"),
+        date=_date(header("date")),
+        message_id=message_id("message-id"),
+        in_reply_to=message_id("in-reply-to"),
+        references=cuts["references"].listed(
+            cuts["references"](reference.group())
+            for reference in _MESSAGE_ID.finditer(header("references"))
+        ),
+        authentication=authentication,
+    )
+    cut_from = [
+        _header_subject(first[name][0], 1) for name, cut in cuts.items() if cut.cut
+    ]
+    return read, cut_from + ([authentication_cut] if authentication_cut else [])
+
+
+def _envelope(envelope: Envelope, cut: _Cutter) -> Envelope:
+    """The SMTP envelope within its budgets: each string cut to
+    ``_STRING_BYTES``, ``rcpt_to`` to ``_LIST_BYTES``."""
+    return Envelope(
+        mail_from=cut.optional(envelope.mail_from),
+        rcpt_to=cut.listed(cut(recipient) for recipient in envelope.rcpt_to),
+        client_address=cut.optional(envelope.client_address),
+        client_name=cut.optional(envelope.client_name),
+        helo=cut.optional(envelope.helo),
+    )
+
+
 # ----------------------------------------------------------------------- #
 # Authentication-Results (RFC 8601)
 # ----------------------------------------------------------------------- #
@@ -1189,46 +1511,68 @@ def _date(value: str) -> datetime | None:
 
 def _authentication(
     fields: list[tuple[str, str]], trusted: set[str]
-) -> list[AuthResult]:
-    """The results of the trusted headers above the first untrusted one.
+) -> tuple[list[AuthResult], str | None]:
+    """The results of the trusted headers above the first untrusted one,
+    within ``_LIST_BYTES``, each string cut to ``_STRING_BYTES``; and the
+    header the first cut is in, as a ``header:`` subject, if any.
 
     Our MTAs add their headers on top, so only that run is theirs: a trusted
     authserv-id below an untrusted one was written by someone else.
     """
     results: list[AuthResult] = []
+    first_cut: str | None = None
+    size = 1  # as _listed counts
+    for subject, result, cut in _trusted_results(fields, trusted):
+        size += _size(result) + 1
+        if size > _LIST_BYTES:
+            return results, first_cut or subject
+        results.append(result)
+        if cut and first_cut is None:
+            first_cut = subject
+    return results, first_cut
+
+
+def _trusted_results(
+    fields: list[tuple[str, str]], trusted: set[str]
+) -> Iterator[tuple[str, AuthResult, bool]]:
+    """Each result of the trusted headers on top, with the header it is in (a
+    ``header:`` subject) and whether one of its strings was cut."""
+    occurrence = 0
     for name, value in fields:
         if name.lower() != "authentication-results":
             continue
+        occurrence += 1
         head, *resinfos = _segments(value)
         words = head.split()
         authserv_id = _unquote(words[0]).lower() if words else ""
         if authserv_id not in trusted:
-            break
-        results += _auth_results(authserv_id, resinfos)
-    return results
+            return
+        for result, cut in _auth_results(authserv_id, resinfos):
+            yield _header_subject(name, occurrence), result, cut
 
 
-def _auth_results(authserv_id: str, resinfos: list[str]) -> list[AuthResult]:
-    """Each resinfo's ``method=result``, with its ``ptype.property=value`` pairs."""
-    results: list[AuthResult] = []
+def _auth_results(
+    authserv_id: str, resinfos: list[str]
+) -> Iterator[tuple[AuthResult, bool]]:
+    """Each resinfo's ``method=result``, with its ``ptype.property=value``
+    pairs, each string cut to ``_STRING_BYTES``; and whether one was."""
     for resinfo in resinfos:
         pairs = _AUTH_PAIR.findall(resinfo)
         if not pairs:  # "none": no result
             continue
         (method, result), *properties = pairs
-        results.append(
-            AuthResult(
-                authserv_id=authserv_id,
-                method=method.partition("/")[0].lower(),
-                result=_unquote(result).lower(),
-                properties={
-                    key.lower(): _unquote(pvalue)
-                    for key, pvalue in properties
-                    if "." in key
-                },
-            )
+        cut = _Cutter()
+        read = AuthResult(
+            authserv_id=cut(authserv_id),
+            method=cut(method.partition("/")[0].lower()),
+            result=cut(_unquote(result).lower()),
+            properties={
+                cut(key.lower()): cut(_unquote(pvalue))
+                for key, pvalue in properties
+                if "." in key
+            },
         )
-    return results
+        yield read, cut.cut
 
 
 def _segments(value: str) -> list[str]:
@@ -1299,22 +1643,33 @@ def _host(url: str) -> str:
     return _domain(host) if host else ""
 
 
+def _url(
+    url: str,
+    found_in: Literal["text", "html_href", "html_text", "header"],
+    part_id: str | None,
+    cut: _Cutter,
+    anchor_text: str | None = None,
+) -> Url:
+    """A URL as the view records it: cut to ``_URL_BYTES``, its host (of the
+    whole URL) and anchor text to ``_STRING_BYTES``."""
+    return Url(
+        url=cut(url, _URL_BYTES),
+        host=cut(_host(url)),
+        found_in=found_in,
+        part_id=part_id,
+        anchor_text=cut.optional(anchor_text),
+    )
+
+
 def _urls_in(
-    text: str, found_in: Literal["text", "html_text"], part_id: str
+    text: str, found_in: Literal["text", "html_text"], part_id: str, cut: _Cutter
 ) -> Iterator[Url]:
     """The ``http(s)://`` and ``www.`` URLs written in a text."""
     for match in _URL.finditer(text):
-        url = match.group().rstrip(_URL_TRAILER)
-        yield Url(
-            url=url,
-            host=_host(url),
-            found_in=found_in,
-            part_id=part_id,
-            anchor_text=None,
-        )
+        yield _url(match.group().rstrip(_URL_TRAILER), found_in, part_id, cut)
 
 
-def _header_urls(fields: list[tuple[str, str]]) -> Iterator[Url]:
+def _header_urls(fields: list[tuple[str, str]], cut: _Cutter) -> Iterator[Url]:
     """The URLs of the List-Unsubscribe headers (RFC 2369)."""
     for name, value in fields:
         if name.lower() != "list-unsubscribe":
@@ -1322,25 +1677,13 @@ def _header_urls(fields: list[tuple[str, str]]) -> Iterator[Url]:
         for item in _ANGLE_BRACKETS.findall(value):
             url = "".join(item.split())
             if url:
-                yield Url(
-                    url=url,
-                    host=_host(url),
-                    found_in="header",
-                    part_id=None,
-                    anchor_text=None,
-                )
+                yield _url(url, "header", None, cut)
 
 
-def _html_urls(links: list[_Link], part_id: str) -> Iterator[Url]:
+def _html_urls(links: list[_Link], part_id: str, cut: _Cutter) -> Iterator[Url]:
     """The URLs of an HTML part's attributes."""
     for link in links:
-        yield Url(
-            url=link.url,
-            host=_host(link.url),
-            found_in="html_href",
-            part_id=part_id,
-            anchor_text=link.anchor_text,
-        )
+        yield _url(link.url, "html_href", part_id, cut, link.anchor_text)
 
 
 @dataclass(slots=True)