seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/runtime/idempotency.py

@@ -0,0 +1,279 @@
+"""Idempotency at the boundary (ADR 0012 "Target obligations"): after the input step, the claim's fixed-size key and
+fingerprint, and the replay, running and mismatch answers; once the reply is written, the record completed with the
+reply that went out, or abandoned after a server error or an error that forbids storing."""
+
+from dataclasses import dataclass
+from typing import ClassVar, Final
+
+from seampact.codegen.runtime.access_steps import HookCaller
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.digests import hex_of
+from seampact.codegen.runtime.failures import BoundaryFailureError
+from seampact.codegen.runtime.input_decoding import DecodedInput, role_refusal
+from seampact.codegen.runtime.ir_view import IrMap, ir_int, ir_map, ir_maps, ir_string, ir_strings
+from seampact.codegen.runtime.principal_members import principal_members
+from seampact.codegen.runtime.replies import CACHE_CONTROL, CONTENT_TYPE, NO_STORE, Reply
+from seampact.hooks import IdempotencyClaim, IdempotencyStore, OperationRef, StoredResponse, idempotency_begin
+from seampact.hooks._redaction import RedactedRepr
+
+IN_PROGRESS_ROLE: Final = "idempotencyInProgress"
+KEY_REUSED_ROLE: Final = "idempotencyKeyReused"
+
+_DERIVED: Final = "derived"
+_BOUNDARY: Final = "boundary"
+_UNION_TAG_DERIVATION: Final = "union.headerTag"
+_CONTENT_HEADER_PREFIX: Final = "content-"
+_AUTHORIZATION_HEADER: Final = "authorization"
+_REPLAYED: Final = "true"
+_CLIENT_ERROR_FLOOR: Final = 400
+_SERVER_ERROR_FLOOR: Final = 500
+
+
+@dataclass(frozen=True, slots=True)
+class IdempotencyClaimed:
+    """The request holds the record of `key`: its handler runs, then the placement settles the record."""
+
+    key: str
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class IdempotencyReplayed(RedactedRepr):
+    """The stored reply of an earlier request with the same key and input: the handler must not run. Its repr hides
+    the reply, whose body and headers the store keeps redacted too."""
+
+    _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"reply"})
+
+    reply: Reply
+
+
+@dataclass(frozen=True, slots=True)
+class IdempotencyStoreFailure:
+    """The store failed after the reply was decided, so the reply stands: the placement logs `reason` with `cause`
+    and tells the unexpected-error listener."""
+
+    reason: str
+    cause: Exception
+
+
+type IdempotencyStart = IdempotencyClaimed | IdempotencyReplayed | None
+
+
+def enforces_idempotency(contract: ApiContract, operation_id: str) -> bool:
+    """Whether the boundary enforces the operation's idempotency, so it needs the api's idempotency store."""
+    idempotency = ir_map(contract.operation(operation_id), "idempotency")
+
+    return ir_string(idempotency, "kind") == _DERIVED and ir_string(idempotency, "enforce") == _BOUNDARY
+
+
+async def begin_idempotency(
+    contract: ApiContract,
+    operation_id: str,
+    principal: object | None,
+    decoded: DecodedInput,
+    store: IdempotencyStore | None,
+    call: HookCaller,
+) -> IdempotencyStart:
+    """Claims the request's key. None for a request without a key, or an operation whose idempotency the boundary
+    does not enforce; a required key that is missing was refused by the input step.
+
+    Raises `ContractRefusal` when the key is running or was used with another request, and `BoundaryFailureError`
+    when the api has no store or the store answers something else."""
+    if not enforces_idempotency(contract, operation_id):
+        return None
+
+    idempotency = ir_map(contract.operation(operation_id), "idempotency")
+
+    client_key = decoded.headers.get(ir_string(idempotency, "header") or "")
+
+    if not isinstance(client_key, str):
+        return None
+
+    if store is None:
+        raise BoundaryFailureError(
+            f"seampact: the api '{contract.api}' has no idempotency store for operation '{operation_id}'; register "
+            "one as the target's guide says."
+        )
+
+    key = idempotency_partition_key(contract, operation_id, principal, client_key)
+    claim = IdempotencyClaim(
+        key=key,
+        fingerprint=idempotency_fingerprint(contract, operation_id, decoded),
+        lifetime_ms=ir_int(idempotency, "lifetimeMs") or 0,
+        operation=OperationRef(api=contract.api, id=operation_id),
+    )
+    begun = await call(store.begin, claim)
+
+    if isinstance(begun, idempotency_begin.Started):
+        return IdempotencyClaimed(key)
+
+    if isinstance(begun, idempotency_begin.Running):
+        raise role_refusal(contract, operation_id, IN_PROGRESS_ROLE)
+
+    if isinstance(begun, idempotency_begin.Mismatch):
+        raise role_refusal(contract, operation_id, KEY_REUSED_ROLE)
+
+    if isinstance(begun, idempotency_begin.Replay):
+        return IdempotencyReplayed(_replayed(begun.response, ir_string(idempotency, "replayHeader")))
+
+    raise BoundaryFailureError(
+        f"seampact: the idempotency store answered a {type(begun).__qualname__}, none of Started, Running, Mismatch "
+        "and Replay; return one of them."
+    )
+
+
+async def settle_idempotency(
+    contract: ApiContract,
+    operation_id: str,
+    claimed: IdempotencyClaimed,
+    reply: Reply,
+    store: IdempotencyStore,
+    call: HookCaller,
+) -> IdempotencyStoreFailure | None:
+    """Completes the claimed record with the reply that went out, or abandons it when the reply is not kept."""
+    try:
+        if not _is_kept_for_replay(reply):
+            await call(store.abandon, claimed.key)
+            return None
+
+        stored = StoredResponse(
+            status=reply.status, headers=_stored_headers(contract, operation_id, reply), body=reply.body
+        )
+        await call(lambda response: store.complete(claimed.key, response), stored)
+    except Exception as failure:  # The reply stands: the failure goes back to the placement.
+        return IdempotencyStoreFailure(
+            "the idempotency store failed to record the reply, so a retry with the same key may run again; check "
+            "the store's backend",
+            failure,
+        )
+
+    return None
+
+
+async def abandon_idempotency(
+    claimed: IdempotencyClaimed, store: IdempotencyStore, call: HookCaller
+) -> IdempotencyStoreFailure | None:
+    """Releases the key without a reply to keep, after the request failed before its reply."""
+    try:
+        await call(store.abandon, claimed.key)
+    except Exception as failure:  # The request already failed: the failure goes back to the placement.
+        return IdempotencyStoreFailure(
+            "the idempotency store failed to release a key after the request failed, so a retry waits for its "
+            "lifetime; check the store's backend",
+            failure,
+        )
+
+    return None
+
+
+def idempotency_partition_key(
+    contract: ApiContract, operation_id: str, principal: object | None, client_key: str
+) -> str:
+    """The stored key of a client key: the api, operation, identity and principal members partition it, so two
+    callers never share a record (ADR 0012)."""
+    members = principal_members(contract, operation_id, principal)
+    identity = ir_string(ir_map(contract.operation(operation_id), "access"), "identity") or ""
+
+    return hex_of([contract.api, operation_id, identity, "" if members is None else hex_of([members]), client_key])
+
+
+def idempotency_fingerprint(contract: ApiContract, operation_id: str, decoded: DecodedInput) -> str:
+    """The digest a retry under the same key must match: the method, the contract path and the decoded input, its
+    headers cut to the header params the author declared and a union tag, in lower case. Any other header param the
+    compiler derives (a trace id, a deadline, the key, CSRF) and every credential header change on a retry."""
+    operation = contract.operation(operation_id)
+    credentials = _credential_headers(contract, operation)
+    counted = [name for name in _fingerprint_headers(operation) if name not in credentials]
+    headers = {name.lower(): value for name, value in decoded.headers.items() if name.lower() in counted}
+    parts: dict[str, object] = {"path": decoded.path, "query": decoded.query, "headers": headers}
+
+    if ir_map(operation, "input"):
+        parts["body"] = decoded.body
+
+    return hex_of([(ir_string(operation, "method") or "").lower(), ir_string(operation, "path") or "", parts])
+
+
+def _replayed(stored: StoredResponse, replay_header: str | None) -> Reply:
+    """The stored reply as it went out, authored by the boundary; a stored success carries the replay header."""
+    replay_name = None if replay_header is None else replay_header.lower()
+    headers = [(header.name.lower(), header.value) for header in stored.headers if header.name.lower() != replay_name]
+
+    if replay_name is not None and stored.status < _CLIENT_ERROR_FLOOR:
+        headers.append((replay_name, _REPLAYED))
+
+    return Reply(stored.status, tuple(headers), stored.body)
+
+
+def _is_kept_for_replay(reply: Reply) -> bool:
+    """A server error is dropped, and so is an error reply its sender marked no-store; a no-store success is kept,
+    so a retry never runs the write twice."""
+    if reply.status >= _SERVER_ERROR_FLOOR:
+        return False
+
+    if reply.status < _CLIENT_ERROR_FLOOR:
+        return True
+
+    directives = [
+        directive.strip().lower()
+        for name, value in reply.headers
+        if name == CACHE_CONTROL
+        for directive in value.split(",")
+    ]
+
+    return NO_STORE not in directives
+
+
+def _stored_headers(contract: ApiContract, operation_id: str, reply: Reply) -> tuple[StoredResponse.Header, ...]:
+    """The contract reply only: its content headers and the headers the operation declares for its status. Headers
+    set beside it (session cookies, CORS, security headers) belong to the request that ran."""
+    declared = {
+        (ir_string(header, "name") or "").lower()
+        for response in ir_maps(contract.operation(operation_id), "responses")
+        if ir_int(response, "status") == reply.status
+        for header in ir_maps(response, "headers")
+    }
+
+    return tuple(
+        StoredResponse.Header(name=name, value=value)
+        for name, value in reply.headers
+        if name == CONTENT_TYPE or name.startswith(_CONTENT_HEADER_PREFIX) or name in declared
+    )
+
+
+def _fingerprint_headers(operation: IrMap) -> list[str]:
+    """The header params a retry repeats: those the author declared, and a union tag."""
+    names: list[str] = []
+
+    for param in ir_maps(ir_map(operation, "params"), "header"):
+        derived_from = ir_map(param, "derivedFrom")
+
+        if not derived_from or ir_string(derived_from, "derivation") == _UNION_TAG_DERIVATION:
+            names.append((ir_string(param, "name") or "").lower())
+
+    return names
+
+
+def _credential_headers(contract: ApiContract, operation: IrMap) -> list[str]:
+    """The headers carrying a credential, lower case: a retry after a token or session refresh is the same request."""
+    access = ir_map(operation, "access")
+    names: list[str] = []
+
+    for scheme_id in ir_strings(access, "schemes"):
+        scheme = contract.declaration("schemes", scheme_id)
+        kind = ir_string(scheme, "kind")
+
+        if kind == "bearer":
+            names.append(_AUTHORIZATION_HEADER)
+        elif kind == "header":
+            names.append((ir_string(scheme, "name") or "").lower())
+
+    signed = ir_string(contract.declaration("identities", ir_string(access, "identity") or ""), "signed")
+
+    if signed is not None:
+        names.append((ir_string(contract.declaration("schemes", signed), "name") or "").lower())
+
+    csrf_header = ir_string(ir_map(operation, "csrf"), "header")
+
+    if csrf_header is not None:
+        names.append(csrf_header.lower())
+
+    return names

