seampact-codegen 1.0.0__py3-none-any.whl

seampact/codegen/pydantic_models.py

@@ -0,0 +1,405 @@
+"""The Pydantic emitter FastAPI and Ninja share (ADR 0026 "Types and validation"): a `StrEnum` per enum and a strict,
+frozen model per object schema (`protected_namespaces=()`, unknown keys refused), each member typed by the runtime's
+type layer (`WholeNumber`, `WireDateTime`, `WireUuid`, ...), and the value rules as Pydantic's own `Field`
+constraints under `rules: native` or as the runtime's validators under `seampact-consistent`. A member both optional
+and nullable is a `Field` of `seampact.hooks`. A model holding a sensitive member gets a `__repr_args__` that prints it
+as `[redacted]`, which Pydantic's `repr`, `str` and rich output read (ADR 0026 "Redaction"). Framework names are
+imported under private aliases."""
+
+from collections.abc import Sequence
+from decimal import Decimal
+from enum import StrEnum
+from typing import Final
+
+from seampact.codegen.names import ApiNames
+from seampact.codegen.printer import INDENT, PythonModule, fits, string_literal
+from seampact.codegen.redacted_members import REDACTED_CLASS, redacted_marker_block
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.ir.hydration import OMITTED
+from seampact.ir.model import (
+    ArrayTypeUse,
+    ContractIR,
+    EnumTypeUse,
+    MapSchema,
+    ObjectSchema,
+    OpaqueTypeUse,
+    Property,
+    Refinements,
+    RefTypeUse,
+    ScalarType,
+    ScalarTypeUse,
+    TypeUse,
+    UnionSchema,
+)
+
+# The Pydantic the generated models are written for; the boot check refuses another major.
+PYDANTIC_PACKAGE: Final = "pydantic"
+PYDANTIC_MAJOR: Final = "2"
+
+
+class RulesMode(StrEnum):
+    NATIVE = "native"
+    SEAMPACT_CONSISTENT = "seampact-consistent"
+
+
+_MODEL_CONFIG: Final = "_MODEL_CONFIG"
+_OR_NONE: Final = " | None"
+_NATIVE_BOUNDS: Final = {"minimum": "ge", "maximum": "le", "exclusive_minimum": "gt", "exclusive_maximum": "lt"}
+_FORMAT_TYPES: Final = {
+    "date-time": "WireDateTime",
+    "date": "WireDate",
+    "uuid": "WireUuid",
+    "decimal": "WireDecimal",
+}
+
+
+class _Emission:
+    def __init__(self, ir: ContractIR, names: ApiNames, rules: RulesMode, refusals: Refusals) -> None:
+        self.ir = ir
+        self.names = names
+        self.rules = rules
+        self.refusals = refusals
+        self.module = PythonModule(f"The schema types of api '{ir.api.id}'.")
+        self.pydantic = self.module.imported("pydantic", "_pydantic")
+        self.typing = self.module.imported("typing", "_typing")
+        self.seampact = self.module.imported("seampact.codegen.runtime.pydantic", "_seampact")
+        self._objects = {key: value for key, value in ir.schemas.items() if isinstance(value, ObjectSchema)}
+        self._defined: set[str] = set()
+        self._redacted_declared = False
+
+    def text(self) -> str:
+        self.module.add_block(
+            [
+                f"{_MODEL_CONFIG} = {self.pydantic}.ConfigDict(",
+                f"{INDENT}strict=True,",
+                f"{INDENT}frozen=True,",
+                f'{INDENT}extra="forbid",',
+                f"{INDENT}protected_namespaces=(),",
+                f'{INDENT}regex_engine="rust-regex",',
+                f"{INDENT}allow_inf_nan=False,",
+                f"{INDENT}hide_input_in_errors=True,",
+                ")",
+            ]
+        )
+
+        for enum_id in sorted(self.ir.enums):
+            self._enum(enum_id)
+
+        for schema_id in self._dependency_order():
+            self._model(schema_id, self._objects[schema_id], IrPlace(f"/schemas/{schema_id}"))
+
+        for schema_id, schema in sorted(self.ir.schemas.items()):
+            at = IrPlace(f"/schemas/{schema_id}")
+
+            if isinstance(schema, ObjectSchema):
+                continue
+
+            if isinstance(schema, MapSchema | UnionSchema):
+                self.refusals.waiting(f"schema.{schema.kind}", f"A {schema.kind} schema", at, Delivery.CONSUMER)
+            else:
+                self.refusals.unknown_value(schema.kind, at.below("kind"))
+
+        return self.module.text()
+
+    def _dependency_order(self) -> list[str]:
+        """Object schemas by id, each after the schemas its members name, so a model names only defined classes; a
+        cycle names the later class as a string."""
+        ordered: list[str] = []
+        visiting: set[str] = set()
+
+        def visit(schema_id: str) -> None:
+            if schema_id in ordered or schema_id in visiting:
+                return
+
+            visiting.add(schema_id)
+
+            for member in self._objects[schema_id].properties:
+                for referenced in _referenced_schemas(member.type):
+                    if referenced in self._objects:
+                        visit(referenced)
+
+            ordered.append(schema_id)
+
+        for schema_id in sorted(self._objects):
+            visit(schema_id)
+
+        return ordered
+
+    def _enum(self, enum_id: str) -> None:
+        enum_module = self.module.imported("enum", "_enum")
+        lines = [f"class {self.names.enum_classes[enum_id]}({enum_module}.StrEnum):"]
+
+        for value, member in self.names.enum_members[enum_id].items():
+            lines.append(f"{INDENT}{member} = {string_literal(value)}")
+
+        self.module.add_block(lines)
+
+    def _model(self, schema_id: str, schema: ObjectSchema, at: IrPlace) -> None:
+        lines = [f"class {self.names.schema_classes[schema_id]}({self.pydantic}.BaseModel):"]
+        lines.append(f"{INDENT}model_config = {_MODEL_CONFIG}")
+        members = self.names.members.get(schema_id, {})
+
+        if schema.properties:
+            lines.append("")
+
+        for index, member in enumerate(schema.properties):
+            attribute = members.get(member.name)
+
+            if attribute is not None:
+                lines.extend(self._member(attribute, member, at.below("properties", index)))
+
+        sensitive = [
+            members[member.name] for member in schema.properties if _is_sensitive(member) and member.name in members
+        ]
+
+        if sensitive:
+            lines.extend(self._redacted_repr_args(sensitive))
+
+        self._defined.add(schema_id)
+        self.module.add_block(lines)
+
+    def _redacted_repr_args(self, attributes: Sequence[str]) -> list[str]:
+        """The `__repr_args__` that prints each sensitive attribute as `[redacted]`; `model_dump` still shows it."""
+        abc = self.module.imported("collections.abc", "_abc")
+        self._declare_redacted()
+        names = ", ".join(string_literal(attribute) for attribute in attributes)
+        redacted = f"frozenset({{{names}}})"
+
+        return [
+            "",
+            f"{INDENT}def __repr_args__(self) -> {abc}.Iterator[tuple[str | None, object]]:",
+            f"{INDENT}{INDENT}for name, value in super().__repr_args__():",
+            f"{INDENT}{INDENT}{INDENT}yield name, {REDACTED_CLASS}() if name in {redacted} else value",
+        ]
+
+    def _declare_redacted(self) -> None:
+        if self._redacted_declared:
+            return
+
+        self._redacted_declared = True
+        self.module.add_block(redacted_marker_block())
+
+    def _member(self, attribute: str, member: Property, at: IrPlace) -> list[str]:
+        annotation = self.annotation(member.type, at.below("type"))
+        nullable = member.nullable or _use_nullable(member.type)
+
+        if member.default is not OMITTED:
+            self.refusals.waiting("member.default", "A member with a default", at.below("default"), Delivery.CONSUMER)
+
+        if member.optional and nullable:
+            hooks = self.module.imported("seampact.hooks", "_hooks")
+            return _wrapped(f"{INDENT}{attribute}: {hooks}.Field[", annotation, f" | None] = {hooks}.Absent.ABSENT")
+
+        if member.optional:
+            return _wrapped_in(f"{INDENT}{attribute}: {self.seampact}.Omittable[", annotation, "] = None")
+
+        return _wrapped(f"{INDENT}{attribute}: ", annotation, " | None" if nullable else "")
+
+    def annotation(self, type_use: TypeUse, at: IrPlace) -> list[str]:
+        """The annotation of a type use: one item, or the items of an `Annotated` that the printer may explode."""
+        if isinstance(type_use, ScalarTypeUse):
+            return self._scalar(type_use, at)
+
+        if isinstance(type_use, EnumTypeUse):
+            return self._enum_use(type_use, at)
+
+        if isinstance(type_use, RefTypeUse):
+            schema = self.ir.schemas.get(type_use.schema)
+            name = self.names.schema_classes.get(type_use.schema)
+
+            if not isinstance(schema, ObjectSchema) or name is None:
+                self.refusals.inconsistent("schema.ref.missing", f"No object schema '{type_use.schema}'", at)
+                return ["object"]
+
+            return [name if type_use.schema in self._defined else string_literal(name)]
+
+        if isinstance(type_use, ArrayTypeUse):
+            items = _joined(self.annotation(type_use.items, at.below("items")))
+            rules = self._length_rules(type_use.min_items, type_use.max_items)
+            return [f"list[{items}]"] if not rules else [f"{self.typing}.Annotated[", f"list[{items}]", *rules]
+
+        if isinstance(type_use, OpaqueTypeUse):
+            return [f"{self.seampact}.Opaque"]
+
+        self.refusals.waiting(f"type.{type_use.kind}", f"A type use of kind '{type_use.kind}'", at, Delivery.CONSUMER)
+        return ["object"]
+
+    def _enum_use(self, type_use: EnumTypeUse, at: IrPlace) -> list[str]:
+        if type_use.narrowed_to is not None:
+            self.refusals.waiting("enum.narrowed", "An enum narrowed at its use", at, Delivery.CONSUMER)
+
+        name = self.names.enum_classes.get(type_use.enum)
+
+        if name is None:
+            self.refusals.inconsistent("enum.missing", f"No enum '{type_use.enum}'", at)
+            return ["str"]
+
+        return [f"{self.typing}.Annotated[", name, f"{self.seampact}.enum_from_wire({name})"]
+
+    def _scalar(self, type_use: ScalarTypeUse, at: IrPlace) -> list[str]:
+        if not isinstance(type_use.type, ScalarType):
+            self.refusals.unknown_value(type_use.type.raw, at.below("type"))
+            return ["object"]
+
+        base = self._scalar_base(type_use, type_use.type, at)
+        rules = self._value_rules(type_use.refinements, type_use.type, at.below("refinements"))
+
+        return [base] if not rules else [f"{self.typing}.Annotated[", base, *rules]
+
+    def _scalar_base(self, type_use: ScalarTypeUse, scalar: ScalarType, at: IrPlace) -> str:
+        if type_use.format is not None:
+            wire_type = _FORMAT_TYPES.get(type_use.format)
+
+            if wire_type is None:
+                self.refusals.waiting(
+                    f"format.{type_use.format}", f"The format '{type_use.format}'", at, Delivery.CONSUMER
+                )
+                return "str"
+
+            return f"{self.seampact}.{wire_type}"
+
+        if scalar is ScalarType.INTEGER:
+            return f"{self.seampact}.WholeNumber"
+
+        return {ScalarType.NUMBER: "float", ScalarType.BOOLEAN: "bool"}.get(scalar, "str")
+
+    def _value_rules(self, refinements: Refinements, scalar: ScalarType, at: IrPlace) -> list[str]:
+        bounds = [
+            (key, value)
+            for key, value in (
+                ("minimum", refinements.minimum),
+                ("maximum", refinements.maximum),
+                ("exclusive_minimum", refinements.exclusive_minimum),
+                ("exclusive_maximum", refinements.exclusive_maximum),
+            )
+            if value is not None
+        ]
+        pattern = None if refinements.pattern is None else string_literal(refinements.pattern.normalized)
+
+        if self.rules is RulesMode.NATIVE:
+            arguments = _length_arguments(refinements.min_length, refinements.max_length)
+            arguments += [f"{_NATIVE_BOUNDS[key]}={number_literal(value, scalar)}" for key, value in bounds]
+
+            if refinements.multiple_of is not None:
+                arguments.append(f"multiple_of={number_literal(refinements.multiple_of, scalar)}")
+
+            if pattern is not None:
+                arguments.append(f"pattern={pattern}")
+
+            return [f"{self.pydantic}.Field({', '.join(arguments)})"] if arguments else []
+
+        rules = self._length_rules(refinements.min_length, refinements.max_length)
+
+        if bounds:
+            bound_arguments = ", ".join(f"{key}={string_literal(value)}" for key, value in bounds)
+            rules.append(f"{self.seampact}.bounds({bound_arguments})")
+
+        if refinements.multiple_of is not None:
+            rules.append(f"{self.seampact}.multiple_of({string_literal(refinements.multiple_of)})")
+
+        if pattern is not None:
+            rules.append(f"{self.seampact}.pattern({pattern})")
+
+        return rules
+
+    def _length_rules(self, minimum: int | None, maximum: int | None) -> list[str]:
+        arguments = _length_arguments(minimum, maximum)
+
+        if not arguments:
+            return []
+
+        helper = f"{self.seampact}.length" if self.rules is RulesMode.SEAMPACT_CONSISTENT else f"{self.pydantic}.Field"
+
+        return [f"{helper}({', '.join(arguments)})"]
+
+
+def pydantic_schemas_module(ir: ContractIR, names: ApiNames, rules: RulesMode, refusals: Refusals) -> str:
+    """The `schemas` module of an api: its enums and its object models."""
+    return _Emission(ir, names, rules, refusals).text()
+
+
+def _joined(items: Sequence[str]) -> str:
+    if len(items) == 1:
+        return items[0]
+
+    return items[0] + ", ".join(items[1:]) + "]"
+
+
+def _wrapped_in(prefix: str, annotation: Sequence[str], suffix: str) -> list[str]:
+    """A member whose annotation sits in one subscript (`prefix` ends with `[`, `suffix` starts with `]`), exploded as
+    ruff writes it: the annotation on its own line, else its `Annotated` items one per line with a trailing comma."""
+    joined = _joined(annotation)
+    single = f"{prefix}{joined}{suffix}"
+
+    if fits(single):
+        return [single]
+
+    # ruff parenthesizes the default instead when the annotation then fits on the member's line.
+    annotated, equals, default = suffix.partition(" = ")
+
+    if equals and fits(f"{prefix}{joined}{annotated} = ("):
+        return [f"{prefix}{joined}{annotated} = (", f"{INDENT * 2}{default}", f"{INDENT})"]
+
+    if fits(f"{INDENT * 2}{joined}") or len(annotation) == 1:
+        return [prefix, f"{INDENT * 2}{joined}", f"{INDENT}{suffix}"]
+
+    items = [f"{INDENT * 3}{item}," for item in annotation[1:]]
+
+    return [prefix, f"{INDENT * 2}{annotation[0]}", *items, f"{INDENT * 2}]", f"{INDENT}{suffix}"]
+
+
+def _wrapped(prefix: str, annotation: Sequence[str], suffix: str) -> list[str]:
+    """The member line, or, past the line length, its `Annotated` items one per line with a trailing comma."""
+    single = f"{prefix}{_joined(annotation)}{suffix}"
+
+    if fits(single) or len(annotation) == 1:
+        return [single]
+
+    items = [f"{INDENT * 2}{item}," for item in annotation[1:]]
+
+    if not suffix.startswith(_OR_NONE):
+        return [f"{prefix}{annotation[0]}", *items, f"{INDENT}]{suffix}"]
+
+    # ruff parenthesizes an exploded annotation that a `| None` follows.
+    default = suffix.removeprefix(_OR_NONE)
+    nested = [f"{INDENT}{item}" for item in items]
+
+    return [
+        f"{prefix}(",
+        f"{INDENT * 2}{annotation[0]}",
+        *nested,
+        f"{INDENT * 2}]",
+        f"{INDENT * 2}| None",
+        f"{INDENT}){default}",
+    ]
+
+
+def _referenced_schemas(type_use: TypeUse) -> list[str]:
+    if isinstance(type_use, RefTypeUse):
+        return [type_use.schema]
+
+    return _referenced_schemas(type_use.items) if isinstance(type_use, ArrayTypeUse) else []
+
+
+def _is_sensitive(member: Property) -> bool:
+    """A sensitive property, or a property whose scalar use is sensitive (docs/ir section 5)."""
+    return member.sensitive or (isinstance(member.type, ScalarTypeUse) and member.type.sensitive is True)
+
+
+def _use_nullable(type_use: TypeUse) -> bool:
+    nullable_uses = ScalarTypeUse | EnumTypeUse | RefTypeUse | ArrayTypeUse
+
+    return isinstance(type_use, nullable_uses) and type_use.nullable is True
+
+
+def _length_arguments(minimum: int | None, maximum: int | None) -> list[str]:
+    return [f"{key}={value}" for key, value in (("min_length", minimum), ("max_length", maximum)) if value is not None]
+
+
+def number_literal(literal: str, scalar: ScalarType) -> str:
+    exact = Decimal(literal)
+
+    if scalar is ScalarType.INTEGER and exact == exact.to_integral_value():
+        return str(int(exact))
+
+    return repr(float(exact))

