seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/runtime/contract.py

@@ -0,0 +1,232 @@
+"""The api's contract as the boundary reads it: the IR view of the kept operations and the declarations they read,
+which the generated code holds as JSON values, the Python names of each schema's members, and the routes, built once
+per process."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Final
+
+from seampact.codegen.runtime.ir_view import IrJson, IrMap, ir_int, ir_map, ir_maps, ir_string
+from seampact.codegen.runtime.response_header_entries import HeaderEntry, HeaderProblem, response_header_entry
+from seampact.codegen.runtime.route_match import ContractRoute, RouteMatch, most_specific_first
+
+NOT_FOUND_ROLE: Final = "notFound"
+# The role a framework's HTTP error takes on a contract route, by its status; another status has no role.
+ROLE_OF_STATUS: Final[Mapping[int, str]] = {
+    401: "unauthenticated",
+    403: "forbidden",
+    404: NOT_FOUND_ROLE,
+    413: "payloadTooLarge",
+    429: "rateLimited",
+    503: "serviceUnavailable",
+}
+UNDECLARED_STATUS_ROLE: Final = "undeclaredStatus"
+INTERNAL_STATUS: Final = 500
+
+PATH_PART: Final = "path"
+QUERY_PART: Final = "query"
+HEADER_PART: Final = "header"
+PROOFS_PART: Final = "proofs"
+"""The parts of an operation's input whose wire names `operation_members` maps: its path, query and header
+parameters (the credential and CSRF headers stay the boundary's), and the rule proofs read in its body. The header
+part is spelled as the IR spells it."""
+_KNOWN_PARTS: Final = (PATH_PART, QUERY_PART, HEADER_PART, PROOFS_PART)
+
+_IGNORE_POLICY: Final = "ignore"
+_REFUSE_POLICY: Final = "refuse"
+_HEAD: Final = "HEAD"
+_GET: Final = "GET"
+
+
+@dataclass(frozen=True, slots=True)
+class ApiContract:
+    """`ir_view` is the IR's JSON subset the generator wrote (`api`, `formats`, `errors`, `schemas`, `enums`,
+    `operations`, and the access declarations `identities`, `schemes`, `scopes`, `rights`, `rules`, `buckets` and
+    `pagings`); `members` maps each schema id to its members' wire names and Python attribute names;
+    `operation_members` maps each operation id, then each part of its input, to the same; `params_models` maps the
+    params schema id of each right and rule to its generated class; `mount` is the entry's prefix of every contract
+    path, empty for none."""
+
+    api: str
+    generated_by: str
+    mount: str
+    ir_view: Mapping[str, IrJson]
+    members: Mapping[str, Mapping[str, str]]
+    operation_members: Mapping[str, Mapping[str, Mapping[str, str]]]
+    params_models: Mapping[str, type] = field(default_factory=dict[str, type])
+    _operations: dict[str, IrMap] = field(init=False, repr=False)
+    _routes: tuple[ContractRoute, ...] = field(init=False, repr=False)
+    _base_paths: tuple[str, ...] = field(init=False, repr=False)
+    _header_entries: dict[tuple[str, int], tuple[HeaderEntry | HeaderProblem, ...]] = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        operations: dict[str, IrMap] = {}
+        routes: list[ContractRoute] = []
+        base_paths: list[str] = []
+        surfaces = ir_map(ir_map(self.ir_view, "api"), "surfaces")
+
+        for operation in ir_maps(self.ir_view, "operations"):
+            operation_id = ir_string(operation, "id") or ""
+            base_path = self.mount + (
+                ir_string(ir_map(surfaces, ir_string(operation, "surface") or ""), "prefix") or ""
+            )
+            template = self.mount + (ir_string(operation, "path") or "")
+            operations[operation_id] = operation
+            routes.append(ContractRoute.of(operation_id, ir_string(operation, "method") or "", template, base_path))
+
+            if base_path not in base_paths:
+                base_paths.append(base_path)
+
+        object.__setattr__(self, "_operations", operations)
+        object.__setattr__(self, "_routes", tuple(most_specific_first(routes)))
+        object.__setattr__(self, "_base_paths", tuple(base_paths))
+        object.__setattr__(self, "_header_entries", self._resolved_header_entries())
+
+    def _resolved_header_entries(self) -> dict[tuple[str, int], tuple[HeaderEntry | HeaderProblem, ...]]:
+        """The derived header entries of each response, by operation and status, resolved once: a read's ETag looks
+        through every operation for its `If-Match` writes."""
+        operations = list(self._operations.values())
+        resolved: dict[tuple[str, int], tuple[HeaderEntry | HeaderProblem, ...]] = {}
+
+        for operation_id, operation in self._operations.items():
+            for response in ir_maps(operation, "responses"):
+                entries = (
+                    response_header_entry(self.api, self.mount, operations, operation, header)
+                    for header in ir_maps(response, "headers")
+                )
+                resolved[(operation_id, ir_int(response, "status") or 0)] = tuple(
+                    entry for entry in entries if entry is not None
+                )
+
+        return resolved
+
+    def response_header_entries(self, operation_id: str, status: int) -> tuple[HeaderEntry | HeaderProblem, ...]:
+        """The entries the boundary writes the derived headers of the operation's `status` response from, or why it
+        cannot; empty for a response that derives none."""
+        return self._header_entries.get((operation_id, status), ())
+
+    def operation(self, operation_id: str) -> IrMap:
+        """Raises `LookupError` for an operation the api does not keep."""
+        operation = self._operations.get(operation_id)
+
+        if operation is None:
+            raise LookupError(f"The api '{self.api}' has no operation '{operation_id}'.")
+
+        return operation
+
+    def part_members(self, operation_id: str, part: str) -> Mapping[str, str]:
+        """The wire names of one part of the operation's input and their Python attributes, empty for a part it does not
+        have. Raises `ValueError` for a part name that is none of the known parts."""
+        if part not in _KNOWN_PARTS:
+            raise ValueError(
+                f"Unknown part '{part}' of an operation's input; the known parts are {', '.join(_KNOWN_PARTS)}."
+            )
+
+        self.operation(operation_id)
+
+        return self.operation_members.get(operation_id, {}).get(part, {})
+
+    def ignores_unknown_query(self, operation_id: str) -> bool:
+        """Whether the operation ignores the query keys it does not declare, rather than refusing them."""
+        return ir_string(ir_map(self.operation(operation_id), "unknownQuery"), "policy") == _IGNORE_POLICY
+
+    def unknown_keys_policy(self, operation_id: str) -> str:
+        """`refuse`, `ignore` or `keep`: what the operation's body does with a key its schema does not declare; the
+        names of the body's rule proofs are declared keys."""
+        input_use = ir_map(ir_map(self.operation(operation_id), "input"), "schema")
+
+        return ir_string(ir_map(input_use, "unknownKeys"), "policy") or _REFUSE_POLICY
+
+    def operation_ids(self) -> list[str]:
+        return list(self._operations)
+
+    def base_paths(self) -> tuple[str, ...]:
+        return self._base_paths
+
+    def match(self, method: str, raw_path: str) -> RouteMatch | None:
+        """The operation the raw path matches; an unserved match for a path under a base path that no route serves
+        with this method; None for a path under none of the api's base paths."""
+        if not any(_under(raw_path, base_path) for base_path in self._base_paths):
+            return None
+
+        route_method = _GET if method.upper() == _HEAD else method.upper()
+        segments = raw_path.split("/")[1:]
+
+        for route in self._routes:
+            parameters = route.match(segments)
+
+            if parameters is not None and route.method == route_method:
+                return RouteMatch(route.operation_id, parameters)
+
+        return RouteMatch(None, {})
+
+    def route_name(self, operation_id: str) -> str:
+        """The name the generated route declaration gives an operation."""
+        return f"seampact.{self.api}.{operation_id}"
+
+    def role_code(self, operation_id: str | None, role: str) -> str | None:
+        """The code an operation declares for `role`, else a catalogued code whose default role it is and that the
+        operation declares; with no operation, the first code any operation declares for the role."""
+        operations = list(self._operations.values()) if operation_id is None else [self.operation(operation_id)]
+
+        for operation in operations:
+            for error in ir_maps(operation, "errors"):
+                if any(ir_string(declared, "role") == role for declared in ir_maps(error, "roles")):
+                    return ir_string(error, "code")
+
+        if operation_id is None:
+            return None
+
+        for code, catalogued in ir_map(self.ir_view, "errors").items():
+            if ir_string(catalogued, "default") == role and self.declares(operation_id, code):
+                return code
+
+        return None
+
+    def role_params(self, operation_id: str, code: str, role: str) -> object:
+        """The params template a role binds on one of the operation's codes, None when it binds none."""
+        for declared in ir_maps(self.error_declaration(operation_id, code), "roles"):
+            if ir_string(declared, "role") == role:
+                return declared.get("params")
+
+        return None
+
+    def error_declaration(self, operation_id: str, code: str) -> IrMap:
+        """The operation's entry for `code` (its roles and retry header), empty when it declares none."""
+        for error in ir_maps(self.operation(operation_id), "errors"):
+            if ir_string(error, "code") == code:
+                return error
+
+        return {}
+
+    def declares(self, operation_id: str, code: str) -> bool:
+        return bool(self.error_declaration(operation_id, code))
+
+    def catalog_entry(self, code: str) -> IrMap:
+        return ir_map(ir_map(self.ir_view, "errors"), code)
+
+    def status_of(self, code: str) -> int:
+        return ir_int(ir_map(self.catalog_entry(code), "http"), "status") or INTERNAL_STATUS
+
+    def declared_codes(self, operation_id: str, status: int) -> list[str]:
+        """The operation's codes answered with `status`."""
+        codes = [ir_string(error, "code") for error in ir_maps(self.operation(operation_id), "errors")]
+
+        return [code for code in codes if code is not None and self.status_of(code) == status]
+
+    def format(self, operation_id: str | None) -> IrMap:
+        """The wire format an operation answers in; the api's first format when no operation matched."""
+        formats = ir_map(self.ir_view, "formats")
+        format_id = None if operation_id is None else ir_string(self.operation(operation_id), "format")
+
+        if format_id is None:
+            format_id = next(iter(formats), "")
+
+        return ir_map(formats, format_id)
+
+    def declaration(self, kind: str, declaration_id: str) -> IrMap:
+        return ir_map(ir_map(self.ir_view, kind), declaration_id)
+
+
+def _under(raw_path: str, base_path: str) -> bool:
+    return base_path == "" or raw_path == base_path or raw_path.startswith(base_path + "/")