seampact/codegen/runtime/input_decoding.py

@@ -0,0 +1,226 @@
+"""Step 1's decoding: the path parameters percent-decoded from the raw path, the query from the raw query string, the
+declared headers, and the body (bounded read, media type, `json` with objects and arrays kept apart); each placement
+hands the decoded parts to its own step 6."""
+
+import json
+import re
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from seampact.codegen.runtime.body_reader import (
+    PAYLOAD_TOO_LARGE_ROLE,
+    SCHEMA_INVALID_ROLE,
+    UNSUPPORTED_MEDIA_TYPE_ROLE,
+    read_body,
+)
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.failures import BoundaryFailureError, ContractRefusal
+from seampact.codegen.runtime.ir_view import ir_int, ir_map, ir_maps, ir_string, ir_true
+from seampact.codegen.runtime.raw_target import RawTarget
+from seampact.codegen.runtime.replies import role_params
+from seampact.codegen.runtime.wire_values import decoded_segment, list_items, path_value, query_value, raw_query
+from seampact.codegen.runtime.wire_values import scalar as scalar_value
+
+_CONTENT_LENGTH: Final = "content-length"
+_CONTENT_TYPE: Final = "content-type"
+_CONTENT_ENCODING: Final = "content-encoding"
+_TRANSFER_ENCODING: Final = "transfer-encoding"
+_MAX_JSON_DEPTH: Final = 512
+_LONE_SURROGATE: Final = re.compile("[\ud800-\udfff]")
+
+
+@dataclass(frozen=True, slots=True)
+class IncomingRequest:
+    """What a placement reads of a contract request: header names in lower case, the first value of each."""
+
+    method: str
+    target: RawTarget
+    headers: Mapping[str, str]
+    body: AsyncIterator[bytes]
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class DecodedInput:
+    """The params by name, decoded by the IR's wire form, and the body tree (None when the request carries none);
+    `raw_body` holds the bytes as received on a signed route only. `repr` shows no value."""
+
+    path: dict[str, object]
+    query: dict[str, object]
+    headers: dict[str, object]
+    body: object
+    raw_body: bytes | None
+
+    def __repr__(self) -> str:
+        return "DecodedInput([redacted])"
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    """One refused input value: where (`path`, `query`, `header`, `body`), the JSON pointer and the contract rule."""
+
+    in_: str
+    pointer: str
+    rule: str
+
+    def as_slot(self) -> dict[str, str]:
+        return {"in": self.in_, "pointer": self.pointer, "rule": self.rule}
+
+
+async def decode_input(
+    contract: ApiContract, operation_id: str, raw_parameters: Mapping[str, str], request: IncomingRequest
+) -> DecodedInput:
+    """Raises `ContractRefusal` with the operation's code for a refused body or path value."""
+    operation = contract.operation(operation_id)
+    params = ir_map(operation, "params")
+    path: dict[str, object] = {}
+
+    for param in ir_maps(params, "path"):
+        name = ir_string(param, "name") or ""
+        raw = raw_parameters.get(name, "")
+
+        if decoded_segment(raw) is None:
+            raise schema_invalid(contract, operation_id, [Issue("path", f"/{name}", "type")])
+
+        path[name] = path_value(raw, ir_map(param, "type"))
+
+    headers: dict[str, object] = {}
+
+    for param in ir_maps(params, "header"):
+        name = ir_string(param, "name") or ""
+        value = request.headers.get(name.lower())
+
+        if value is not None:
+            headers[name] = scalar_value(value, ir_map(param, "type"))
+
+    query = _query(ir_maps(params, "query"), request.target.query)
+    input_ = ir_map(operation, "input")
+    body: object = None
+    raw_body: bytes | None = None
+
+    if input_ and _carries_body(request.headers):
+        data = await _body_bytes(contract, operation_id, input_, request)
+        raw_body = data if ir_true(input_, "rawBody") else None
+        body = None if data == b"" else _json_tree(contract, operation_id, data)
+
+    return DecodedInput(path, query, headers, body, raw_body)
+
+
+def schema_invalid(contract: ApiContract, operation_id: str, issues: list[Issue]) -> ContractRefusal:
+    """The operation's `schemaInvalid` refusal with its issues."""
+    return role_refusal(contract, operation_id, SCHEMA_INVALID_ROLE, {"issues": [issue.as_slot() for issue in issues]})
+
+
+def role_refusal(
+    contract: ApiContract, operation_id: str, role: str, slots: Mapping[str, object] | None = None
+) -> ContractRefusal:
+    """Raises `BoundaryFailureError` when the operation declares no code for `role`, which the compiler derives."""
+    code = contract.role_code(operation_id, role)
+
+    if code is None:
+        raise BoundaryFailureError(
+            f"seampact: operation '{operation_id}' has no code for the role '{role}'; regenerate the api."
+        )
+
+    return ContractRefusal(contract.api, code, role_params(contract, operation_id, code, role, slots or {}))
+
+
+def _query(declared: list[Mapping[str, object]], raw: str) -> dict[str, object]:
+    by_name = {ir_string(param, "name") or "": param for param in declared}
+    query: dict[str, object] = {}
+
+    for name, raw_values in raw_query(raw).items():
+        param = by_name.get(name)
+        values = list_items(raw_values, None if param is None else param.get("wire"))
+
+        if param is None:
+            query[name] = values[0] if len(values) == 1 else values
+        else:
+            query[name] = query_value(values, ir_map(param, "type"))
+
+    return query
+
+
+async def _body_bytes(
+    contract: ApiContract, operation_id: str, input_: Mapping[str, object], request: IncomingRequest
+) -> bytes:
+    # The bounded read comes first, so an oversized body answers 413 whatever its media type (ADR 0012).
+    limit_bytes = ir_int(input_, "bodyLimitBytes")
+
+    if limit_bytes is None:
+        raise BoundaryFailureError(f"seampact: operation '{operation_id}' has no body limit; regenerate the api.")
+
+    read = await read_body(
+        request.body, request.headers.get(_CONTENT_LENGTH), request.headers.get(_CONTENT_ENCODING), limit_bytes
+    )
+
+    if read.refused_role == PAYLOAD_TOO_LARGE_ROLE:
+        raise role_refusal(contract, operation_id, PAYLOAD_TOO_LARGE_ROLE, {"limitBytes": limit_bytes})
+
+    media = (request.headers.get(_CONTENT_TYPE) or "").split(";", 1)[0].strip().lower()
+
+    if read.refused_role == UNSUPPORTED_MEDIA_TYPE_ROLE or (read.data != b"" and media != ir_string(input_, "media")):
+        raise role_refusal(contract, operation_id, UNSUPPORTED_MEDIA_TYPE_ROLE)
+
+    if read.refused_role is not None:
+        raise schema_invalid(contract, operation_id, [Issue("body", "", "type")])
+
+    return read.data
+
+
+def _json_tree(contract: ApiContract, operation_id: str, data: bytes) -> object:
+    try:
+        tree: object = json.loads(data.decode("utf-8"), parse_constant=_refuse_constant)
+    except (ValueError, RecursionError):
+        raise schema_invalid(contract, operation_id, [Issue("body", "", "type")]) from None
+
+    if _depth(tree) > _MAX_JSON_DEPTH or _holds_lone_surrogate(tree):
+        raise schema_invalid(contract, operation_id, [Issue("body", "", "type")])
+
+    return tree
+
+
+def _refuse_constant(name: str) -> object:
+    """`NaN` and the infinities are not JSON."""
+    raise ValueError(f"{name} is not JSON")
+
+
+def _holds_lone_surrogate(tree: object) -> bool:
+    """A string with a lone surrogate, in a value or a key, which is not Unicode text."""
+    pending = [tree]
+
+    while pending:
+        item = pending.pop()
+
+        if isinstance(item, str) and _LONE_SURROGATE.search(item) is not None:
+            return True
+
+        if isinstance(item, dict):
+            pending.extend(item.keys())
+            pending.extend(item.values())
+        elif isinstance(item, list):
+            pending.extend(item)
+
+    return False
+
+
+def _depth(tree: object) -> int:
+    depth = 0
+    level = [tree]
+
+    while level:
+        containers = [item for item in level if isinstance(item, dict | list)]
+
+        if not containers:
+            return depth
+
+        depth += 1
+        level = [child for item in containers for child in (item.values() if isinstance(item, dict) else item)]
+
+    return depth
+
+
+def _carries_body(headers: Mapping[str, str]) -> bool:
+    length = headers.get(_CONTENT_LENGTH)
+
+    return (length is not None and length != "0") or _TRANSFER_ENCODING in headers