seampact/codegen/redacted_members.py

@@ -0,0 +1,47 @@
+"""The generated marker that prints `[redacted]` in place of a sensitive value, and the `__repr__` and `__rich_repr__`
+of a generated dataclass that print its sensitive members through it (ADR 0026 "Redaction")."""
+
+from collections.abc import Collection, Sequence
+from typing import Final
+
+from seampact.codegen.printer import INDENT, string_literal
+
+REDACTED_CLASS: Final = "_Redacted"
+_REDACTED: Final = "[redacted]"
+
+
+def redacted_marker_block() -> list[str]:
+    """The module-level marker class; a module declares it once, before its first use."""
+    return [
+        f"class {REDACTED_CLASS}:",
+        f'{INDENT}"""Stands for a sensitive value in a `repr`."""',
+        "",
+        f"{INDENT}def __repr__(self) -> str:",
+        f"{INDENT}{INDENT}return {string_literal(_REDACTED)}",
+    ]
+
+
+def redacted_dataclass_reprs(
+    class_name: str, members: Sequence[str], redacted: Collection[str], abc_alias: str
+) -> list[str]:
+    """The `__repr__` and `__rich_repr__` methods of a generated dataclass: its `members` in order, each one in
+    `redacted` printed `[redacted]`, the others by their own `repr`."""
+    rendered = ", ".join(
+        f"{member}={_REDACTED}" if member in redacted else f"{member}={{self.{member}!r}}" for member in members
+    )
+    shown = any(member not in redacted for member in members)
+    returned = f'f"{class_name}({rendered})"' if shown else string_literal(f"{class_name}({rendered})")
+    rich_members = [
+        f"{INDENT}{INDENT}yield {string_literal(member)}, "
+        + (f"{REDACTED_CLASS}()" if member in redacted else f"self.{member}")
+        for member in members
+    ]
+
+    return [
+        "",
+        f"{INDENT}def __repr__(self) -> str:",
+        f"{INDENT}{INDENT}return {returned}",
+        "",
+        f"{INDENT}def __rich_repr__(self) -> {abc_alias}.Iterator[tuple[str, object]]:",
+        *rich_members,
+    ]

