lorebase-keeper 0.2.3__py3-none-any.whl

lorebase_keeper/settings.py

@@ -0,0 +1,313 @@
+"""The `keeper` settings section, registered with `lorebase_platform`.
+
+Every value has a code default for local runs; deployments override them through the YAML file
+(`keeper:`) or environment variables (`LOREBASE__KEEPER__PORT`, ...). See
+`config/lorebase.example.yaml`.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import Field, field_validator, model_validator
+
+from lorebase_keeper.auth.config import AuthSettings, is_loopback
+from lorebase_keeper.client_address import normalize_networks
+from lorebase_keeper.ratelimit.config import QuotaSettings, RateLimitSettings
+from lorebase_keeper.services.config import (
+    AgentWriteSettings,
+    BranchSettings,
+    DocumentSettings,
+    DomainSettings,
+    OperationSettings,
+    ProposalSettings,
+    SchemaChangeSettings,
+    SchemaInferenceSettings,
+    SchemaSuggestionSettings,
+)
+from lorebase_keeper.tracing.config import TraceSettings
+from lorebase_platform.settings import SectionModel, Settings, register_section
+
+SECTION = "keeper"
+
+
+REQUIRED_CORS_REQUEST_HEADERS = (
+    "Authorization",
+    "Content-Type",
+    "Idempotency-Key",
+    "If-None-Match",
+)
+"""Request headers the clients send, always allowed cross-origin (plus the request id, session
+CSRF and agent trace headers Keeper is configured with)."""
+
+REQUIRED_CORS_RESPONSE_HEADERS = ("ETag", "Lorebase-Revision")
+"""Response headers always readable cross-origin (plus the request id and rate limit headers):
+the web app revalidates reads with the ETag and follows the Revision a read was served from."""
+
+
+class CorsSettings(SectionModel):
+    """Cross-origin access for browser clients. Disabled while `allow_origins` is empty."""
+
+    allow_origins: tuple[str, ...] = Field(
+        default=(), description="Allowed origins, e.g. https://lorebase.example.com. Empty: off."
+    )
+    allow_methods: tuple[str, ...] = ("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
+    allow_headers: tuple[str, ...] = Field(
+        default=(),
+        description="Further request headers to allow. Always allowed besides them: "
+        "Authorization, Content-Type, Idempotency-Key, If-None-Match, the request id header, "
+        "the session CSRF header and the agent trace headers.",
+    )
+    expose_headers: tuple[str, ...] = Field(
+        default=REQUIRED_CORS_RESPONSE_HEADERS,
+        description="Response headers readable by cross-origin scripts. ETag and "
+        "Lorebase-Revision (conditional reads), the request id and the rate limit headers are "
+        "always exposed.",
+    )
+    allow_credentials: bool = False
+    max_age_s: int = Field(default=600, ge=0, description="Preflight cache lifetime.")
+
+    @model_validator(mode="after")
+    def _no_wildcard_with_credentials(self) -> Self:
+        if self.allow_credentials and "*" in self.allow_origins:
+            raise ValueError("allow_origins cannot contain '*' when allow_credentials is true")
+        return self
+
+
+class HstsSettings(SectionModel):
+    """`Strict-Transport-Security`, which only makes sense when the connection is TLS."""
+
+    enabled: Literal["auto", "always", "never"] = Field(
+        default="auto",
+        description="auto: send it when the request arrived over https (directly, or through a "
+        "trusted proxy that sets X-Forwarded-Proto: https); always; never.",
+    )
+    max_age_s: int = Field(default=31_536_000, ge=0, description="max-age directive.")
+    include_subdomains: bool = True
+    preload: bool = Field(
+        default=False,
+        description="Add the preload directive; needs include_subdomains and a max_age_s of at "
+        "least one year.",
+    )
+
+    @model_validator(mode="after")
+    def _preload_requirements(self) -> Self:
+        if self.preload and (not self.include_subdomains or self.max_age_s < 31_536_000):
+            raise ValueError("preload needs include_subdomains and max_age_s of at least 31536000")
+        return self
+
+    @property
+    def header_value(self) -> str:
+        parts = [f"max-age={self.max_age_s}"]
+        if self.include_subdomains:
+            parts.append("includeSubDomains")
+        if self.preload:
+            parts.append("preload")
+        return "; ".join(parts)
+
+
+class SecurityHeadersSettings(SectionModel):
+    """Response headers that limit what a browser does with Keeper's responses. A header a
+    route sets itself is never replaced."""
+
+    enabled: bool = Field(default=True, description="Master switch for all of these headers.")
+    hsts: HstsSettings = Field(default_factory=HstsSettings)
+    frame_options: Literal["DENY", "SAMEORIGIN", "off"] = Field(
+        default="DENY",
+        description="X-Frame-Options, and the matching CSP frame-ancestors ('none' or 'self'). "
+        "off sends neither.",
+    )
+    referrer_policy: str = Field(
+        default="no-referrer", description="Referrer-Policy value. Empty: not sent."
+    )
+    content_type_nosniff: bool = Field(
+        default=True, description="Send X-Content-Type-Options: nosniff."
+    )
+
+
+class LimitSettings(SectionModel):
+    """Request size limits, rate limits and daily quotas."""
+
+    max_request_body_bytes: int = Field(
+        default=1_048_576, ge=1, description="Larger request bodies are rejected with 413."
+    )
+    rate: RateLimitSettings = Field(default_factory=RateLimitSettings)
+    quota: QuotaSettings = Field(default_factory=QuotaSettings)
+
+
+class PaginationSettings(SectionModel):
+    """Cursor pagination bounds shared by list endpoints."""
+
+    default_limit: int = Field(default=50, ge=1)
+    max_limit: int = Field(default=500, ge=1)
+
+    @model_validator(mode="after")
+    def _default_within_max(self) -> Self:
+        if self.default_limit > self.max_limit:
+            raise ValueError("default_limit cannot exceed max_limit")
+        return self
+
+
+class ReadCacheSettings(SectionModel):
+    """In-process cache of GET read responses, keyed by the Revision they were served from.
+
+    Entries never go stale (a new commit means a new Revision, hence a new key); they leave
+    by size, count or time to live.
+    """
+
+    enabled: bool = True
+    max_entries: int = Field(default=1024, ge=1, description="Responses kept.")
+    max_bytes: int = Field(
+        default=32 * 1024 * 1024, ge=1, description="Total size of kept response bodies."
+    )
+    ttl_s: float = Field(default=300, gt=0, description="Lifetime of an entry in seconds.")
+    max_body_bytes: int = Field(
+        default=1024 * 1024, ge=1, description="Larger responses are not cached."
+    )
+    time_travel_max_entries: int = Field(
+        default=128,
+        ge=0,
+        description="Entries for reads served from the tree at another Revision; once reached, "
+        "such reads are not cached. 0 never caches them.",
+    )
+
+
+class SensitivitySettings(SectionModel):
+    """How reads show values of sensitive Attributes (design 10.2, 13.5).
+
+    A caller sees the values of an Attribute tagged `pii`, `confidential` or `restricted` only
+    with the matching clearance (`pii.read`, `confidential.read`, `restricted.read`) on its
+    Kind; other callers get `masked_value`, or no value at all with `omit`.
+    """
+
+    omit: bool = Field(
+        default=False,
+        description="Leave masked values out of Records instead of showing masked_value. "
+        "Values shown outside Records (history, lineage, diffs, Conflicts) are always masked.",
+    )
+    masked_value: str = Field(
+        default="***", description="What a value is replaced by when it is masked."
+    )
+    erased_value: str = Field(
+        default="[erased]",
+        description="What cleared callers see for a vault value that was erased.",
+    )
+
+
+class ReadsSettings(SectionModel):
+    """Read responses: authorization of Revisions named by id or tag, response cache, and the
+    database serving them (design 15.3)."""
+
+    cache: ReadCacheSettings = Field(default_factory=ReadCacheSettings)
+    sensitivity: SensitivitySettings = Field(default_factory=SensitivitySettings)
+    reachability_max_depth: int = Field(
+        default=1000,
+        ge=1,
+        description="Parent hops followed from branch heads when checking that a Revision or "
+        "tag named by a caller with branch-scoped grants is reachable from a branch the caller "
+        "may read. A Revision further back than this is refused (403).",
+    )
+    prefer_replica: bool = Field(
+        default=False,
+        description="Serve reads from the read replicas named by `database.read_dsn` when one "
+        "is fresh enough; otherwise, or when false, from the primary. Without replicas "
+        "configured it has no effect.",
+    )
+
+
+class ReadinessSettings(SectionModel):
+    """How `/readyz` finds and probes the database."""
+
+    timeout_s: float = Field(default=2.0, gt=0, description="Time budget of each check.")
+    database_section: str = Field(
+        default="database",
+        min_length=1,
+        description="Settings section holding the database connection. When it is absent "
+        "the database check reports not_configured.",
+    )
+    database_dsn_key: str = Field(
+        default="dsn", min_length=1, description="Key of the connection string in that section."
+    )
+
+
+class OpenApiSettings(SectionModel):
+    """OpenAPI document and interactive docs, served under the API prefix."""
+
+    title: str = "Lorebase Keeper"
+    description: str = (
+        "REST API of Lorebase: versioned ontology and knowledge graph. Errors use RFC 9457 "
+        "problem details."
+    )
+    docs_enabled: bool = Field(default=True, description="Serve /docs and the OpenAPI document.")
+
+
+class KeeperSettings(SectionModel):
+    """Settings of the Keeper service."""
+
+    host: str = Field(default="127.0.0.1", min_length=1, description="Bind address.")
+    port: int = Field(default=8080, ge=1, le=65535)
+    api_prefix: str = Field(default="/api/v1", description="Version prefix of every API route.")
+    request_id_header: str = Field(
+        default="X-Request-ID", min_length=1, description="Header carrying the request id."
+    )
+    problem_type_base: str = Field(
+        default="urn:lorebase:problem:",
+        min_length=1,
+        description="Prefix of the stable `type` URI of problem details; the error code is "
+        "appended.",
+    )
+    trusted_proxies: tuple[str, ...] = Field(
+        default=(),
+        description="Networks of the reverse proxies in front of Keeper, e.g. 10.0.0.0/8. Only "
+        "when the socket peer is in one of them is X-Forwarded-For read (right to left, "
+        "skipping trusted hops) to find the client address used by API key allowlists and "
+        "failed authentication limits. Empty: the socket peer is the client.",
+    )
+    cors: CorsSettings = Field(default_factory=CorsSettings)
+    security_headers: SecurityHeadersSettings = Field(default_factory=SecurityHeadersSettings)
+    limits: LimitSettings = Field(default_factory=LimitSettings)
+    pagination: PaginationSettings = Field(default_factory=PaginationSettings)
+    reads: ReadsSettings = Field(default_factory=ReadsSettings)
+    readiness: ReadinessSettings = Field(default_factory=ReadinessSettings)
+    auth: AuthSettings = Field(default_factory=AuthSettings)
+    openapi: OpenApiSettings = Field(default_factory=OpenApiSettings)
+    domains: DomainSettings = Field(default_factory=DomainSettings)
+    branches: BranchSettings = Field(default_factory=BranchSettings)
+    schema_changes: SchemaChangeSettings = Field(default_factory=SchemaChangeSettings)
+    schema_inference: SchemaInferenceSettings = Field(default_factory=SchemaInferenceSettings)
+    schema_suggestions: SchemaSuggestionSettings = Field(default_factory=SchemaSuggestionSettings)
+    operations: OperationSettings = Field(default_factory=OperationSettings)
+    proposals: ProposalSettings = Field(default_factory=ProposalSettings)
+    agent_writes: AgentWriteSettings = Field(default_factory=AgentWriteSettings)
+    documents: DocumentSettings = Field(default_factory=DocumentSettings)
+    trace: TraceSettings = Field(default_factory=TraceSettings)
+
+    @field_validator("trusted_proxies")
+    @classmethod
+    def _proxy_networks(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return normalize_networks(value)
+
+    @field_validator("api_prefix")
+    @classmethod
+    def _prefix_shape(cls, value: str) -> str:
+        if not value.startswith("/") or (len(value) > 1 and value.endswith("/")):
+            raise ValueError("must start with '/' and not end with '/'")
+        return "" if value == "/" else value
+
+    @model_validator(mode="after")
+    def _no_anonymous_access_off_loopback(self) -> Self:
+        if self.auth.mode == "none" and not self.auth.allow_insecure and not is_loopback(self.host):
+            raise ValueError(
+                f"auth.mode 'none' accepts every request as an administrator and host "
+                f"{self.host!r} is not a loopback address: choose another auth.mode, bind to "
+                "127.0.0.1, or set auth.allow_insecure to true"
+            )
+        return self
+
+
+register_section(SECTION, KeeperSettings)
+
+
+def keeper_settings(settings: Settings) -> KeeperSettings:
+    """The validated `keeper` section of loaded settings."""
+    return settings.section(SECTION, KeeperSettings)

lorebase_keeper/tracing/__init__.py

@@ -0,0 +1 @@
+"""Agent trace: opt-in record of how agent sessions navigate the graph (`keeper.trace`)."""

lorebase_keeper/tracing/capture.py

@@ -0,0 +1,350 @@
+"""What a trace step keeps of a request and its response: pure functions over JSON.
+
+- `query_of`: the query as structured data. The request body of a POST read, or the query
+  parameters of a GET read. Values compared by filters (`attr` and `derived` predicates) are
+  replaced by their type, except on fields the read found not sensitive (`plain`, with
+  `capture_filter_values: non_sensitive`), where scalars and lists of scalars are kept, cut
+  to `max_text_chars` and `max_filter_value_items`; `capture_literals` keeps them all. Search
+  text (`q`, `search`, `match`) is kept unless `capture_search_text` is off; query vectors
+  are replaced by their dimension and cursors dropped. Long strings are cut.
+- `result_of`: counts of the lists of a response, plus the search mode and corrections, the
+  context pack budget and truncation flags. No values.
+- `refs_of`: the Records (Kind and key) and Links (Relation and both ends) a response
+  touched. Members named `values` are never walked, so values of Records are never read
+  even when they hold references.
+- `proposal_of`: the Proposal a write opened or acted on.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+from lorebase_keeper.tracing.config import TraceSettings
+
+TEXT_MEMBERS = frozenset({"q", "search", "match"})
+SKIPPED_PARAMS = frozenset({"cursor"})
+COMPARED_FIELDS = ("attr", "derived")
+MAX_LIST_ITEMS = 100
+MAX_CORRECTIONS = 20
+MAX_DEPTH = 32
+
+RecordRef = tuple[str, str]
+LinkRef = tuple[str, str, str, str, str]
+
+
+def _type_of(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int | float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "list"
+    return "object"
+
+
+def _redacted(value: Any) -> dict[str, Any]:
+    out: dict[str, Any] = {"redacted": _type_of(value)}
+    if isinstance(value, list):
+        out["count"] = len(value)
+    return out
+
+
+def _scalar(value: Any) -> bool:
+    return value is None or isinstance(value, bool | int | float | str)
+
+
+class _Redactor:
+    def __init__(self, settings: TraceSettings, plain: Callable[[str], bool] | None = None) -> None:
+        self._settings = settings
+        self._plain = plain if settings.capture_filter_values == "non_sensitive" else None
+
+    def _plain_field(self, comparison: Mapping[str, Any]) -> bool:
+        """Whether a predicate compares a field the read reported as not sensitive (every
+        field it names, should it name both `attr` and `derived`)."""
+        plain = self._plain
+        fields = [comparison[name] for name in COMPARED_FIELDS if name in comparison]
+        return (
+            plain is not None
+            and bool(fields)
+            and all(isinstance(field, str) and plain(field) for field in fields)
+        )
+
+    def literal(self, value: Any) -> Any:
+        """A compared value as kept: a scalar (strings cut) or a list of scalars (cut to
+        `max_filter_value_items`); anything else by its type."""
+        if isinstance(value, str):
+            return self.text(value)
+        if _scalar(value):
+            return value
+        if isinstance(value, list) and all(_scalar(item) for item in value):
+            limit = self._settings.max_filter_value_items
+            items: list[Any] = [
+                self.text(item) if isinstance(item, str) else item for item in value[:limit]
+            ]
+            if len(value) > limit:
+                items.append({"truncated": len(value) - limit})
+            return items
+        return _redacted(value)
+
+    def text(self, value: str) -> str:
+        limit = self._settings.max_text_chars
+        return value if len(value) <= limit else value[:limit] + "…"
+
+    def node(self, value: Any, depth: int = 0) -> Any:
+        if depth > MAX_DEPTH:
+            return {"truncated": True}
+        if isinstance(value, Mapping):
+            return self.mapping(value, depth)
+        if isinstance(value, list):
+            items = [self.node(item, depth + 1) for item in value[:MAX_LIST_ITEMS]]
+            if len(value) > MAX_LIST_ITEMS:
+                items.append({"truncated": len(value) - MAX_LIST_ITEMS})
+            return items
+        if isinstance(value, str):
+            return self.text(value)
+        return value
+
+    def mapping(self, value: Mapping[str, Any], depth: int) -> dict[str, Any]:
+        comparison = any(name in value for name in COMPARED_FIELDS) and "value" in value
+        out: dict[str, Any] = {}
+        for name, member in value.items():
+            if name == "query_vector" and isinstance(member, list):
+                out[name] = {"dims": len(member)}
+            elif name in SKIPPED_PARAMS:
+                continue
+            elif name == "value" and comparison:
+                if self._settings.capture_literals:
+                    out[name] = self.node(member, depth + 1)
+                elif self._plain_field(value):
+                    out[name] = self.literal(member)
+                else:
+                    out[name] = _redacted(member)
+            elif name in TEXT_MEMBERS and isinstance(member, str):
+                out[name] = (
+                    self.text(member)
+                    if self._settings.capture_search_text
+                    else {"redacted": "text", "length": len(member)}
+                )
+            else:
+                out[name] = self.node(member, depth + 1)
+        return out
+
+
+def _parse(raw: bytes) -> Any:
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return None
+
+
+def query_of(
+    settings: TraceSettings,
+    *,
+    params: Iterable[tuple[str, str]],
+    body: bytes | None,
+    body_complete: bool,
+    plain: Callable[[str], bool] | None = None,
+) -> dict[str, Any] | None:
+    """The recorded query of a read: `{"body": ...}` and/or `{"params": ...}`. `plain` tells
+    the fields whose compared values may be kept (see the module doc); None: none."""
+    redactor = _Redactor(settings, plain)
+    out: dict[str, Any] = {}
+    collected: dict[str, Any] = {}
+    for name, value in params:
+        if name in SKIPPED_PARAMS:
+            continue
+        if name == "where":
+            parsed = _parse(value.encode())
+            collected[name] = (
+                redactor.node(parsed) if parsed is not None else {"redacted": "string"}
+            )
+        elif name in TEXT_MEMBERS:
+            collected[name] = redactor.mapping({name: value}, 0)[name]
+        else:
+            collected[name] = redactor.text(value)
+    if collected:
+        out["params"] = collected
+    if body:
+        if not body_complete:
+            out["body"] = {"truncated": True, "bytes": len(body)}
+        else:
+            parsed = _parse(body)
+            if isinstance(parsed, Mapping):
+                out["body"] = redactor.mapping(parsed, 0)
+    if not out:
+        return None
+    if len(json.dumps(out)) > settings.max_query_bytes:
+        return {"truncated": True}
+    return out
+
+
+def branch_of(query: Mapping[str, Any] | None) -> str | None:
+    """The branch a recorded query names, if any."""
+    if not query:
+        return None
+    for part in ("body", "params"):
+        section = query.get(part)
+        if isinstance(section, Mapping) and isinstance(section.get("branch"), str):
+            return str(section["branch"])
+    return None
+
+
+def result_of(document: Any, settings: TraceSettings) -> dict[str, Any] | None:
+    """Counts and shape of a JSON response; never values. Search corrections name the query
+    words, so they are kept only with `capture_search_text`."""
+    if not isinstance(document, Mapping):
+        return None
+    counts: dict[str, int] = {}
+    for name, member in document.items():
+        if name == "corrections":
+            continue
+        if isinstance(member, list):
+            counts[name] = len(member)
+        elif (
+            isinstance(member, Mapping)
+            and member
+            and all(isinstance(v, list) for v in member.values())
+        ):
+            counts[name] = sum(len(v) for v in member.values())
+    hops = document.get("hops")
+    if isinstance(hops, list):
+        counts["hop_records"] = sum(
+            len(h.get("records") or ()) for h in hops if isinstance(h, Mapping)
+        )
+    out: dict[str, Any] = {"counts": counts}
+    if isinstance(document.get("mode"), str):
+        out["mode"] = document["mode"]
+    corrections = document.get("corrections")
+    if isinstance(corrections, list) and corrections and settings.capture_search_text:
+        out["corrections"] = [
+            {"word": c.get("word"), "replacements": list(c.get("replacements") or ())[:10]}
+            for c in corrections[:MAX_CORRECTIONS]
+            if isinstance(c, Mapping)
+        ]
+    budget = document.get("budget")
+    if isinstance(budget, Mapping):
+        out["budget"] = {
+            name: budget.get(name)
+            for name in ("limit_tokens", "used_tokens", "over_budget", "capped")
+            if name in budget
+        }
+    if isinstance(document.get("truncated"), bool):
+        out["truncated"] = document["truncated"]
+    if "next_cursor" in document:
+        out["has_more"] = document.get("next_cursor") is not None
+    aggregate = document.get("aggregate")
+    if isinstance(aggregate, Mapping) and isinstance(aggregate.get("counts"), list):
+        counts["aggregate_groups"] = len(aggregate["counts"])
+    return out
+
+
+def _ref(value: Any) -> RecordRef | None:
+    if isinstance(value, Mapping):
+        kind, key = value.get("kind"), value.get("key")
+        if isinstance(kind, str) and isinstance(key, str):
+            return kind, key
+        return None
+    if isinstance(value, str) and "/" in value:
+        kind, _, key = value.partition("/")
+        if kind and key:
+            return kind, key
+    return None
+
+
+class _Refs:
+    def __init__(self, limit: int) -> None:
+        self.limit = limit
+        self.records: dict[RecordRef, None] = {}
+        self.links: dict[LinkRef, None] = {}
+        self.truncated = False
+
+    def record(self, ref: RecordRef | None) -> None:
+        if ref is None or ref in self.records:
+            return
+        if len(self.records) + len(self.links) >= self.limit:
+            self.truncated = True
+            return
+        self.records[ref] = None
+
+    def link(self, relation: str, source: RecordRef | None, target: RecordRef | None) -> None:
+        if source is None or target is None:
+            return
+        self.record(source)
+        self.record(target)
+        key = (relation, *source, *target)
+        if key in self.links:
+            return
+        if len(self.records) + len(self.links) >= self.limit:
+            self.truncated = True
+            return
+        self.links[key] = None
+
+    def walk(self, node: Any, depth: int = 0) -> None:
+        if depth > MAX_DEPTH:
+            return
+        if isinstance(node, list):
+            for item in node:
+                self.walk(item, depth + 1)
+            return
+        if not isinstance(node, Mapping):
+            return
+        self.record(_ref(node))
+        ref = node.get("ref")
+        if isinstance(ref, str):
+            self.record(_ref(ref))
+        relation = node.get("relation")
+        if isinstance(relation, str):
+            self.link(relation, _ref(node.get("from")), _ref(node.get("to")))
+        for name, member in node.items():
+            if name == "values":
+                continue
+            if name == "links" and isinstance(member, Mapping):
+                self._pack_links(member)
+                continue
+            if isinstance(member, Mapping | list):
+                self.walk(member, depth + 1)
+
+    def _pack_links(self, links: Mapping[str, Any]) -> None:
+        """Context pack Links: `{relation: [{"from": "Kind/key", "to": "Kind/key"}]}`."""
+        for relation, items in links.items():
+            for item in items if isinstance(items, list) else ():
+                if isinstance(item, Mapping):
+                    self.link(relation, _ref(item.get("from")), _ref(item.get("to")))
+
+
+def refs_of(document: Any, limit: int) -> dict[str, Any] | None:
+    """Records and Links a JSON response touched, at most `limit` in all."""
+    refs = _Refs(limit)
+    refs.walk(document)
+    if not refs.records and not refs.links:
+        return None
+    out: dict[str, Any] = {
+        "records": [list(ref) for ref in refs.records],
+        "links": [list(link) for link in refs.links],
+    }
+    if refs.truncated:
+        out["truncated"] = True
+    return out
+
+
+def proposal_of(document: Any) -> str | None:
+    """The id of the Proposal a write response names (`proposal.id` or `proposal_id`)."""
+    if not isinstance(document, Mapping):
+        return None
+    proposal = document.get("proposal")
+    if isinstance(proposal, Mapping) and isinstance(proposal.get("id"), str):
+        return str(proposal["id"])
+    if isinstance(document.get("proposal_id"), str):
+        return str(document["proposal_id"])
+    return None
+
+
+def parse_json(raw: bytes) -> Any:
+    """A JSON body, or None when it is not JSON."""
+    return _parse(raw) if raw else None