weft-kernel 0.1.0__py3-none-any.whl

weft_kernel/payload/ext.py

@@ -0,0 +1,172 @@
+"""Namespaced, typed extension data on a `Node`.
+
+Settled in G5. A pack declares a model that owns a namespace; the kernel
+validates it on write through ordinary Pydantic construction, and
+`Node.with_ext` / `Node.ext_as` are the typed read/write pair — namespace
+strings never appear in plugin code. See `docs/02-extension-model.md`
+section 1.
+
+`__transient__` marks a namespace the kernel strips before the node is
+persisted (`Node.without_transient`). This is deliberately a class-level,
+type-checked declaration rather than a maintained tuple of key-name strings a
+stage author has to remember to extend. A namespace's transience is a fact
+about its type, checked once, at the declaration, never re-decided at every
+call site.
+
+**Built in Phase 5 task 5.2c.** `__schema_version__` is a second mandatory
+declaration, checked in the same `__pydantic_init_subclass__` seam as
+`__namespace__` and for the identical reason — G9's ruling (`docs/README.md`
+decision log, `docs/02-extension-model.md` §1): a contract version cannot
+stand in for it because it is not available at the read site, so an
+`ExtModel` carries its own version, and a missing one fails loudly at class
+definition rather than silently at first read. `SCHEMA_VERSION_KEY` is
+written into every dumped namespace by `_dump` below — *in the data*, never
+as a `ClassVar` a serialiser would drop, which is the exact defect `Filter.
+version` demonstrates. `upgrade` is the classmethod a reader calls when a
+stored version disagrees with the current one; its default refuses, naming
+the namespace, the stored version and the current one, because silence here
+is a contaminated fallback in another costume — the exact shape CLAUDE.md's
+rule against silent fallbacks exists to forbid.
+"""
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Annotated, ClassVar, Final
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, PlainSerializer, SerializeAsAny
+
+from weft_kernel.errors import WeftError
+
+#: The key `_dump` writes a namespace's `__schema_version__` under, inside the plain dict
+#: `ExtModel.model_dump()` otherwise produces — chosen dunder-shaped so it reads as
+#: metadata about the namespace rather than one of the subclass's own fields, the same
+#: visual distinction `__namespace__` itself makes at the Python level.
+SCHEMA_VERSION_KEY: Final[str] = "__schema_version__"
+
+
+class SchemaVersionRefusedError(WeftError):
+    """A stored namespace's schema version disagrees with the class reading it, and
+    `upgrade` was not overridden to reconcile the difference.
+
+    `docs/02-extension-model.md` §1: "A reader upgrades or refuses... Silence is
+    refusal." `stored_version` is `None` when the data was written before this task —
+    every row this store held before 5.2c — rather than assumed to be the current
+    version, which would be exactly the silent fallback CLAUDE.md forbids.
+    """
+
+    def __init__(self, *, namespace: str, stored_version: str | None, current_version: str) -> None:
+        stored = "no version at all (written before schema versioning existed)"
+        if stored_version is not None:
+            stored = f"version {stored_version!r}"
+        message = (
+            f"'{namespace}' data was written at {stored}, but the installed class is at "
+            f"{current_version!r} and declares no upgrade path from it. Override "
+            f"{namespace}'s ExtModel.upgrade(data, from_version) to migrate this shape, "
+            f"or reindex the corpus so this namespace is rewritten at the current version."
+        )
+        super().__init__(message)
+        self.namespace = namespace
+        self.stored_version = stored_version
+        self.current_version = current_version
+
+
+class ExtModel(BaseModel):
+    """Base for a pack's namespaced extension data.
+
+    A subclass must declare a non-empty `__namespace__` and a non-empty
+    `__schema_version__` — both enforced at class definition, not at first
+    use, so a missing declaration fails at import rather than at the first
+    `with_ext` call or the first read off a store.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    __namespace__: ClassVar[str] = ""
+    __schema_version__: ClassVar[str] = ""
+    __transient__: ClassVar[bool] = False
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: object) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        if not cls.__namespace__:
+            raise TypeError(
+                f"{cls.__name__} must declare a non-empty __namespace__ — the "
+                f"distribution name that owns this extension data"
+            )
+        if not cls.__schema_version__:
+            raise TypeError(
+                f"{cls.__name__} must declare a non-empty __schema_version__ — the "
+                f"version of this namespace's own shape, carried in every dumped "
+                f"instance so a reader can tell an old row from a current one even "
+                f"when the pack that wrote it is not installed (docs/02-extension-model.md §1)"
+            )
+
+    @classmethod
+    def upgrade(cls, data: Mapping[str, object], from_version: str | None) -> Mapping[str, object]:
+        """Migrate `data`, stored at `from_version`, to this class's current schema.
+
+        Refuses by default — `SchemaVersionRefusedError`, naming the namespace, the
+        stored version and the current one. A pack that can actually reconcile an
+        older shape overrides this; the base class assumes nothing is compatible,
+        because guessing wrong here means silently misreading a user's own data.
+        """
+        raise SchemaVersionRefusedError(
+            namespace=cls.__namespace__,
+            stored_version=from_version,
+            current_version=cls.__schema_version__,
+        )
+
+
+def _freeze(value: Mapping[str, ExtModel]) -> Mapping[str, ExtModel]:
+    """Wrap a validated ext mapping in an immutable view.
+
+    `Node`'s `frozen=True` blocks attribute *assignment* only — it does not
+    stop `node.ext['x'] = y` from mutating the plain `dict` a bare
+    `Mapping[str, ExtModel]` field would validate to. `MappingProxyType`
+    closes that door: `node.ext[...] = ...` raises `TypeError`, so
+    `Node.with_ext` is the only way to change what a node's `ext` holds.
+    """
+    return MappingProxyType(dict(value))
+
+
+def _dump(value: Mapping[str, ExtModel]) -> dict[str, object]:
+    """Serialise each namespace's model by its own (sub)class, not `ExtModel`.
+
+    Two problems, both invisible without a test that actually serialises a
+    `Node`. First, `MappingProxyType` has no serializer pydantic-core knows,
+    so `model_dump_json()` raises on it outright — this function's plain
+    `dict` return sidesteps that. Second, declaring the value type as the
+    base `ExtModel` makes pydantic serialise every entry *as* `ExtModel`:
+    a subclass's own fields (e.g. `entities` on a pack's model) are silently
+    dropped, not warned about, because serialisation follows the declared
+    type, not the runtime one. Calling each value's own `model_dump` here is
+    what stops both today; the `SerializeAsAny` on `ExtMap` below is a second
+    line, covering the declared-type path if this serialiser is ever narrowed
+    or removed. Only the loss of `model_dump_json` support is loud, so the
+    test in `tests/unit/weft_kernel/payload/test_node.py` asserts on the
+    subclass's field values, not merely that dumping did not raise.
+
+    Note for step 8 (the store): this is the write side only. A dumped `ext`
+    is plain dicts, so `Node.model_validate(node.model_dump())` does *not*
+    round-trip — rehydrating a namespace string back to the owning model
+    class needs a registry that does not exist yet.
+
+    **Task 5.2c adds `SCHEMA_VERSION_KEY`** to each namespace's dumped dict,
+    read off the *class*, not the instance — there is nowhere else in this
+    function that the version could come from, since it is a `ClassVar`, not
+    a field `model_dump()` itself would ever emit. This is the one place a
+    dumped namespace's bytes are assembled, so it is the one place the
+    version can travel in them rather than being dropped the way `Filter.
+    version` was.
+    """
+    return {
+        namespace: {**model.model_dump(), SCHEMA_VERSION_KEY: type(model).__schema_version__}
+        for namespace, model in value.items()
+    }
+
+
+type ExtMap = Annotated[
+    Mapping[str, SerializeAsAny[ExtModel]],
+    AfterValidator(_freeze),
+    PlainSerializer(_dump, return_type=dict),
+]

weft_kernel/payload/ids.py

@@ -0,0 +1,22 @@
+"""The two identifier types the payload model needs.
+
+`NodeId` is a content-addressed digest — see `node.py` for how it is computed.
+`SourceId` identifies the document a node's lineage traces back to; it is
+assigned by whichever component owns the record of that source document.
+Both live in the kernel because `Lineage`, a kernel type, names them in its
+own fields, and a pack downstream of the kernel cannot be the type a kernel
+field is declared against.
+
+Each is a `typing.NewType` over `str` rather than a real subclass: a
+`NodeId`/`SourceId` compares, hashes and sorts exactly like the string it is,
+with no unwrapping at call sites, while a signature can still require the
+specific type rather than any string. Pydantic has built-in, dependency-free
+support for `NewType` fields — unlike a genuine `str` subclass, which needs a
+custom `__get_pydantic_core_schema__` that imports `pydantic_core` directly,
+an import the kernel does not declare and fitness function 1 refuses.
+"""
+
+from typing import NewType
+
+NodeId = NewType("NodeId", str)
+SourceId = NewType("SourceId", str)

weft_kernel/payload/lineage.py

@@ -0,0 +1,90 @@
+"""Where a `Node` came from.
+
+Settled in G5. `sources` is computed by the kernel as the union of the
+parents' sources — never authored directly, except at a true root, where
+there are no parents to derive it from (see `Node.synthetic`). That rule is
+what makes cascade delete reach every descendant: `docs/02-extension-model.md`
+section 1, "Deleting a source cascades."
+
+`Lineage` can be constructed directly by pack or pipeline code — `Lineage()`
+and `Lineage(sources=...)` at a root are both ordinary, validated calls. The
+one shape it refuses is `sources` supplied alongside non-empty `parents`: a
+`Lineage` holds parent ids, not parent nodes, so it cannot check that
+`sources` is *correctly* derived from them, only that it was not authored
+out of nothing. `Node.derive` and `Node.combine` compute `sources` as the
+union of the actual parent nodes' own sources, then reach `Lineage.derived`
+to build the result — that classmethod still goes through the ordinary
+validated constructor, so `parents` and `sources` remain type-checked, and
+carries the fact that the check already happened through pydantic's
+validation context rather than skipping validation (`model_construct`) to
+get past it.
+
+The trust signal has to survive one more step than the context argument
+alone reaches: `Node.derive` and `Node.combine` embed the `Lineage` they
+build into a `Node`, and pydantic re-runs a nested model's
+`model_validator`s against that same object — same identity, verified by
+`id()` — when the outer `Node` is constructed, but *without* replaying the
+context the inner value was originally validated with. So the validator
+below also stamps a private, non-field flag onto the object the one time
+context says it may, and reads that flag on every later re-run — the
+context argument is what makes the *first* validation honest (a caller
+cannot get the flag set without going through full field validation), the
+flag is what makes it durable.
+"""
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr, ValidationInfo, model_validator
+
+from weft_kernel.payload.ids import NodeId, SourceId
+
+
+class Lineage(BaseModel):
+    """A node's ancestry: the nodes it was built from, and the documents it traces to."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    parents: tuple[NodeId, ...] = ()
+    sources: frozenset[SourceId] = frozenset()
+
+    _derived: bool = PrivateAttr(default=False)
+
+    @model_validator(mode="after")
+    def _sources_are_derived_not_authored(self, info: ValidationInfo) -> "Lineage":
+        """Refuse `sources` authored alongside non-empty `parents`.
+
+        The only legal place to author `sources` directly is a root with no
+        parents (reached through `Node.synthetic`). Everywhere else,
+        `sources` must come from `Lineage.derived`, which the ordinary
+        constructor cannot be used for — this is what stops a node claiming
+        a source its parents do not, which would make cascade delete either
+        miss it or delete it under the wrong document.
+        """
+        context: dict[str, object] = info.context or {}
+        trusted = self._derived or bool(context.get("derived"))
+        if self.parents and self.sources and not trusted:
+            raise ValueError(
+                "Lineage.sources is derived from parents' sources, never authored "
+                "directly, except at a root with no parents (Node.synthetic) — got "
+                "both non-empty parents and non-empty sources; use Lineage.derived "
+                "if sources was genuinely computed from the parents' own sources"
+            )
+        if trusted and not self._derived:
+            object.__setattr__(self, "_derived", True)
+        return self
+
+    @classmethod
+    def derived(cls, *, parents: tuple[NodeId, ...], sources: frozenset[SourceId]) -> "Lineage":
+        """Build a lineage whose `sources` was already correctly computed from `parents`.
+
+        The only callers are `Node.derive` and `Node.combine`, which compute
+        `sources` as the union of the actual parent nodes' own sources
+        before calling this. Goes through the ordinary validated
+        constructor — `parents` and `sources` are still type-checked — and
+        passes the trust signal through pydantic's validation context so
+        `_sources_are_derived_not_authored` above admits this one call
+        without skipping validation to do it; that validator then stamps
+        the result so embedding it in a `Node` (which re-runs this
+        validator with no context) still passes.
+        """
+        return cls.model_validate(
+            {"parents": parents, "sources": sources}, context={"derived": True}
+        )