seampact/codegen/runtime/cors_preflight.py

@@ -0,0 +1,20 @@
+"""A CORS preflight: an `OPTIONS` request with `Origin` and `Access-Control-Request-Method`, which no contract
+operation declares. A boundary leaves it to the app's CORS layer, as the PHP boundaries do, rather than answering the
+path's 404 for a method the path does not serve."""
+
+from collections.abc import Iterable
+from typing import Final
+
+_PREFLIGHT_METHOD: Final = "OPTIONS"
+_ORIGIN: Final = "origin"
+_REQUESTED_METHOD: Final = "access-control-request-method"
+
+
+def is_cors_preflight(method: str, header_names: Iterable[str]) -> bool:
+    """`header_names` in any case; the method as sent, since HTTP methods are case-sensitive."""
+    if method != _PREFLIGHT_METHOD:
+        return False
+
+    names = {name.lower() for name in header_names}
+
+    return _ORIGIN in names and _REQUESTED_METHOD in names

seampact/codegen/runtime/deadline.py

@@ -0,0 +1,72 @@
+"""The request deadline (grammar section 9, a header of semantic `deadline`): an RFC 3339 instant the caller sends in
+the operation's `deadlineHeader`. The boundary refuses a malformed one with `schemaInvalid` and a passed one with the
+`deadlineExceeded` role's code; the generated request's `deadline` gives the handler the time left. An operation's
+`budgetMs` alone is the client's default timeout: the server receives nothing of it beside this header."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Final
+
+from seampact.codegen.runtime.contract import ApiContract
+from seampact.codegen.runtime.failures import ContractRefusal
+from seampact.codegen.runtime.input_decoding import DecodedInput, Issue, role_refusal, schema_invalid
+from seampact.codegen.runtime.ir_view import ir_string
+from seampact.codegen.runtime.value_rules import ValueRuleError, date_time_from_text
+
+DEADLINE_EXCEEDED_ROLE: Final = "deadlineExceeded"
+
+_HEADER_PART: Final = "header"
+_FORMAT_RULE: Final = "format"
+_MILLISECONDS_PER_SECOND: Final = 1000
+
+
+@dataclass(frozen=True, slots=True)
+class RequestDeadline:
+    """The instant the caller stops waiting, aware of its offset."""
+
+    at: datetime
+
+    def remaining_ms(self, now: datetime) -> int:
+        """The whole milliseconds left at `now`, 0 once the deadline has passed."""
+        return max(int((self.at - now).total_seconds() * _MILLISECONDS_PER_SECOND), 0)
+
+    def has_passed(self, now: datetime) -> bool:
+        return now >= self.at
+
+
+def request_deadline(
+    contract: ApiContract, operation_id: str, decoded: DecodedInput, now: datetime
+) -> RequestDeadline | None:
+    """The deadline the request carries, None when the operation reads none or the caller sent none (a required
+    header was refused by the input step).
+
+    Raises `ContractRefusal` for a malformed deadline, or one passed at `now`."""
+    header = ir_string(contract.operation(operation_id), "deadlineHeader")
+    sent = None if header is None else decoded.headers.get(header)
+
+    if header is None or sent is None:
+        return None
+
+    try:
+        deadline = RequestDeadline(date_time_from_text(str(sent)))
+    except ValueRuleError:
+        raise schema_invalid(
+            contract, operation_id, [Issue(_HEADER_PART, f"/{header.lower()}", _FORMAT_RULE)]
+        ) from None
+
+    if deadline.has_passed(now):
+        raise deadline_exceeded(contract, operation_id)
+
+    return deadline
+
+
+def sent_deadline(text: str | None) -> RequestDeadline | None:
+    """The deadline a header's text carries, None when the caller sent none.
+
+    Raises `ValueRuleError` for a text that is not an RFC 3339 instant with its offset."""
+    return None if text is None else RequestDeadline(date_time_from_text(text))
+
+
+def deadline_exceeded(contract: ApiContract, operation_id: str) -> ContractRefusal:
+    """The refusal a handler raises when the deadline passes while it works."""
+    return role_refusal(contract, operation_id, DEADLINE_EXCEEDED_ROLE)

seampact/codegen/runtime/digests.py

@@ -0,0 +1,98 @@
+"""The SHA-256 digests of the boundary (the throttle bucket key, and later the idempotency key and the strong ETag),
+over the text `JSON.stringify` writes with object members sorted by name, so every target derives the same key from
+the same values (ADR 0023 "Query and bounded values")."""
+
+import hashlib
+import json
+import math
+import re
+from collections.abc import Mapping, Sequence
+from typing import Final
+
+# `JSON.stringify` writes an exponent from 1e21 up and below 1e-6.
+_PLAIN_UPPER_EXPONENT: Final = 21
+_PLAIN_LOWER_EXPONENT: Final = -6
+# 2^32 - 1, the first integer that is not an array index in JavaScript.
+_NOT_AN_INDEX: Final = 4294967295
+_INDEX_NAME: Final = re.compile(r"(?:0|[1-9][0-9]{0,9})")
+_DECIMAL_TEXT: Final = re.compile(r"(-?)([0-9]+)(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?")
+_UTF16: Final = "utf-16-be"
+
+
+def hex_of(parts: Sequence[object]) -> str:
+    """The SHA-256 of the canonical JSON of `parts`, as lowercase hex."""
+    return hashlib.sha256(canonical(list(parts)).encode("utf-8", errors="surrogatepass")).hexdigest()
+
+
+def canonical(value: object) -> str:
+    """`value` as `JSON.stringify` writes it, object members sorted by name. Raises `TypeError` for a value JSON
+    cannot hold."""
+    if value is None:
+        return "null"
+
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    if isinstance(value, int):
+        return str(value)
+
+    if isinstance(value, float):
+        return _number(value)
+
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+
+    if isinstance(value, Mapping):
+        names = sorted((str(name) for name in value), key=_name_order)
+        members = {str(name): member for name, member in value.items()}
+
+        return (
+            "{" + ",".join(f"{json.dumps(name, ensure_ascii=False)}:{canonical(members[name])}" for name in names) + "}"
+        )
+
+    if isinstance(value, list | tuple):
+        return "[" + ",".join(canonical(item) for item in value) + "]"
+
+    raise TypeError(f"seampact: a digest cannot read a {type(value).__qualname__}.")
+
+
+def _name_order(name: str) -> tuple[int, bytes]:
+    """Array-index names first in numeric order, as every JavaScript object orders its own keys, then the others by
+    UTF-16 code units, as JavaScript's default sort compares them."""
+    index = min(int(name), _NOT_AN_INDEX) if _INDEX_NAME.fullmatch(name) else _NOT_AN_INDEX
+
+    return index, name.encode(_UTF16, errors="surrogatepass")
+
+
+def _number(value: float) -> str:
+    """A number as JavaScript prints its double: the shortest digits, plain between 1e-6 and 1e21, an exponent
+    outside."""
+    if not math.isfinite(value):
+        return "null"
+
+    if value == 0:
+        return "0"
+
+    parts = _DECIMAL_TEXT.fullmatch(repr(value))
+
+    if parts is None:
+        raise ValueError(f"seampact: the number {value!r} has no decimal form.")
+
+    sign, integral, fraction, exponent_text = parts.group(1), parts.group(2), parts.group(3) or "", parts.group(4)
+    digits = (integral + fraction).lstrip("0")
+    leading_zeros = len(integral + fraction) - len(digits)
+    exponent = int(exponent_text or "0") + len(integral) - 1 - leading_zeros
+    digits = digits.rstrip("0")
+
+    if exponent >= _PLAIN_UPPER_EXPONENT or exponent < _PLAIN_LOWER_EXPONENT:
+        mantissa = digits if len(digits) == 1 else f"{digits[0]}.{digits[1:]}"
+
+        return f"{sign}{mantissa}e{'-' if exponent < 0 else '+'}{abs(exponent)}"
+
+    if exponent < 0:
+        return f"{sign}0.{'0' * (-exponent - 1)}{digits}"
+
+    whole = digits[: exponent + 1].ljust(exponent + 1, "0")
+    decimals = digits[exponent + 1 :]
+
+    return f"{sign}{whole}{'.' + decimals if decimals else ''}"

