weft-kernel 0.1.0__py3-none-any.whl

weft_kernel/errors.py

@@ -0,0 +1,73 @@
+"""`WeftError` — the root of Weft's error hierarchy.
+
+Specified in `docs/02-extension-model.md` section 1 ("What a plugin
+receives"): packs raise subclasses of `WeftError`, which carries a
+`transient` marker so a pack can say what is worth retrying — the kernel
+runs no retry engine of its own, so a caller deciding whether to retry needs
+the pack's opinion, not a guess read off the exception's class name. Every
+kernel-raised error is loud and specific: it says what was wanted, why it is
+unavailable, and what the valid options are, never a bare
+`unknown plugin 'x'` that names no alternative.
+
+**Attribution is data this type carries, not logic it performs.**
+`docs/06-phase-0-build.md` step 3 builds the registration seam that catches
+whatever escapes a plugin's `run()` and wraps it, naming the pack, contract,
+plugin and stage, with `__cause__` preserved so no traceback is hidden. This
+step only gives that seam somewhere to put the four names — a plain
+`WeftError` raised directly by a pack has no reason to know its own
+attribution, and none of the four fields defaulting to `None` is exactly
+that: a stage does not know which pack it runs under or which pipeline slot
+it fills, and the one place that does is the seam wrapping the call, not the
+stage itself.
+"""
+
+
+class WeftError(Exception):
+    """Root of Weft's error hierarchy. Every kernel- and pack-raised error is one of these.
+
+    Catching `WeftError` catches everything Weft itself raises, kernel or
+    pack, without also swallowing an unrelated `KeyError` or `TypeError` a
+    caller would want to see — the catch-specific-exceptions rule applies to
+    callers of this library exactly as it applies inside it.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        transient: bool = False,
+        pack: str | None = None,
+        contract: str | None = None,
+        plugin: str | None = None,
+        stage: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.transient = transient
+        self.pack = pack
+        self.contract = contract
+        self.plugin = plugin
+        self.stage = stage
+
+
+class UnresolvedNameError:
+    """Marks a `WeftError` subclass whose failure mode is a name that did not resolve
+    against a known, enumerable set of alternatives — fitness function 12's family
+    (`docs/01-high-level-plan.md` → *Fitness functions*, item 12; grilling session G11).
+
+    `valid_options` is the typed field the function requires: the alternatives a caller
+    could have supplied instead, carried as a structural fact a renderer can format
+    however it likes, rather than only interpolated into `str(self)` where a reviewer
+    has to notice its absence. `01` requirement 5's own words: *"an unknown name fails
+    loudly, naming the valid options."*
+
+    **Not itself a `WeftError`, and defines no `__init__`.** A family member already
+    inherits one from wherever it actually sits — `PipelineResolutionError`'s four
+    fields, `LLMError`'s `provider`/`model`, or plain `WeftError` — and cooperative
+    multiple-inheritance `__init__` chaining across those different shapes is exactly
+    the machinery this class exists to avoid needing. This is mixed in as a second base
+    purely so `issubclass(cls, UnresolvedNameError)` is a real, mechanical fact fitness
+    function 12 can check; each concrete subclass sets `self.valid_options` itself, in
+    its own `__init__`, the same way it already sets any of its other typed fields.
+    """
+
+    valid_options: tuple[str, ...]

weft_kernel/fallback.py

@@ -0,0 +1,159 @@
+"""`try_in_order` — the fallback combinator, over any contract at all.
+
+`04` → the `_try_extractors` row: a fallback-chain executor belongs
+in the kernel "as a combinator", because **it composes plugins rather than
+doing work**. Nothing here inspects a payload, imports a capability or knows
+what a document is; it matches on the `Outcome` type a contract already
+defines and calls the next candidate or stops. That is what lets one
+implementation serve extraction today and a store, an embedder or a retriever
+tomorrow without a line changing.
+
+A separate module rather than a method on `Runner`, for two reasons that are
+not style: its cost is visible on its own line in fitness function 3's
+per-file numbers, and it is testable with no `Runner`, no `Registry` and no
+resolved pipeline — which is what makes the three-outcome table below a
+checked fact rather than a claim about the runner.
+
+**A `fail_silently` channel has no equivalent here, and this module is where
+that is enforced.** Such a channel returns an empty result indistinguishable
+downstream from a successfully-parsed empty document (`payload/outcome.py`) —
+the shape a two-state success/failure model is forced into once the real
+problem has three states. `Outcome` has the third, and `02` §1 already assigns
+the meanings:
+
+- **`Produced` — stop, return it.** Success is contract-defined, never guessed at
+  by looking inside the value the way `fail_silently` had to.
+- **`NothingToProduce` — stop, return it unchanged.** `02` §1, on a backend that
+  legitimately extracted nothing: it can now say so, "**and it stops the chain**".
+  *"I looked, and there is nothing here"* is a claim a second backend cannot
+  improve on.
+- **`Failed` — record it, try the next.** *"I could not see it"* — another backend
+  might.
+- **raises `WeftError` — record it, try the next.** See below.
+- **raises `BlockingCallError` — stop, and let it out.** See below.
+
+**Catching `WeftError` is the one deliberate breadth in this module.** Every
+candidate reaches here already wrapped by `weft_kernel.seam.wrap`, which turns
+anything a plugin lets escape into a `WeftError` with `__cause__` preserved and
+the pack, contract, plugin and stage attributed. So the broad tolerance a
+chain over third-party format libraries genuinely needs is declared once, at
+the combinator, against the one class the seam guarantees — rather than as a
+blind `except Exception` inside every backend, buried where no reviewer of
+the combinator would ever see it. `CancelledError`, `KeyboardInterrupt` and
+`SystemExit` are `BaseException`, so they are never caught here: cancellation
+propagates by construction, not by an added clause.
+
+**`BlockingCallError` is the one exception to that breadth, and it is the
+kernel's own, not a backend's.** The seam arms `weft_kernel.blocking.guard`
+around every candidate, so fitness function 7(b) raises it from *inside* the
+offending call — and it subclasses `WeftError`, so the clause above would file
+it as *"this backend could not do its job"* and let the next candidate answer.
+That is a `fallback:` line silently opting a stage out of the colour rule: the
+run exits with a success, the refusal list is discarded, and with the default
+no-op tracer the violation is named nowhere. The distinction the chain is
+allowed to walk past is a backend's report about a **document**; a report that
+the plugin itself broke the runtime contract is not a refusal to be tried
+around, so it propagates untouched. Any future kernel-raised diagnostic of a
+contract violation belongs beside it here.
+
+**The author rule that makes the `NothingToProduce` row honest**, stated on
+`Attempt` too because a backend author is who has to obey it:
+
+> Return `NothingToProduce` only when you can distinguish "there is nothing
+> here" from "I could not see it". If your backend cannot tell those apart for
+> this input, return `Failed`.
+
+`weft-pdf` ships both cases as unit tests — a page with a text layer drawing no
+glyphs against a page with no text and an embedded image — so the distinction
+the chain rests on is checked rather than promised.
+"""
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+
+from weft_kernel.blocking import BlockingCallError
+from weft_kernel.context import Context
+from weft_kernel.errors import WeftError
+from weft_kernel.payload import Failed, Outcome
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Attempt[In, Out]:
+    """One candidate in a chain: a name, and an already-seam-wrapped call.
+
+    `run` is expected to carry its own span, attribution, blocking guard and
+    transient stripping — the caller builds it through `weft_kernel.seam.wrap`
+    — which is why **this module writes no span of its own**. A chain of three
+    backends produces three spans, each attributed to the backend that
+    actually ran, and a fourth wrapping span naming only the chain would say
+    less than the three already do.
+
+    `name` is the plugin name, not the stage id: the stage is one position and
+    every candidate fills it, so it is the *name* that answers the question a
+    reader of the trace or of an exhausted chain's reason is asking — which
+    backend answered.
+    """
+
+    name: str
+    run: Callable[[In, Context], Awaitable[Outcome[Out]]]
+
+
+async def try_in_order[In, Out](
+    payload: In,
+    ctx: Context,
+    *,
+    stage: str,
+    attempts: Sequence[Attempt[In, Out]],
+) -> Outcome[Out]:
+    """Try each of `attempts` in order until one answers something other than a refusal.
+
+    `attempts` is `[primary, *fallbacks]` — the stage's own `use:` plugin is
+    simply the first candidate, so there is no special-cased primary path that
+    could diverge from the fallback path as either changes. Ordering is the
+    caller's data (`StageDeclaration.fallback`, written in a document), never a
+    constructor sequence compiled in here.
+
+    Returns the first `Produced` or `NothingToProduce`. When every candidate
+    refused, returns a single `Failed` naming **every** one of them and what
+    each said, in order — refusals accumulate and are reported together, because
+    a chain that reports only its last candidate's reason hides the fact that
+    the first one was the interesting failure.
+
+    Raises `BlockingCallError` rather than recording it — see the module
+    docstring: a chain is tolerant of what a backend says about a *document*,
+    never of a candidate breaking the runtime contract.
+    """
+    if not attempts:
+        raise ValueError(
+            f"stage '{stage}' was given an empty chain, so there is nothing to try. A chain "
+            f"is [primary, *fallbacks] and its first entry is the stage's own plugin; an "
+            f"empty one is a caller's bug, and answering Failed would file it as a backend's."
+        )
+
+    refusals: list[str] = []
+    for attempt in attempts:
+        try:
+            outcome = await attempt.run(payload, ctx)
+        except BlockingCallError:
+            # Before the broad clause, and never recorded: the seam's guard reports that
+            # this candidate broke the runtime contract, not that it met a document it
+            # could not read. See the module docstring's fifth row.
+            raise
+        except WeftError as exc:
+            refusals.append(f"'{attempt.name}' raised: {exc}")
+            continue
+        if isinstance(outcome, Failed):
+            refusals.append(f"'{attempt.name}' failed: {outcome.reason}")
+            continue
+        # `Produced` and `NothingToProduce` both stop the chain, and they are returned by
+        # the same line on purpose: `Failed` is the only refusal, and a reader looking for
+        # what continues a chain finds exactly one answer rather than two rules to compare.
+        return outcome
+
+    return Failed(
+        reason=(
+            f"every candidate for stage '{stage}' refused, in order: {'; '.join(refusals)}. "
+            f"No backend produced anything, and none of them reported the document as "
+            f"legitimately empty."
+        )
+    )

weft_kernel/payload/__init__.py

@@ -0,0 +1,43 @@
+"""The payload types — the domain model every stage signature names.
+
+Settled in G5. `NodeId`, `SourceId`, `Lineage`, `MediaType`, `Node`, `ExtModel`,
+`ExtMap`, `Vector` and `Outcome`. See `docs/02-extension-model.md` section 1.
+
+`Property` is G2's addition (task 1.2, `02` §3 → *Ordering constraints*): the
+marker `intact`/`destroys` name, on the same namespaced-tag footing
+`ExtModel` gives `requires`/`provides`, but never itself node data.
+
+`Applies` is G2's other addition (task 1.6, `02` §3 → *Applicability*): what
+a stage's `applies_to` tuple carries — a fact, declared as data, that the
+runner evaluates at the seam. See `weft_kernel.payload.applicability`.
+"""
+
+from weft_kernel.payload.applicability import Applies
+from weft_kernel.payload.ext import SCHEMA_VERSION_KEY, ExtMap, ExtModel, SchemaVersionRefusedError
+from weft_kernel.payload.ids import NodeId, SourceId
+from weft_kernel.payload.lineage import Lineage
+from weft_kernel.payload.media_type import MediaType
+from weft_kernel.payload.node import Node, SyntheticOrigin
+from weft_kernel.payload.outcome import Failed, NothingToProduce, Outcome, Produced
+from weft_kernel.payload.property import Property
+from weft_kernel.payload.vector import Vector
+
+__all__ = [
+    "SCHEMA_VERSION_KEY",
+    "Applies",
+    "ExtMap",
+    "ExtModel",
+    "Failed",
+    "Lineage",
+    "MediaType",
+    "Node",
+    "NodeId",
+    "NothingToProduce",
+    "Outcome",
+    "Produced",
+    "Property",
+    "SchemaVersionRefusedError",
+    "SourceId",
+    "SyntheticOrigin",
+    "Vector",
+]

weft_kernel/payload/applicability.py

@@ -0,0 +1,298 @@
+"""`Applies` — what a stage operates on, declared as data. Task 1.6, extended by 9.2.
+
+Settled in G2, `docs/02-extension-model.md` §3 → *Applicability*: "A stage
+declares what it operates on; the runner routes everything else past it,
+untouched." That makes applicability a mechanism the kernel enforces itself
+rather than a rule every stage's author has to remember and apply by hand.
+`docs/11-multimodal.md` §2's own worked example is
+the ingest-path illustration: "An atomic node passes the chunker unsplit,
+and the chunker does not have to know that."
+
+**Why a predicate cannot be a callable.** A callable can be *run*; it cannot
+be *printed*, checked at registration, or diffed between two resolutions of
+the same pipeline — exactly the complaint `weft_kernel.pipeline`'s own
+module docstring raises against a second construction path, one level down:
+a predicate a plugin author hands the kernel as a function is a second,
+unauditable grammar sitting next to the one `02` §3 already made data. So
+`Applies` is a frozen `pydantic.BaseModel` the kernel publishes, exactly the
+footing `weft_kernel.payload.property.Property` gives `intact`/`destroys` —
+data a plugin's `applies_to` tuple carries, evaluated by whoever runs the
+pipeline, never executed by the plugin itself.
+
+**What a fact is.** `Applies` wraps an `ExtModel` *subclass* — a namespaced
+fact a node may or may not carry, on the same footing `requires`/`provides`
+already give ext models. `Applies(Language)` matches any node carrying that
+fact at all; `Applies(Language, code="pl")` narrows to nodes whose `Language`
+additionally has `code == "pl"`. There is no other spelling: matching is
+always "this fact is present" or "this fact is present *and* these fields
+equal these values" — never "this fact is absent", because the safe-side
+reading below already gives absence a meaning, and giving it two would make
+one of them redundant with the other.
+
+**Keyword names are checked against the fact's own fields, immediately.**
+`Applies(Language, code="pl")` validates `code` against `Language.model_fields`
+the moment it is constructed — which, for the way every real plugin uses
+this (a class-level `applies_to = (Applies(Language, code="pl"),)` tuple,
+evaluated when the plugin's module is imported for registration), *is*
+"at registration": a typo'd field name fails on the pack's own import, not
+silently at the first pipeline that happens to route a node past a stage
+that should have claimed it. This is the identical failure class `02` §3
+rules out everywhere else — a typo that becomes a stage which silently never
+applies is indistinguishable, from the outside, from a stage that correctly
+declined every node it saw, and there is no doctor command that can tell
+those apart after the fact. Refusing it before the mistake can be observed
+is the only fix; a `TypeError`, not a `WeftError` — this is a plugin
+author's own class body failing to construct, the same footing
+`ExtModel.__pydantic_init_subclass__` and `Property.__init_subclass__`
+already refuse a missing `__namespace__` on, neither of which is a
+`PipelineResolutionError` either: nothing about a pipeline document is
+involved yet.
+
+**Absence fails to the safe side.** `02` §3 → *Language, and what a var is
+for*: "unknown language flows past" a language-specific stage — a fact this
+module's own `matches` makes literal. A stage that declares `applies_to`
+narrows itself to nodes it can positively confirm it should touch; every
+node it cannot confirm — the fact missing entirely, or present with a
+different value — passes it by. There is no third state and no negation:
+a chunker that wants to leave a table node alone does not declare
+"not `Atomic`" (which this module does not let it spell), it declares what
+it *does* want — the prose fact its own splitting logic actually depends on
+— and a table simply never carries that. This is the whole mechanism behind
+"the chunker does not have to know that" tables exist: the declaration
+names the chunker's own requirement, in the chunker's own vocabulary, and
+routing a stranger's `Atomic`-marked node past it is a byproduct of that
+requirement never being met, not a rule about tables the chunker's author
+had to think of and add.
+
+**A media-type constraint, task 9.2's addition.** `media_type` is already a core `Node`
+field — G5's admission rule, `node.py`'s own module docstring — rather than a namespaced
+fact, so it cannot be spelled as `Applies(SomeFact, ...)`; there is no `ExtModel` to narrow.
+`Applies(media_type=MediaType.TEXT)` claims a node of that type; `Applies(media_type=
+(MediaType.TEXT, MediaType.IMAGE))` claims any node whose type is one of those listed —
+the "any of these" reading lives *inside* one `Applies`, never across two, because a node
+has exactly one media type and two media-type `Applies` in one (conjunctive) tuple would
+jointly match nothing. `Applies(SomeFact, media_type=...)` is refused with a `ValueError` naming
+`media_type`: one `Applies` states one kind of constraint, and a fact constraint (narrows
+an `ExtModel` a node may carry) and a media-type constraint (narrows a field every node
+already has) are two different conjunction rules that a single object cannot mean at once.
+`Applies()` claiming neither is refused for the same reason it matters here at all — a
+constraint that matches nothing is a stage that silently never runs.
+
+**Vars never participate.** Nothing here reads `weft_kernel.pipeline`'s
+`vars:` block, and nothing could: `applies_to` is a class-level declaration
+a plugin's own module carries, never a field a pipeline document writes, so
+there is no `${var:NAME}` token for `weft_kernel.resolution`'s substitution
+to ever reach. `02` §3: "A var can say translate into English; it can never
+say pretend this document is English" — enforced here not by a check but by
+there being no document-authored surface for a var to land on in the first
+place.
+
+**A stage that declares no `applies_to` applies to everything, silently.**
+Read defensively — `getattr(instance, "applies_to", ())` — the identical
+convention `weft_kernel.runner` already uses for `requires`/`provides`/
+`intact`/`destroys`. An empty tuple is not a special case the seam checks
+for; it is simply zero constraints to fail, so every node satisfies it
+vacuously. This is what keeps every stage written before this task — none
+of which declares `applies_to` at all — running exactly as it did.
+"""
+
+import sys
+from typing import Annotated
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, PlainSerializer
+
+from weft_kernel.payload.ext import ExtModel
+from weft_kernel.payload.media_type import MediaType
+from weft_kernel.payload.node import Node
+
+
+def _fact_to_ref(fact: type[ExtModel]) -> str:
+    """`module:QualName` — enough to find the class again, and nothing more."""
+    return f"{fact.__module__}:{fact.__qualname__}"
+
+
+def _fact_from_ref(value: object) -> object:
+    """A persisted `module:QualName` back into the class, **without importing anything**.
+
+    The pack that declares a fact was imported at discovery if it is installed at all, so a
+    reference this cannot resolve means the pack is *gone* — and that is a refusal, not an import.
+    Resolving by importing whatever a persisted file names would turn a JSON artefact into an
+    instruction to execute code, which is a much larger promise than reading a run record needs.
+    """
+    if not isinstance(value, str):
+        return value
+    module_name, _, qualname = value.partition(":")
+    if not qualname:
+        raise ValueError(
+            f"{value!r} is not a fact reference. Expected 'module:QualName' — a fact written by a "
+            f"version of Weft before this form was introduced cannot be read, and the record "
+            f"carrying it should be deleted."
+        )
+    module = sys.modules.get(module_name)
+    if module is None:
+        raise ValueError(
+            f"no installed pack has imported '{module_name}', so the fact '{qualname}' this record "
+            f"was written against cannot be resolved. Install the distribution that provides it, "
+            f"or delete the record. Nothing is imported to answer this — a persisted name is data."
+        )
+    resolved: object = module
+    for part in qualname.split("."):
+        resolved = getattr(resolved, part, None)
+        if resolved is None:
+            raise ValueError(
+                f"'{module_name}' no longer declares '{qualname}'. The pack is installed and this "
+                f"fact has been renamed or removed since the record was written."
+            )
+    return resolved
+
+
+type _FactRef = Annotated[
+    type[ExtModel],
+    PlainSerializer(_fact_to_ref, return_type=str, when_used="json"),
+    BeforeValidator(_fact_from_ref),
+]
+"""`Applies.fact` in a document: the class in memory, `module:QualName` once dumped to JSON.
+
+pydantic has no serializer at all for an arbitrary `type`, so `model_dump(mode='json')` on a
+`ResolvedStage.applies_to` would otherwise raise outright rather than merely print something ugly.
+
+**It used to dump the bare `__name__` and had no validator, which made it write-only** — found at
+Phase 8's close review by running the binary. The serialising half worked from the day it was
+written, so nothing ever failed while records were being created; the failure arrived later and
+somewhere else, in three commands that merely *read* the directory those records live in. A bare
+name is also not enough to find a class again, which is why the form changed rather than only
+gaining a validator: two packs may each declare a `Language`, and the record has to say whose.
+"""
+
+
+class _Unset:
+    """The absence of an authored `fact`, distinguishable from every value one could hold."""
+
+    __slots__ = ()
+
+
+_UNSET = _Unset()
+
+
+class Applies(BaseModel):
+    """One constraint a stage's `applies_to` tuple carries: a fact, optionally narrowed.
+
+    See the module docstring for the reasoning; this class carries only the
+    shape and the one check that has to happen at construction, before a
+    typo can ship as a stage that silently never runs.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    fact: _FactRef | None = None
+    constraints: tuple[tuple[str, object], ...] = ()
+    media_type: tuple[MediaType, ...] = ()
+    """The media types this constraint claims, its own typed field rather than an entry in
+    `constraints` — which is `tuple[tuple[str, object], ...]` because a *fact's* narrowed values
+    are arbitrary, and `object` is exactly the annotation that makes pydantic hand a persisted
+    `"text"` back as the string `"text"`. A constraint that dumps correctly and reads back as
+    something `matches` compares false against is write-only, which is the defect `_FactRef`'s
+    docstring above records this module already paying for once: it "worked from the day it was
+    written, so nothing ever failed while records were being created", and surfaced later in three
+    commands that merely read. Typed here, pydantic validates the round trip rather than this
+    module hoping for it.
+    """
+
+    def __init__(
+        self,
+        fact: type[ExtModel] | _Unset = _UNSET,
+        /,
+        *,
+        media_type: MediaType | tuple[MediaType, ...] | _Unset = _UNSET,
+        **field_values: object,
+    ) -> None:
+        """Authored as `Applies(Language, code="pl")` **or** `Applies(media_type=...)`,
+        and **rebuilt from JSON as well**.
+
+        `fact` is positional-only so that a fact model declaring its own `fact` field is still
+        narrowable, and that is exactly what broke reading one back: pydantic validates a persisted
+        `{"fact": "Language", "constraints": [["code", "pl"]]}` by calling `__init__(**data)`, where
+        a positional-only parameter cannot be reached — so `fact` and `constraints` both landed in
+        `field_values`, `fact` was never supplied, and `model_validate` raised
+        *"missing 1 required positional argument: 'fact'"*.
+
+        **The writing half always worked, which is why nothing failed for a phase.** Found at Phase
+        8's close review by running the binary, not by the suite: `index-polish` declares
+        `applies_to = (Applies(Language, code="pl"),)`, so one `weft eval run` of it wrote a run
+        record that nothing could read afterwards — and `weft_cli.commands._participating_stores`
+        loads every record for `weft index`, `weft reconcile` **and** `weft delete`, so a single
+        opaque JSON file stopped all three in that project with no hint which file. `L6.14` says a
+        read method with no writer answers emptily; this is the reverse, and the reverse is worse,
+        because the artefact persists and the failure surfaces somewhere else entirely.
+
+        The unset sentinel is what lets one `__init__` serve every caller: `fact` and `media_type`
+        both absent means pydantic is rebuilding and `field_values` already holds the model's own
+        fields (`fact`, `constraints`); `fact` given with `media_type` given too is the one
+        combination task 9.2 refuses outright, one `Applies` stating two conjunction rules at once.
+        """
+        if not isinstance(fact, _Unset) and not isinstance(media_type, _Unset):
+            raise ValueError(
+                f"Applies({fact.__name__}, media_type=...) is not allowed: a fact constraint "
+                f"narrows an ExtModel a node may carry, and media_type narrows a field every "
+                f"node already has. One Applies states one kind of constraint — declare two "
+                f"separate stages, or drop whichever constraint this stage does not need."
+            )
+        if isinstance(fact, _Unset):
+            if "fact" in field_values:
+                if not isinstance(media_type, _Unset):
+                    field_values["media_type"] = media_type
+                super().__init__(**field_values)
+                return
+            if isinstance(media_type, _Unset):
+                raise TypeError(
+                    "Applies() states no constraint at all. Pass a fact to narrow "
+                    "(Applies(Language, code='pl')) or a media type to claim "
+                    "(Applies(media_type=MediaType.TEXT)); an Applies claiming nothing would "
+                    "match no node and say nothing about why."
+                )
+            if field_values:
+                unexpected = ", ".join(sorted(field_values))
+                raise TypeError(
+                    f"Applies(media_type=...) accepts no keyword but media_type; got "
+                    f"{unexpected}. A media-type constraint narrows a field every node has, "
+                    f"with nothing left to name."
+                )
+            claimed = (media_type,) if isinstance(media_type, MediaType) else tuple(media_type)
+            super().__init__(fact=None, media_type=claimed)
+            return
+        unknown = sorted(set(field_values) - set(fact.model_fields))
+        if unknown:
+            valid = ", ".join(sorted(fact.model_fields)) or "(no fields)"
+            raise TypeError(
+                f"Applies({fact.__name__}, {', '.join(f'{key}=...' for key in unknown)}) named "
+                f"field(s) {fact.__name__} does not have. {fact.__name__} declares: {valid}."
+            )
+        super().__init__(fact=fact, constraints=tuple(sorted(field_values.items())))
+
+    def matches(self, node: Node) -> bool:
+        """Whether `node` satisfies this constraint — a fact, or a media type, never both.
+
+        `fact is None` means this `Applies` was built from `media_type=...`, and `media_type`
+        is checked directly against `node.media_type` — a core field every node has, so there
+        is no absence case to fail to the safe side of, unlike a fact.
+
+        Otherwise, `node.ext_as(self.fact)` returning `None` is an ordinary absence — "the
+        stage does not apply", the safe-side reading the module docstring describes — never
+        treated as an error here, unlike a namespace collision, which `ext_as` itself already
+        raises on and this method makes no attempt to catch.
+        """
+        if self.fact is None:
+            return node.media_type in self.media_type
+        value = node.ext_as(self.fact)
+        if value is None:
+            return False
+        return all(getattr(value, name) == expected for name, expected in self.constraints)
+
+    def __repr__(self) -> str:
+        if self.fact is None:
+            types = ", ".join(claimed.value for claimed in self.media_type)
+            return f"Applies(media_type=({types}))"
+        if not self.constraints:
+            return f"Applies({self.fact.__name__})"
+        fields = ", ".join(f"{name}={value!r}" for name, value in self.constraints)
+        return f"Applies({self.fact.__name__}, {fields})"