weft_kernel/payload/media_type.py

@@ -0,0 +1,18 @@
+"""The closed vocabulary of what content a `Node` carries."""
+
+from enum import StrEnum
+
+
+class MediaType(StrEnum):
+    """What kind of content a `Node` carries.
+
+    A core field under G5's admission rule: every store and every retrieval
+    strategy must understand it to function. That is why it is a closed enum
+    rather than an open, pack-declared vocabulary — unlike a plugin name,
+    there is no registry a third party extends here, and per the project's
+    string-constant rule this is `Enum`, never `Literal[...]`.
+    """
+
+    TEXT = "text"
+    IMAGE = "image"
+    TABLE = "table"

weft_kernel/payload/node.py

@@ -0,0 +1,260 @@
+"""The `Node` type, and the three ways to build one.
+
+Settled in G5, specified in `docs/02-extension-model.md` section 1 ("The
+payload model"). Six core fields, admitted because every store and every
+retrieval strategy must understand them to function: `id`, `lineage`,
+`content`, `media_type`, `embedding`, `ext`. Everything else a pack wants to
+attach is namespaced extension data — see `ext.py` — never a seventh core
+field.
+
+Three defect shapes become unrepresentable here rather than merely guarded, as
+`docs/06-phase-0-build.md` step 1 requires:
+
+* **RAPTOR's unreachable summaries.** `Node.combine` refuses an empty
+  `members` sequence, and a `model_validator` on `Node` itself refuses any
+  parentless node that does not carry `SyntheticOrigin` — so a summary with
+  no members and no stated reason for its absent lineage cannot be built by
+  any path, not only through `combine`. A summary node built with an empty
+  relationships mapping to signal that it has no single source document
+  carries no `ref_doc_id` either way, so no deletion path can ever reach it.
+  Under `combine`, parents are explicit and `Lineage.sources` is the union of
+  the members' sources — a summary with no members has no sources to derive.
+* **A node claiming a source its parents do not.** `Lineage` itself refuses
+  `sources` authored alongside non-empty `parents` (see `lineage.py`), so a
+  node cannot claim ancestry to a document unrelated to what it was actually
+  built from — the same defect class, one field over.
+* **The multi-MB base64 blob reaching JSONB.** Guarding this with a
+  maintained tuple of key names that one pipeline stage has to remember to
+  check is exactly the kind of rule an author forgets. Here, transience is
+  declared once on the `ExtModel`
+  subclass that owns the namespace (`ExtModel.__transient__`) and
+  `Node.without_transient` strips by that declaration — a type-level fact
+  the registration seam (step 3) will apply automatically, not a list an
+  author extends. `ext` is also validated into an immutable mapping (see
+  `ext.py`), so a transient blob cannot be reinserted by mutating `node.ext`
+  in place after stripping — only `with_ext` can put one back.
+"""
+
+import hashlib
+from collections.abc import Sequence
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from weft_kernel.payload.ext import ExtMap, ExtModel
+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.vector import Vector
+
+
+class SyntheticOrigin(ExtModel):
+    """Attached automatically by `Node.synthetic`, carrying why the node has no lineage.
+
+    This is what makes a synthetic node's absence of lineage "explicit,
+    greppable, doctor-reportable" rather than merely a node with empty
+    `lineage.parents` indistinguishable from a bug: `node.ext_as(SyntheticOrigin)`
+    finds it, and a future `weft plugins doctor` can enumerate every one.
+    """
+
+    __namespace__ = "weft-kernel"
+    __schema_version__ = "1.0.0"
+
+    reason: str
+
+
+class Node(BaseModel):
+    """A unit of content flowing through a pipeline.
+
+    Frozen: every change is a new `Node`, produced by `derive`, `with_ext`,
+    `with_embedding` or `without_transient`, never by mutating this one.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: NodeId
+    lineage: Lineage
+    content: str
+    media_type: MediaType
+    embedding: Vector | None = None
+    # `validate_default` sends even the omitted-`ext` case through the field's
+    # validator, so a freshly built `MappingProxyType` comes out of the
+    # `default_factory` too — `default=MappingProxyType({})` would hand every
+    # node the *same* proxy instance, which `copy.deepcopy` (pydantic's guard
+    # against shared mutable defaults) cannot copy, since `mappingproxy` has
+    # no `__deepcopy__` and is not picklable.
+    ext: ExtMap = Field(default_factory=dict, validate_default=True)
+
+    @model_validator(mode="after")
+    def _lineage_requires_parents_or_synthetic_origin(self) -> "Node":
+        """Refuse a parentless node unless it carries `SyntheticOrigin`.
+
+        This is what makes the unreachable-summary bug described in the module
+        docstring unrepresentable by construction rather than only by the three factories being
+        well-behaved: a plain `Node(...)` call with empty `lineage.parents`
+        and no stated reason is refused here, no matter how it was built.
+        """
+        if self.lineage.parents:
+            return self
+        origin = self.ext.get(SyntheticOrigin.__namespace__)
+        if not isinstance(origin, SyntheticOrigin):
+            raise ValueError(
+                "a node with no lineage parents must carry SyntheticOrigin in ext, "
+                "stating why — construct it through Node.synthetic, which stamps "
+                "this automatically; an unexplained parentless node is unreachable by "
+                "any cascade delete, so it outlives the document it describes"
+            )
+        return self
+
+    def derive(
+        self, *, content: str, media_type: MediaType | None = None, ordinal: int = 0
+    ) -> "Node":
+        """A child produced from this node. Lineage is carried; `ext` and `embedding` are not.
+
+        The child is different content, so the parent's extension data and
+        embedding do not silently carry over — later stages attach their own.
+        """
+        effective_media_type = self.media_type if media_type is None else media_type
+        lineage = Lineage.derived(parents=(self.id,), sources=self.lineage.sources)
+        node_id = _content_digest(
+            media_type=effective_media_type,
+            content=content,
+            parent_ids=lineage.parents,
+            ordinal=ordinal,
+        )
+        return type(self)(
+            id=node_id, lineage=lineage, content=content, media_type=effective_media_type
+        )
+
+    @classmethod
+    def combine(
+        cls, members: Sequence["Node"], *, content: str, media_type: MediaType, ordinal: int = 0
+    ) -> "Node":
+        """A summary built from `members`. Parents are explicit and never empty.
+
+        Raises if `members` is empty — see the module docstring for why that
+        refusal is the fix for the unreachable-summary bug described there.
+        """
+        if not members:
+            raise ValueError(
+                "Node.combine requires at least one member. An empty set would produce "
+                "a summary with no derivable sources, unreachable by any cascade delete: "
+                "delete every document it summarised and it stays retrievable forever, "
+                "describing content that is gone. Refused by construction."
+            )
+
+        parents = tuple(member.id for member in members)
+        sources = frozenset[SourceId]().union(*(member.lineage.sources for member in members))
+        lineage = Lineage.derived(parents=parents, sources=sources)
+        node_id = _content_digest(
+            media_type=media_type, content=content, parent_ids=parents, ordinal=ordinal
+        )
+        return cls(id=node_id, lineage=lineage, content=content, media_type=media_type)
+
+    @classmethod
+    def synthetic(
+        cls,
+        *,
+        content: str,
+        media_type: MediaType,
+        reason: str,
+        sources: frozenset[SourceId] = frozenset(),
+        ordinal: int = 0,
+    ) -> "Node":
+        """A node with no real lineage — its absence stated rather than implied.
+
+        `sources` is accepted directly here, and only here, because there are
+        no parents to derive it from. This is also the root of a document's
+        very first node: extraction has no upstream `Node`, only a source
+        document, so it states that document's id as `sources` explicitly.
+
+        Built in one constructor call, with `SyntheticOrigin` already in
+        `ext`: the model-level invariant above rejects a parentless node
+        that does not carry it, and `model_copy` (which `with_ext` uses)
+        skips validation, so a two-step "build, then attach" sequence would
+        raise on the intermediate object.
+        """
+        if not reason:
+            raise ValueError("Node.synthetic requires a non-empty reason, so it stays greppable")
+
+        lineage = Lineage(parents=(), sources=sources)
+        node_id = _content_digest(
+            media_type=media_type, content=content, parent_ids=(), ordinal=ordinal
+        )
+        return cls(
+            id=node_id,
+            lineage=lineage,
+            content=content,
+            media_type=media_type,
+            ext={SyntheticOrigin.__namespace__: SyntheticOrigin(reason=reason)},
+        )
+
+    def _replace(self, **updates: object) -> "Node":
+        """Rebuild this node through full validation.
+
+        `model_copy(update=...)` skips validation entirely, so it would let a
+        caller smuggle an invalid `content`, `media_type` or `ext` past every
+        guard this model declares — including the lineage invariant above.
+        Revalidating the whole node closes that: `with_ext`, `with_embedding`
+        and `without_transient` cannot become a second, unchecked way to
+        build one.
+        """
+        return type(self).model_validate({**self.__dict__, **updates})
+
+    def with_ext(self, model: ExtModel) -> "Node":
+        """Attach namespaced extension data, replacing any prior value in that namespace."""
+        namespace = type(model).__namespace__
+        return self._replace(ext={**self.ext, namespace: model})
+
+    def ext_as[T: ExtModel](self, kind: type[T]) -> T | None:
+        """This node's data for `kind`'s namespace, or `None` if absent.
+
+        `None` is legitimate — the producing stage may have run and produced
+        nothing for this node. A namespace occupied by a different type than
+        requested raises: that is not a legitimate absence, it is two packs
+        disagreeing about what one namespace means.
+        """
+        value = self.ext.get(kind.__namespace__)
+        if value is None:
+            return None
+        if not isinstance(value, kind):
+            raise TypeError(
+                f"namespace '{kind.__namespace__}' holds {type(value).__name__}, "
+                f"not {kind.__name__}"
+            )
+        return value
+
+    def without_transient(self) -> "Node":
+        """This node with every `__transient__` namespace stripped."""
+        kept = {ns: model for ns, model in self.ext.items() if not type(model).__transient__}
+        if len(kept) == len(self.ext):
+            return self
+        return self._replace(ext=kept)
+
+    def with_embedding(self, embedding: Vector) -> "Node":
+        """This node with its embedding set. Identity is unaffected — the digest excludes it."""
+        return self._replace(embedding=embedding)
+
+
+def _content_digest(
+    *, media_type: MediaType, content: str, parent_ids: Sequence[NodeId], ordinal: int
+) -> NodeId:
+    """The content-addressed identity: media type, content, sorted parents, an ordinal.
+
+    Excludes the embedding (derived from content, and it would bind ids to a
+    model) and any stage configuration, so two pipelines producing
+    byte-identical output produce one node. The ordinal disambiguates
+    byte-identical content under the same parent set: without it, two
+    structurally identical siblings — the same content, the same parents —
+    would collide on identity and silently merge into one node; a caller
+    passing distinct ordinals for siblings avoids that here.
+
+    Parts are length-prefixed before hashing so that no concatenation of
+    variable-length strings can collide across a different split of the same
+    bytes.
+    """
+    digest = hashlib.sha256()
+    for part in (media_type.value, content, *sorted(parent_ids), str(ordinal)):
+        encoded = part.encode("utf-8")
+        digest.update(len(encoded).to_bytes(8, byteorder="big"))
+        digest.update(encoded)
+    return NodeId(digest.hexdigest())

weft_kernel/payload/outcome.py

@@ -0,0 +1,40 @@
+"""The result every contract method returns.
+
+Settled in G5. Never a bare value: `Produced` / `NothingToProduce` / `Failed`.
+This is what lets the kernel own a fallback combinator over any contract
+without inspecting payload content — it matches on the outcome's type and
+never looks inside it — and it is the fix for the worst extraction trap a
+`fail_silently` path opens: an empty result indistinguishable downstream
+from a successfully-parsed empty document. A backend that
+legitimately produced nothing now has `NothingToProduce` to say so, distinct
+from `Failed`. See `docs/02-extension-model.md` section 1.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Produced[T](BaseModel):
+    """The stage ran and produced a value."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    value: T
+
+
+class NothingToProduce(BaseModel):
+    """The stage ran, found nothing to produce, and that is a legitimate result."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    reason: str
+
+
+class Failed(BaseModel):
+    """The stage did not complete."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    reason: str
+
+
+type Outcome[T] = Produced[T] | NothingToProduce | Failed

weft_kernel/payload/property.py

@@ -0,0 +1,60 @@
+"""`Property` — a namespaced marker for a fact about a stage's payload that ordering cares about.
+
+Settled in G2, `docs/02-extension-model.md` §3 → *Ordering constraints —
+`intact` and `destroys`*: G5's `requires`/`provides` solve ordering by **data
+dependency** — a stage that reads what an earlier one produced — and that
+cannot express a constraint that exists for the opposite reason: hyphenation
+repair must run before whitespace normalization not because anything reads
+its output, but because whitespace normalization is **destructive** to a fact
+no dependency graph can see. `intact`/`destroys` are the mirror G2 added, and
+this is what they carry: "The representation is the mirror of `requires` /
+`provides`... The properties are published by whichever pack publishes the
+contract — namespaced marker classes exactly as G5 gives ext models their
+namespaces."
+
+**Never instantiated, and never a `Node`'s data.** `weft_kernel.runner.Stage`'s
+`requires`/`provides` already demonstrate the shape ordering borrows: an
+`ExtModel` *subclass* is a tag a stage's tuple carries, never an instance the
+stage constructs. `intact`/`destroys` need that same tagging shape, but not
+an `ExtModel`'s own machinery — a property is not payload data a `Node`
+carries, is never written, validated or persisted, and gets no `ext`
+namespace of its own — so it gets a lightweight base rather than reusing
+`ExtModel` for a job it was never shaped for.
+
+**`__namespace__` is mandatory, and enforced the same way `ExtModel`
+enforces it** — at class definition, via `__init_subclass__`, never at first
+use — for the identical reason: "no plugin ever names another plugin." A
+hyphenation fixer's `intact = (WordBoundaries,)` and a whitespace
+normalizer's `destroys = (WordBoundaries,)` compare by **type identity**,
+never by a string either side had to agree on — see
+`weft_kernel.runner.Runner.resolve`, which is what actually walks a stage
+list accumulating what earlier stages destroyed. The namespace is what stops
+two unrelated packs from silently colliding on the same class name and
+having their unrelated properties compare as equal by accident; it plays no
+role in the comparison itself, exactly as `ExtModel.__namespace__` plays no
+role in `requires`/`provides` matching by model type.
+"""
+
+from typing import ClassVar
+
+
+class Property:
+    """Base for a namespaced marker declaring a fact about a stage's payload.
+
+    A subclass carries no fields and is never instantiated — see the module
+    docstring. `intact`/`destroys` on a plugin class name `Property`
+    subclasses exactly the way `requires`/`provides` name `ExtModel`
+    subclasses: the type itself is the whole payload, so two packs can
+    publish their own properties with no coordination and no shared registry
+    of names.
+    """
+
+    __namespace__: ClassVar[str] = ""
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        if not cls.__namespace__:
+            raise TypeError(
+                f"{cls.__name__} must declare a non-empty __namespace__ — the "
+                f"distribution name that owns this property"
+            )