seampact/codegen/runtime/failures.py

@@ -0,0 +1,33 @@
+"""What stops a contract request before its handler's reply: a refusal answered with one of the api's codes, and a
+failure of the boundary itself, answered with the api's 500; and how a log line names a failure."""
+
+import traceback
+
+from seampact.codegen.runtime.ir_view import IrMap
+
+
+class ContractRefusal(Exception):  # noqa: N818 - a refusal is an answer, not an error of the app
+    """A request the boundary answers with `code` of `api`, its params rendered from the code's role binding."""
+
+    def __init__(self, api: str, code: str, params: IrMap | None = None) -> None:
+        super().__init__(f"seampact: the '{api}' boundary refuses the request with '{code}'.")
+        self.api = api
+        self.code = code
+        self.params = params
+
+
+class BoundaryFailureError(RuntimeError):
+    """A fault of the generated code or the handler that the boundary answers with the api's 500, logged with the
+    cause."""
+
+
+def failure_place(failure: BaseException) -> str:
+    """The exception's class and where it was raised; the boundary's own failures name no input and keep their
+    message. Any other message may carry an input value, so it is left to the caller's debug mode."""
+    if isinstance(failure, BoundaryFailureError):
+        return str(failure)
+
+    frames = traceback.extract_tb(failure.__traceback__)
+    where = f"{frames[-1].filename}:{frames[-1].lineno}" if frames else "an unknown place"
+
+    return f"{type(failure).__qualname__} raised at {where}"

