weft-kernel 0.1.0__tar.gz → 0.2.0__tar.gz

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/.gitignore

@@ -83,3 +83,10 @@ build/
 /docs/_external-reading/
 
 /tmp/
+
+# The internal process record — how this project is worked, not what it ships. The build ledger,
+# the lessons queue and its archive, the grilling sessions, the product direction, the roadmap past
+# Phase 11, the control file that holds project state, and the owner's own list. Untracked
+# 2026-09-11 at the owner's decision. The numbered reference documents stay tracked: 650 citations
+# from `packages/` point at them and those pointers ship inside the wheel.
+/docs/internal/

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: weft-kernel
-Version: 0.1.0
+Version: 0.2.0
 Summary: The Weft kernel: registry, discovery, pipeline model, payload types.
 License-Expression: MIT
 License-File: LICENSE

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "weft-kernel"
-version = "0.1.0"
+version = "0.2.0"
 description = "The Weft kernel: registry, discovery, pipeline model, payload types."
 requires-python = ">=3.12"
 license = "MIT"

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/context.py

@@ -38,7 +38,7 @@ language axis it already has. A locale-keyed message store with one locale is
 a dict with a constant key, so the catalogue, `Context.messages`, `t()` and
 the three error classes they brought (`UnknownMessageError`,
 `DuplicateMessageError`, `MessageFormatError`) are gone, taking this kernel
-from 33 error classes to 30. `docs/05-grilling-sessions.md` → G11 holds the
+from 33 error classes to 30. `docs/internal/05-grilling-sessions.md` → G11 holds the
 session; `docs/02-extension-model.md` §1 owns what replaced it — an English
 literal at the raise site, whose explanation surface is
 `manual/troubleshooting.md`'s coverage ratchet, and whose *quality* is
@@ -70,7 +70,7 @@ import asyncio
 from dataclasses import dataclass, field
 from typing import cast
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
 
 from weft_kernel.errors import UnresolvedNameError, WeftError
 
@@ -108,11 +108,11 @@ class ServiceRole(BaseModel):
     """A pack's declaration, beside the contract it publishes, that `[services].<key>`
     selects an implementation of that contract for one run.
 
-    Ledger task **9.0**, closing the hole `docs/02-extension-model.md` §1 named in its own
-    Phase 0 narrowing: a service is populated into a `ServiceRegistry` by whatever assembles
-    a run, but nothing let a pack *name* which of its contracts is selectable that way, or
-    under what `[services]` key. `ServiceRole` is that declaration — "one constant beside the
-    Protocol" (`docs/build-ledger.md:5026 'exists becaus'`, `:5370`), never a member on the Protocol
+    Ledger task **9.0**, closing the hole `docs/02-extension-model.md` §1 named in its own Phase 0
+    narrowing: a service is populated into a `ServiceRegistry` by whatever assembles a run, but
+    nothing let a pack *name* which of its contracts is selectable that way, or under what
+    `[services]` key. `ServiceRole` is that declaration — "one constant beside the Protocol"
+    (`docs/internal/build-ledger.md:5054 'exists becaus'`, `:5370`), never a member on the Protocol
     itself.
 
     It is a plain constant rather than a `ClassVar` written into the contract's own body,
@@ -138,6 +138,17 @@ class ServiceRole(BaseModel):
     key: str = Field(min_length=1)
     contract: type[object]
 
+    @field_serializer("contract")
+    def _contract_as_name(self, contract: type[object]) -> str:
+        """The contract's qualified name — ledger task **24.5**.
+
+        A role names a live Protocol because `ctx.require(...)` resolves against the class
+        itself; what a reader of `weft --json plugins list` can act on is which contract, which
+        is what a qualified name says. Same rule as `PackReport.ext_models` and
+        `RendererOffer.result_type`: what leaves is an identity, never the object.
+        """
+        return f"{contract.__module__}.{contract.__qualname__}"
+
 
 class ServiceRegistry:
     """Per-run map of `contract -> the one resolved instance a stage gets back.`

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/discovery.py

@@ -85,7 +85,7 @@ about stores: it is inert data until something that *does* know what a store
 is reads `PackReport.ext_models` back off every report and registers each
 class with the namespace-to-class registry that actually rehydrates one —
 `weft_store.rehydrate.register_from_reports`, called once, generically, by