seampact/codegen/refusals.py

@@ -0,0 +1,84 @@
+"""Collects why a Python generator writes no file, each reason with its code, message, fix and place, so `generate`
+lists every refusal at once; one form is refused once per place."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from seampact.ir.config.problem import ConfigProblem
+from seampact.ir.run.generator import GenerationRefusedError
+
+
+class Delivery(StrEnum):
+    """Who brings a form the target does not generate yet."""
+
+    CONSUMER = "it comes when a consumer needs it"
+    AFTER_V1 = "it comes after 1.0"
+    LATER_THAN_V1 = "the 1.0 Python targets do not serve it, so it comes after 1.0"
+
+
+@dataclass(frozen=True, slots=True)
+class IrPlace:
+    """A place in the IR: a JSON pointer, and the operation it sits in."""
+
+    pointer: str
+    operation: str | None = None
+
+    def below(self, *keys: str | int) -> "IrPlace":
+        return IrPlace(self.pointer + "".join(f"/{key}" for key in keys), self.operation)
+
+
+def place_in_entry(entry_id: str, at: IrPlace, api: str | None = None) -> str:
+    """Where a refusal or a warning is, as `seampact` prints it."""
+    api_part = "" if api is None else f"api '{api}' "
+    where = f"entry '{entry_id}' {api_part}{at.pointer or '/'}"
+
+    if at.operation is not None:
+        where += f" (operation '{at.operation}')"
+
+    return where
+
+
+class Refusals:
+    def __init__(self, entry_id: str, target: str, distribution: str) -> None:
+        """`target` is the target's short name in messages (`fastapi`), `distribution` its package
+        (`seampact-fastapi`)."""
+        self._entry_id = entry_id
+        self._target = target
+        self._distribution = distribution
+        self._problems: dict[tuple[str, str], ConfigProblem] = {}
+
+    def add(self, code: str, message: str, fix: str, at: IrPlace) -> None:
+        where = place_in_entry(self._entry_id, at)
+        self._problems.setdefault((code, where), ConfigProblem(code, message, fix, where))
+
+    def waiting(self, form: str, description: str, at: IrPlace, delivery: Delivery) -> None:
+        """A form a later release, or a consumer, brings: `<form>.unsupported`."""
+        self.add(
+            f"{form}.unsupported",
+            f"{description} is not generated by the {self._target} target yet: {delivery.value}.",
+            "Remove this form from the operations the entry keeps (its `operations` filter), or update "
+            f"{self._distribution} to a release that generates it.",
+            at,
+        )
+
+    def inconsistent(self, code: str, description: str, at: IrPlace) -> None:
+        """An IR that breaks a rule the compiler guarantees."""
+        self.add(code, f"{description}.", "Regenerate the IR with seampact: this document is not one it wrote.", at)
+
+    def unknown_value(self, value: str, at: IrPlace) -> None:
+        """A value this IR revision allows but this generator does not know (ADR 0005 section 3)."""
+        self.add(
+            "ir.value.unknown",
+            f"The value '{value}' is not one the {self._target} target knows.",
+            f"Update {self._distribution} to a release that reads this IR, or compile with the matching seampact "
+            "version.",
+            at,
+        )
+
+    def is_empty(self) -> bool:
+        return not self._problems
+
+    def raise_if_any(self) -> None:
+        """Raises `GenerationRefusedError` listing every refusal."""
+        if self._problems:
+            raise GenerationRefusedError(list(self._problems.values()))

seampact/codegen/request_deadline.py

@@ -0,0 +1,68 @@
+"""The `deadline` property of a generated `<Op>Request` on an operation that reads a deadline header (grammar section
+9): the instant the caller stops waiting, read from the header its input already holds, so every target fills it
+alike and the handler asks it for the time left."""
+
+from typing import Final
+
+from seampact.codegen.names import member_identifier
+from seampact.codegen.printer import INDENT, PythonModule
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.ir.model import Operation, Param, ScalarType, ScalarTypeUse
+
+_DATE_TIME_FORMAT: Final = "date-time"
+
+
+def deadline_property(module: PythonModule, operation: Operation, at: IrPlace, refusals: Refusals) -> list[str]:
+    """The property's lines, after a blank line; none when the operation reads no deadline header."""
+    header = operation.deadline_header
+
+    if header is None:
+        return []
+
+    param = next((param for param in operation.params.header if param.name == header), None)
+
+    if param is None:
+        refusals.inconsistent(
+            "deadline.header.missing",
+            f"The deadline header '{header}' of operation '{operation.id}' is not one of its header parameters",
+            at.below("deadlineHeader"),
+        )
+        return []
+
+    deadline = module.imported("seampact.codegen.runtime.deadline", "_deadline")
+    value = f"self.input.headers.{member_identifier(param.name)}"
+    read = _deadline_read(deadline, param, value)
+
+    if read is None:
+        refusals.waiting(
+            "deadline.header.type",
+            f"A deadline header '{header}' typed other than a plain string or a date-time",
+            at.below("deadlineHeader"),
+            Delivery.CONSUMER,
+        )
+        return []
+
+    return [
+        "",
+        f"{INDENT}@property",
+        f"{INDENT}def deadline(self) -> {deadline}.RequestDeadline | None:",
+        f'{INDENT * 2}"""When the caller stops waiting, from its \'{header}\' header; None when it sent none."""',
+        f"{INDENT * 2}return {read}",
+    ]
+
+
+def _deadline_read(deadline: str, param: Param, value: str) -> str | None:
+    """The expression reading the deadline from the header's value: its text parsed, or its date-time wrapped as
+    the input already decoded it; None for another type."""
+    type_use = param.type
+
+    if not isinstance(type_use, ScalarTypeUse) or type_use.type != ScalarType.STRING or type_use.scalar is not None:
+        return None
+
+    if type_use.format is None:
+        return f"{deadline}.sent_deadline({value})"
+
+    if type_use.format == _DATE_TIME_FORMAT:
+        return f"None if {value} is None else {deadline}.RequestDeadline({value})"
+
+    return None