seampact/codegen/runtime/field_rights.py

@@ -0,0 +1,193 @@
+"""Field rights (ADR 0012 "Field rights"): step 7 refuses a restricted top-level input member sent without its right,
+or leaves it out under `inputPolicy: strip`; before a success is written, each restricted output member whose right
+the decider denies for its holder is left out, one decision per right, use-site params, pointer and subject, and a
+member the contract never sends on the operation (`always: absent`) is left out without a decision. Each returns a
+copy; the tree it reads is never changed."""
+
+import copy
+import json
+from collections.abc import Mapping
+from typing import Final
+
+from seampact.codegen.runtime.access_steps import (
+    AccessHooks,
+    AccessState,
+    HookCaller,
+    decided,
+    extensions_of,
+    refusal_of,
+    subject_of,
+    subject_type,
+)
+from seampact.codegen.runtime.failures import ContractRefusal
+from seampact.codegen.runtime.ir_view import IrMap, ir_map, ir_maps, ir_string
+from seampact.codegen.runtime.replies import role_params
+from seampact.codegen.runtime.requirement_params import requirement_params
+from seampact.hooks import FieldDirection, RequirementKind, RequirementRequest, SubjectRef, decision, purpose
+
+_INPUT: Final = "input"
+_OUTPUT: Final = "output"
+_STRIP: Final = "strip"
+_ABSENT: Final = "absent"
+_FORBIDDEN_ROLE: Final = "forbidden"
+_HOLDER_FIELD: Final = "holderField"
+_WILDCARD: Final = "*"
+_TABLE_SHAPE: Final = "table"
+_ITEMS_SHAPES: Final = frozenset({"list", "page"})
+
+
+async def checked_input_fields(state: AccessState, hooks: AccessHooks, call: HookCaller) -> object:
+    """The decoded body with each restricted member the decider denies left out under `strip`.
+
+    Raises `ContractRefusal` with the denial's code, its params joined by the `forbidden` role's `pointer`, for a
+    denied member under `reject`."""
+    if not isinstance(state.body, Mapping):
+        return state.body
+
+    body = copy.deepcopy(dict(state.body))
+
+    for field_right in ir_maps(state.contract.operation(state.operation_id), "fieldRights"):
+        if ir_string(field_right, "direction") != _INPUT:
+            continue
+
+        pointer = ir_string(field_right, "pointer") or ""
+        member = "/".join(_pointer_segments(pointer))
+
+        if member not in body:
+            continue
+
+        right = ir_string(field_right, "right") or ""
+        subject = subject_of(state, ir_map(field_right, "subject"), right)
+        answer = await decided(hooks, call, _request(state, field_right, subject, FieldDirection.INPUT))
+
+        if isinstance(answer, decision.Allowed):
+            continue
+
+        if ir_string(field_right, "inputPolicy") == _STRIP:
+            del body[member]
+            continue
+
+        raise _forbidden_field(state, answer, pointer)
+
+    return body
+
+
+async def visible_output(
+    state: AccessState, hooks: AccessHooks, call: HookCaller, response: IrMap, wire_body: object
+) -> object:
+    """The success body as the wire writes it, without each restricted member its holder may not see."""
+    body = copy.deepcopy(wire_body)
+    decisions: dict[tuple[str, str, str, str], bool] = {}
+    body_schema = ir_string(ir_map(response, "body"), "schema")
+
+    for field_right in ir_maps(state.contract.operation(state.operation_id), "fieldRights"):
+        if ir_string(field_right, "direction") != _OUTPUT or ir_string(field_right, "schema") != body_schema:
+            continue
+
+        segments = _pointer_segments(ir_string(field_right, "pointer") or "")
+        member = segments.pop()
+
+        for instance in _instances(body, ir_string(response, "shape")):
+            for holder in _holders(instance, segments):
+                if member in holder and not await _allowed(state, hooks, call, field_right, holder, decisions):
+                    del holder[member]
+
+    return body
+
+
+async def _allowed(
+    state: AccessState,
+    hooks: AccessHooks,
+    call: HookCaller,
+    field_right: IrMap,
+    holder: Mapping[str, object],
+    decisions: dict[tuple[str, str, str, str], bool],
+) -> bool:
+    if ir_string(field_right, "always") == _ABSENT:
+        return False
+
+    right = ir_string(field_right, "right") or ""
+    source = ir_map(ir_map(field_right, "subject"), "source")
+    subject = None
+
+    if ir_string(source, "in") == _HOLDER_FIELD:
+        holder_id = holder.get(ir_string(source, "name") or "")
+
+        # A holder without a usable id names no subject: the decider is asked with none.
+        if isinstance(holder_id, str | int) and not isinstance(holder_id, bool):
+            subject = SubjectRef(type=subject_type(state.contract, right), id=holder_id)
+    elif source:
+        subject = subject_of(state, ir_map(field_right, "subject"), right)
+
+    # The decider sees the field's params and pointer, so both join the key.
+    use_site_params = json.dumps(field_right.get("params"), sort_keys=True)
+    pointer = ir_string(field_right, "pointer") or ""
+    key = (right, use_site_params, pointer, "" if subject is None else repr(subject.id))
+
+    if key not in decisions:
+        answer = await decided(hooks, call, _request(state, field_right, subject, FieldDirection.OUTPUT))
+        decisions[key] = isinstance(answer, decision.Allowed)
+
+    return decisions[key]
+
+
+def _pointer_segments(pointer: str) -> list[str]:
+    """The member names a JSON pointer walks, `~1` and `~0` unescaped."""
+    return [segment.replace("~1", "/").replace("~0", "~") for segment in pointer[1:].split("/")]
+
+
+def _instances(body: object, shape: str | None) -> list[object]:
+    """A table's values and a list's or page's items are each an instance of the body's schema."""
+    if shape == _TABLE_SHAPE:
+        return list(body.values()) if isinstance(body, dict) else []
+
+    if shape in _ITEMS_SHAPES:
+        return list(body) if isinstance(body, list) else []
+
+    return [body]
+
+
+def _holders(instance: object, segments: list[str]) -> list[dict[str, object]]:
+    """The objects a pointer's parent segments reach, `*` standing for every item of an array."""
+    current = [instance]
+
+    for segment in segments:
+        reached: list[object] = []
+
+        for node in current:
+            if segment == _WILDCARD and isinstance(node, list):
+                reached.extend(node)
+            elif isinstance(node, dict) and segment in node:
+                reached.append(node[segment])
+
+        current = reached
+
+    return [node for node in current if isinstance(node, dict)]
+
+
+def _request(
+    state: AccessState, field_right: IrMap, subject: SubjectRef | None, direction: FieldDirection
+) -> RequirementRequest:
+    name = ir_string(field_right, "right") or ""
+    operation = state.contract.operation(state.operation_id)
+
+    return RequirementRequest(
+        kind=RequirementKind.RIGHT,
+        name=name,
+        params=requirement_params(state.contract, RequirementKind.RIGHT, name, field_right),
+        principal=state.principal,
+        subject=subject,
+        scopes=tuple(state.scopes),
+        purpose=purpose.Field(pointer=ir_string(field_right, "pointer") or "", direction=direction),
+        operation=state.operation,
+        request=state.request,
+        extensions=RequirementRequest.Extensions(requirement={}, operation=extensions_of(operation)),
+    )
+
+
+def _forbidden_field(state: AccessState, denied: decision.Denied, pointer: str) -> ContractRefusal:
+    refusal = refusal_of(state, denied.deny)
+    rendered = role_params(state.contract, state.operation_id, refusal.code, _FORBIDDEN_ROLE, {"pointer": pointer})
+    params = {**(refusal.params or {}), **(rendered or {})}
+
+    return ContractRefusal(state.contract.api, refusal.code, params)