seampact/codegen/runtime/ir_view.py

@@ -0,0 +1,47 @@
+"""Typed reads of the IR view the generated code holds as JSON values: a missing or mistyped member reads as an
+empty map or list, or None, so the boundary never indexes past a member the contract does not carry."""
+
+from collections.abc import Mapping, Sequence
+
+type IrMap = Mapping[str, object]
+type IrJson = bool | int | float | str | list[IrJson] | dict[str, IrJson] | None
+"""A JSON value as the generated code writes it, so a type checker reads each empty object or array it holds."""
+
+_EMPTY: IrMap = {}
+
+
+def ir_map(node: object, key: str) -> IrMap:
+    value = node.get(key) if isinstance(node, Mapping) else None
+
+    return value if isinstance(value, Mapping) else _EMPTY
+
+
+def ir_list(node: object, key: str) -> Sequence[object]:
+    value = node.get(key) if isinstance(node, Mapping) else None
+
+    return value if isinstance(value, list | tuple) else ()
+
+
+def ir_maps(node: object, key: str) -> list[IrMap]:
+    """Each member of the list that is a map."""
+    return [item for item in ir_list(node, key) if isinstance(item, Mapping)]
+
+
+def ir_string(node: object, key: str) -> str | None:
+    value = node.get(key) if isinstance(node, Mapping) else None
+
+    return value if isinstance(value, str) else None
+
+
+def ir_strings(node: object, key: str) -> list[str]:
+    return [item for item in ir_list(node, key) if isinstance(item, str)]
+
+
+def ir_int(node: object, key: str) -> int | None:
+    value = node.get(key) if isinstance(node, Mapping) else None
+
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def ir_true(node: object, key: str) -> bool:
+    return isinstance(node, Mapping) and node.get(key) is True