-whatever already calls `discover()` (`weft_cli.registry_bootstrap.
+whatever already calls `discover()` (`weft_engine.registry_bootstrap.
 build_dependencies`). No pack-specific knowledge sits in that call site: it
 walks whatever `PackReport.ext_models` any report carries, so a future pack
 shipping a new `ExtModel` needs no edit here and no edit in `weft-cli` at all.
@@ -100,7 +100,7 @@ value the kernel already owns (`weft_kernel.resolution` is this same distributio
 not a capability, so this teaches the kernel nothing new either: it stops at "this
 pack offered this contribution," and `PackReport.contributions` is read back off
 every report by whatever assembles a `resolve()` call's own `contributions=` tuple —
-`weft_cli.registry_bootstrap.build_dependencies`, the same caller `Contribution`'s
+`weft_engine.registry_bootstrap.build_dependencies`, the same caller `Contribution`'s
 own docstring names, now real. No pack-specific knowledge sits there either: it
 concatenates whatever `PackReport.contributions` every report carries, so a future
 pack contributing into a slot needs no edit here and no edit in `weft-cli` at all.
@@ -130,7 +130,7 @@ from enum import StrEnum
 from importlib import metadata
 from typing import Protocol, cast, get_type_hints
 
-from pydantic import BaseModel, ConfigDict, ValidationError
+from pydantic import BaseModel, ConfigDict, ValidationError, field_serializer
 
 from weft_kernel.context import ServiceRole
 from weft_kernel.errors import UnresolvedNameError, WeftError
@@ -223,6 +223,26 @@ class RendererOffer(BaseModel):
     result_type: type[object]
     render: Callable[[object], object]
 
+    @field_serializer("result_type")
+    def _result_type_as_name(self, result_type: type[object]) -> str:
+        """The type's qualified name — ledger task **24.5**, and the same rule as
+        `PackReport.ext_models`: what leaves is an identity, never the live object.
+
+        This field holds a real class because `weft_cli.render`'s dispatch keys on it, and a
+        string could not do that. `weft --json plugins list` asked it to serialise and pydantic
+        refused the whole report, so the command exited 1 printing nothing — which is how a
+        field nobody had ever written down announces itself.
+        """
+        return f"{result_type.__module__}.{result_type.__qualname__}"
+
+    @field_serializer("render")
+    def _render_as_name(self, render: Callable[[object], object]) -> str:
+        """Likewise, for the callable. A function has no wire form; what a reader of the JSON
+        can act on is which one it is, which is what a qualified name says."""
+        module = getattr(render, "__module__", "?")
+        name = getattr(render, "__qualname__", repr(render))
+        return f"{module}.{name}"
+
 
 class ServiceRoleOffer(BaseModel):
     """One `ServiceRole` a pack declared, attributed to the pack that declared it.
@@ -288,7 +308,7 @@ class PackReport(BaseModel):
 
     `contributions` — task 5.3a — is every `weft_kernel.resolution.Contribution` the pack
     buffered through `PackRegistrar.add_contribution`, empty for any pack that offers no
-    slot contribution (most packs). `weft_cli.registry_bootstrap.build_dependencies` is the
+    slot contribution (most packs). `weft_engine.registry_bootstrap.build_dependencies` is the
     one place every report's own tuple is concatenated into the `contributions=` argument
     every `weft_kernel.resolution.resolve` call site now passes — `02` §3 → *Slots*: "a pack
     may... contribute into a slot a pipeline opted into."
@@ -321,6 +341,25 @@ class PackReport(BaseModel):
     deprecations: tuple[Deprecation, ...] = ()
     unavailable: tuple[Unavailable, ...] = ()
     ext_models: tuple[type[ExtModel], ...] = ()
+
+    @field_serializer("ext_models")
+    def _ext_models_as_namespaces(self, models: tuple[type[ExtModel], ...]) -> tuple[str, ...]:
+        """The namespaces, not the classes — ledger task **24.5**.
+
+        This field holds live classes on purpose: `weft_store.rehydrate.register_from_reports`
+        reads them back to teach a store how to rehydrate a pack's own `ext` namespaces, and a
+        string could not do that. What a class cannot do is *serialise*, and until 24.5 nothing
+        ever asked it to — `weft --json plugins list` then did, and pydantic refused the whole
+        report with `PydanticSerializationError: Unable to serialize unknown type:
+        ModelMetaclass`, taking the command down with it. Found by running the binary; the 2,749
+        tests could not see it, because none of them dumps a `PackReport`.
+
+        `__namespace__` is the identity a reader of the JSON wants and the one `02` § *The
+        payload model* says is collision-free by construction. The in-memory value is untouched:
+        a serializer decides what leaves, never what the field holds.
+        """
+        return tuple(model.__namespace__ for model in models)
+
     contributions: tuple[Contribution, ...] = ()
     renderers: tuple[RendererOffer, ...] = ()
     service_roles: tuple[ServiceRoleOffer, ...] = ()
@@ -371,7 +410,7 @@ class InertPluginPinError(WeftError):
     parameter is what a diagnostic caller sets `False` to see every
     `PackReport` anyway; `weft_cli.cli.dispatch` does this for `plugins
     list`/`plugins doctor` and no other command, on the same reasoning
-    `weft_cli.registry_bootstrap`'s own module docstring already gives for
+    `weft_engine.registry_bootstrap`'s own module docstring already gives for
     `WEFT_DATABASE_URL`: "a bare crash on every registry-needing command —
     including `plugins doctor`, the one command meant to diagnose exactly
     this — would be worse than" a report.
@@ -969,7 +1008,7 @@ def _activate(
     identical terms, for the identical reason: a pack that raises must never look like it
     offered a slot contribution it never actually committed. This function does nothing else
     with it either — assembling every report's own tuple into one `contributions=` argument
-    for `weft_kernel.resolution.resolve` is `weft_cli.registry_bootstrap.build_dependencies`'s
+    for `weft_kernel.resolution.resolve` is `weft_engine.registry_bootstrap.build_dependencies`'s
     job, the one caller `weft_kernel.resolution.Contribution`'s own docstring names.
 
     **Task 6.20** — `registrar.renderers` reaches `PackReport.renderers` on the identical
@@ -1089,7 +1128,7 @@ def _read_service_roles(
     declaration been buffered through `register()`, `[services] store = "qdrant"` would then be
     refused as an *unknown key*, naming the wrong problem entirely, on exactly the machine where
     an operator is trying to configure their way out of it. The pre-9.0 behaviour — the key
-    parses, and the plugin name fails later through `weft_cli.registry_bootstrap.require_plugin`,
+    parses, and the plugin name fails later through `weft_engine.registry_bootstrap.require_plugin`,
     which names the pack and its reason — is the better error, and reading the declaration here
     is what preserves it.
 

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/payload/__init__.py

@@ -17,7 +17,7 @@ from weft_kernel.payload.ext import SCHEMA_VERSION_KEY, ExtMap, ExtModel, Schema
 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.node import Node, SyntheticOrigin, carry_forward
 from weft_kernel.payload.outcome import Failed, NothingToProduce, Outcome, Produced
 from weft_kernel.payload.property import Property
 from weft_kernel.payload.vector import Vector
@@ -40,4 +40,5 @@ __all__ = [
     "SourceId",
     "SyntheticOrigin",
     "Vector",
+    "carry_forward",
 ]

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/payload/ext.py

@@ -15,7 +15,7 @@ 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`
+`__namespace__` and for the identical reason — G9's ruling (`docs/internal/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

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/payload/node.py

@@ -235,6 +235,34 @@ class Node(BaseModel):
         return self._replace(embedding=embedding)
 
 
+def carry_forward(child: Node, *, parent: Node) -> Node:
+    """`child`, plus every namespace `parent.ext` carries except its root-origin marker.
+
+    `SyntheticOrigin` is excluded by name: it states that a node has no real lineage, and
+    `child` was just given one — by `Node.derive`, whichever stage called this — so copying
+    it forward would attach a claim about `child` that is false the moment it is read.
+    Every other namespace is copied verbatim, last-write-wins is never a concern here since
+    `child` carries no `ext` of its own yet (`derive` starts it empty); a caller that wants
+    its own fact to win over a carried-forward one — `weft_chunk.table_rows` does, for its
+    row's own `TableGrid` — attaches it with `with_ext` *after* calling this.
+
+    **G17, settled 2026-09-12.** Moved here from `weft_chunk.carry` — with a byte-identical
+    private copy in `weft_vision.describe_figure` whose own docstring cited
+    `weft_chunk.fixed_size._carry_forward`, a function that has not existed since task `9.14`
+    lifted it — because G17 adds a third consumer: every `weft_clean` cleaner rebuilds its
+    node with `Node.derive`, which drops `ext`, and `R9.1` is the property that a `TEXT`
+    node's extraction-time facts survive that. `weft_clean`, `weft_chunk` and `weft_vision`
+    import none of each other, so the only module all three already depend on is the kernel,
+    and the function belongs there on `01`'s own test: it names no capability. It is an
+    operation on `Node.ext` and `SyntheticOrigin`, both of them kernel types.
+    """
+    for namespace, model in parent.ext.items():
+        if namespace == SyntheticOrigin.__namespace__:
+            continue
+        child = child.with_ext(model)
+    return child
+
+
 def _content_digest(
     *, media_type: MediaType, content: str, parent_ids: Sequence[NodeId], ordinal: int
 ) -> NodeId:

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/pipeline.py

@@ -79,7 +79,7 @@ already preserves call order into the `**data` dict `BaseModel.__init__`
 builds, which is the same dict a document's loader hands to
 `model_validate`, so there is exactly one code path computing "the order",
 not one per direction. This is what task 1.4 settles from the note 1.1 left
-open in `docs/build-ledger.md`.
+open in `docs/internal/build-ledger.md`.
 
 **`fallback` is data here too.** `02` §1 gives the kernel a fallback combinator
 over any contract, and `11` §4 keeps `fallback:` a per-stage list "tried in
@@ -241,7 +241,7 @@ PIPELINE_OPERATOR_MARK: Final[str] = "pipeline_operator"
 ratchet, and `01` -> *Fitness functions* item 11(a) requires its "actual" side to be
 "derived from the code (the actual operator fields on the model), never a hand-written
 list" — a second tuple of the same four strings, sitting in the test file with no
-structural link back to this class, is exactly the drift `docs/README.md` opens by
+structural link back to this class, is exactly the drift `docs/internal/README.md` opens by
 describing. Each of the four operator fields below carries `Field(...,
 json_schema_extra={PIPELINE_OPERATOR_MARK: True})` for exactly that reason: it is the
 one place in the tree that *decides* a field is an operator block, so the ratchet reads

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/resolution.py

@@ -112,7 +112,7 @@ so a leaf's override reaches a var referenced in a `with:` block the root itself
 **Operators apply against the *running* stage list, never against the original root.**
 `02` §3: "Operators apply in written order, each validated against the running result."
 That is what makes `remove` followed by `insert` on one id a move rather than a
-collision — task 1.4 settles the question `docs/build-ledger.md` left open after 1.1:
+collision — task 1.4 settles the question `docs/internal/build-ledger.md` left open after 1.1:
 "the order in which those keys appear in the document is the order they apply."
 `weft_kernel.pipeline.Pipeline.operator_order` is read off the document (or the call)
 that built the pipeline, never assumed from field order, and `_apply_operators` below

{weft_kernel-0.1.0 → weft_kernel-0.2.0}/src/weft_kernel/seam.py

@@ -43,7 +43,7 @@ The four concerns:
    — is out of scope by construction, not by an exclusion list.
 5. **The NUL-byte sanitiser** — see `_sanitize_control_bytes` below, riding
    the same `Produced` → `Node` / `tuple` / `list` walk `_strip_transient`
-   already performs, immediately after it. `docs/build-ledger.md` → **2.34**
+   already performs, immediately after it. `docs/internal/build-ledger.md` → **2.34**
    settles where this lives, against two alternatives, with evidence:
 
    - **Not in an extractor pack.** Eight sites across `packages/` build a
@@ -51,7 +51,7 @@ The four concerns:
      text.py:80 'Node.syn'`, `weft_pdf/document.py:205 'rows: tu'`,
      `weft_chunk/fixed_size.py:117 'destroys'
      'destroys'`,
-     `weft_clean/dictionary_spacing.py:108-109 'intact: '`,
+     `weft_clean/dictionary_spacing.py:116-117 'intact: '`,
      `weft_clean/hyphenation.py:71-72 'intact: '
      'intact:'`,
      `weft_clean/whitespace.py:64-65 'intact: t'`, `weft_clean/table_linearizer.py:79 'destroys:'`,
@@ -74,11 +74,17 @@ The four concerns:
      structural here, read off the span's own attributes, rather than four
      keyword arguments an author has to remember to pass at every call site.
 
-   **NUL becomes a space, never a deletion**, because `weft_chunk.payload.ChunkOffset` records a
-   character offset into a parent's content, so deleting a byte would
-   silently shift every offset recorded downstream of the node being
-   cleaned. A space is one character for one character; every offset already
-   recorded against this content stays correct.
+   **NUL becomes a space, never a deletion**, because this seam rewrites a
+   node's content *after* whatever produced it has already described it, and
+   a length-changing edit silently invalidates any description that indexes
+   into that content by position. A space is one character for one
+   character, so every such fact stays correct. **The reason is structural
+   rather than live as of 2026-09-12**: `weft_chunk.payload.ChunkOffset` was
+   the one shipped `ExtModel` recording a character offset, and repair
+   `R17.1` withdrew it once **G17** left it with no reader. Nothing in the
+   tree indexes content by position today — which is an argument for
+   preserving length cheaply while that is true, not for spending the
+   invariant.
 
    **Scope is `Node.content` and the `str`-typed fields of whatever
    `ExtModel`s `Node.ext` carries** — `weft_store/pgvector_store.py`'s
@@ -129,14 +135,14 @@ three concerns still apply: a span, the blocking-call guard, and, for a bare
 gives `run()`.
 
 **`guard_blocking_calls`, added by `weft-cli` task 3.4 for a caller outside
-`Runner`'s own reach.** `docs/build-ledger.md` 3.2 tried running a
+`Runner`'s own reach.** `docs/internal/build-ledger.md` 3.2 tried running a
 `weft_command.contract.Command` invocation through this function unchanged
 and reverted: `weft index`'s synchronous filesystem walk tripped concern 4,
 which exists because a blocking `Stage` starves an event loop *other stages
 share* — a `Command` is CLI orchestration invoked once per invocation or
 REPL turn, with nothing else scheduled on that loop to starve, so the guard
 was a false positive for it rather than a caught defect. 3.4's own analysis
-(recorded in full in its `docs/build-ledger.md` entry) rejected two other
+(recorded in full in its `docs/internal/build-ledger.md` entry) rejected two other
 shapes for this fact: a second, hand-written span-and-attribution wrapper in
 `weft_cli` (a second implementation of a concern this module already owns,
 free to drift from it) and applying the guard unconditionally (the reverted
@@ -677,7 +683,7 @@ def _sanitize_ext_model(model: ExtModel) -> tuple[ExtModel, int]:
 
     Scoped to a field whose *runtime value* is a `str` — not `tuple[str, ...]`
     or `list[str]`, checked by `isinstance` rather than by the field's
-    annotation. `docs/build-ledger.md` → 2.34 scopes this task to "`Node.content`
+    annotation. `docs/internal/build-ledger.md` → 2.34 scopes this task to "`Node.content`
     and the `str`-typed fields of the `ExtModel`s in `Node.ext`" literally; no
     shipped `ExtModel` as of this task holds a string collection built from
     verbatim extractor text, so widening to collections has no motivating case
@@ -723,3 +729,64 @@ def _clean_str(value: str) -> tuple[str, int]:
     if "\x00" not in value:
         return value, 0
     return value.replace("\x00", " "), value.count("\x00")
+
+
+async def aclose(
+    instance: object,
+    *,
+    distribution: str,
+    contract: str,
+    plugin: str,
+    stage: str | None = None,
+) -> None:
+    """Close `instance` if it has an `aclose`, with the same span, guard and attribution
+    `wrap_flush` gives `flush`.
+
+    `aclose` is a fact read off the instance, never a method any contract publishes — an
+    in-memory store and every third-party pack that keeps no socket has nothing to close, and
+    requiring the method would be a line each of them has to write in order to be reaped. So
+    the defensive read and the call are one function rather than two: a caller that still had
+    to ask *is there one?* before calling a separate helper would still be the caller deciding,
+    and three call sites deciding it independently is exactly the copy this replaces.
+
+    This is a function callers reach for, never something the runner does on their behalf:
+    the instantiator owns the lifetime it opened, and a `Lifetime.PROCESS` instance outlives
+    any one run, so closing it is not the runner's to do.
+
+    `stage` is optional, defaulted to `f"{contract}:{plugin}"` exactly as `wrap` defaults it for
+    a caller with no pipeline concept — two of this function's three callers hold no pipeline
+    position at all, unlike `wrap_flush`'s one caller, which always has a resolved `StageSpec.id`.
+
+    No `_strip_transient` and no `_sanitize_control_bytes` — like `flush`, `aclose` returns
+    nothing an `Outcome` could decide.
+    """
+    found = getattr(instance, "aclose", None)
+    if found is None or not callable(found):
+        return
+    close = cast("Callable[[], Awaitable[None]]", found)
+
+    label = stage if stage is not None else f"{contract}:{plugin}"
+    with _tracer.start_as_current_span(f"{label}:aclose", kind=SpanKind.INTERNAL) as span:
+        span.set_attribute("weft.pack", distribution)
+        span.set_attribute("weft.contract", contract)
+        span.set_attribute("weft.plugin", plugin)
+        with blocking.guard(f"{label}:aclose"):
+            try:
+                await close()
+            except WeftError as exc:
+                _attribute(
+                    exc,
+                    distribution=distribution,
+                    contract=contract,
+                    plugin=plugin,
+                    stage=label,
+                )
+                raise
+            except Exception as exc:
+                raise WeftError(
+                    f"'{label}' close failed: {exc}",
+                    pack=distribution,
+                    contract=contract,
+                    plugin=plugin,
+                    stage=label,
+                ) from exc