seampact/codegen/response_header_forms.py

@@ -0,0 +1,73 @@
+"""The response headers of the kept operations no Python boundary can write, refused by name for every target alike:
+a derived header the runtime's entries refuse (a successor in another api, an `ETag` whose `If-Match` writes the api
+does not serve, an inconsistent IR), and a paging style's header written from an object or an array, which has no
+header text."""
+
+from typing import Final
+
+from seampact.codegen.refusals import Delivery, IrPlace, Refusals
+from seampact.codegen.runtime.ir_view import ir_maps
+from seampact.codegen.runtime.response_header_entries import HeaderProblem, ProblemKind, response_header_entry
+from seampact.ir.model import ContractIR, LiteralTemplate, SlotTemplate, Template, TextTemplate
+
+# The page slots whose whole value is an object or an array: only a member of them is header text.
+_STRUCTURED_PAGE_SLOTS: Final = frozenset({"items", "meta"})
+
+
+def refuse_response_header_forms(ir: ContractIR, refusals: Refusals) -> None:
+    """Refuses by name each response header of the kept operations the boundary cannot write."""
+    operations = ir_maps(ir.to_json(), "operations")
+    read_styles: set[str] = set()
+
+    for index, operation in enumerate(operations):
+        at = IrPlace(f"/operations/{index}", ir.operations[index].id)
+
+        for position, response in enumerate(ir_maps(operation, "responses")):
+            for header_position, header in enumerate(ir_maps(response, "headers")):
+                entry = response_header_entry(ir.api.id, "", operations, operation, header)
+
+                if isinstance(entry, HeaderProblem):
+                    _refuse(entry, at.below("responses", position, "headers", header_position), refusals)
+
+        paging = ir.operations[index].paging
+        style_id = None if paging is None else paging.style
+
+        if style_id is not None and style_id not in read_styles:
+            read_styles.add(style_id)
+            _refuse_structured_page_headers(ir, style_id, refusals)
+
+
+def _refuse(problem: HeaderProblem, at: IrPlace, refusals: Refusals) -> None:
+    if problem.kind is ProblemKind.WAITING:
+        refusals.waiting(problem.code, problem.description, at, Delivery.AFTER_V1)
+    else:
+        refusals.inconsistent(problem.code, problem.description, at)
+
+
+def _refuse_structured_page_headers(ir: ContractIR, style_id: str, refusals: Refusals) -> None:
+    style = ir.pagings.get(style_id)
+
+    if style is None:
+        return
+
+    for index, header in enumerate(style.response.headers):
+        if not _is_scalar_template(header.value):
+            refusals.waiting(
+                "paging.response.header",
+                f"The header '{header.name}' of the paging style '{style_id}', written from an object or an array,",
+                IrPlace(f"/pagings/{style_id}/response/headers/{index}/value"),
+                Delivery.AFTER_V1,
+            )
+
+
+def _is_scalar_template(template: Template) -> bool:
+    if isinstance(template, TextTemplate):
+        return True
+
+    if isinstance(template, LiteralTemplate):
+        return not isinstance(template.value, dict | list)
+
+    if isinstance(template, SlotTemplate):
+        return bool(template.path) or template.slot not in _STRUCTURED_PAGE_SLOTS
+
+    return False