seampact/codegen/runtime/native_docs.py

@@ -0,0 +1,130 @@
+"""seampact's operation objects and components a `nativeDocs` placement carries (ADR 0026 "Native docs"), read from the
+generated `native_docs.json`, and how they join the framework's own OpenAPI document (FastAPI's, Django Ninja's): each
+contract operation at seampact's path under the entry's `mount`, and seampact's components beside the app's; a
+component the app's document already holds with another value is refused, naming it."""
+
+import copy
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+_OPERATIONS: Final = "operations"
+_COMPONENTS: Final = "components"
+_PATH: Final = "path"
+_METHOD: Final = "method"
+_OPERATION: Final = "operation"
+
+type JsonObject = dict[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentJoin:
+    """Whose document the api's operations join, as a refusal names them: the framework's and the api's names."""
+
+    framework: str
+    api: str
+
+
+@dataclass(frozen=True, slots=True)
+class NativeOperation:
+    """seampact's operation object of one contract operation, with the path and lower-case method it sits under in
+    seampact's document."""
+
+    path: str
+    method: str
+    operation: JsonObject
+
+
+@dataclass(frozen=True, slots=True)
+class NativeDocs:
+    """What `nativeDocs` adds to FastAPI's document: each kept operation's object by operation id, and seampact's
+    components by kind and name."""
+
+    operations: Mapping[str, NativeOperation]
+    components: Mapping[str, JsonObject]
+
+
+class NativeDocsError(Exception):
+    """The framework's document and seampact's name one component with two values, or the generated file does not
+    read."""
+
+
+def read_native_docs(file: Path) -> NativeDocs:
+    """The generated `native_docs.json` beside the placement module."""
+    document = json_object(json.loads(file.read_text(encoding="utf-8")), file.name)
+    operations: dict[str, NativeOperation] = {}
+
+    for operation_id, item in json_object(document.get(_OPERATIONS), _OPERATIONS).items():
+        native = json_object(item, operation_id)
+        operations[operation_id] = NativeOperation(
+            _text_member(native, _PATH, operation_id),
+            _text_member(native, _METHOD, operation_id),
+            json_object(native.get(_OPERATION), operation_id),
+        )
+
+    components = {
+        kind: json_object(named, kind) for kind, named in json_object(document.get(_COMPONENTS), _COMPONENTS).items()
+    }
+
+    return NativeDocs(operations, components)
+
+
+def _text_member(native: JsonObject, key: str, operation_id: str) -> str:
+    value = native.get(key)
+
+    if not isinstance(value, str):
+        raise NativeDocsError(
+            f"seampact: the operation '{operation_id}' of native_docs.json has no '{key}'; run `seampact generate`."
+        )
+
+    return value
+
+
+def json_object(value: object, where: str) -> JsonObject:
+    if not isinstance(value, dict):
+        raise NativeDocsError(f"seampact: '{where}' of the OpenAPI document is not an object; run `seampact generate`.")
+
+    return value
+
+
+def require_every_operation(operation_ids: Iterable[str], native_docs: NativeDocs) -> None:
+    """An operation `native_docs.json` lacks means the file is stale or edited: fail at boot, not in the document."""
+    for operation_id in operation_ids:
+        if operation_id not in native_docs.operations:
+            raise NativeDocsError(
+                f"seampact: native_docs.json holds no operation '{operation_id}', which the api serves; "
+                "run `seampact generate`."
+            )
+
+
+def add_native_docs(
+    document: JsonObject, operation_ids: Iterable[str], mount: str, native_docs: NativeDocs, joined: DocumentJoin
+) -> None:
+    """Each operation at seampact's path under `mount`, with the contract's parameter names, then the components."""
+    paths = _member(document, "paths")
+
+    for operation_id in operation_ids:
+        native = native_docs.operations[operation_id]
+        _member(paths, mount.rstrip("/") + native.path)[native.method] = copy.deepcopy(native.operation)
+
+    components = _member(document, _COMPONENTS)
+
+    for kind, named in native_docs.components.items():
+        held = _member(components, kind)
+
+        for name, value in named.items():
+            if name in held and held[name] != value:
+                raise NativeDocsError(
+                    f"seampact: {joined.framework}'s document already holds the component {kind} '{name}', and api "
+                    f"'{joined.api}' declares another one under that name. Rename the app's model, or switch "
+                    "`nativeDocs` off."
+                )
+
+            held[name] = copy.deepcopy(value)
+
+
+def _member(document: JsonObject, key: str) -> JsonObject:
+    """The object `document` holds at `key`, added empty when absent."""
+    return json_object(document.setdefault(key, {}), key)