weft-kernel 0.1.0__tar.gz

weft_kernel-0.1.0/.gitignore

@@ -0,0 +1,85 @@
+# A sibling checkout, reachable for reading only.
+# Never a build input: see CLAUDE.md and docs/README.md.
+/_external-src
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.pyright/
+
+# `uv.lock` was here, filed between two caches. It is not a cache: `ci.yml` runs
+# `uv sync --frozen` in three of its four jobs, and every one of them died at that step
+# the first time CI ever ran. It is tracked now — the resolution CI installs and the
+# resolution a developer installs must be one artefact, which is the same argument
+# `docs/README.md` makes about single-sourcing anything two readers can disagree about.
+#
+# It constrains nobody downstream. A lockfile is not a dependency bound; what a consumer
+# resolves is decided by each distribution's `pyproject.toml`.
+
+# Session-local attempt counter for the guard_quality_gates.py PreToolUse hook — per-session
+# scratch, not a record anyone should read later. See the hook's module docstring.
+.claude/.gate-attempts.json
+
+# Secrets. `.env` holds live provider keys; only the documented, valueless
+# example is tracked. Listed before any tooling rule so a stray `git add -A`
+# cannot reach it.
+.env
+.env.*
+!.env.example
+
+# Corpus payload. Every subdirectory of /corpus is a materialised document set and
+# is deliberately untracked; `corpus/manifest.toml` and `scripts/fetch_corpus.py`
+# are the tracked artefact. `09` §4 V1 permits exactly this:
+# a corpus is "either redistributable or fetched by a pinned, checksummed script",
+# and the mRMR papers are published under publisher copyright, so committing them
+# would be redistribution this repository has no right to perform. The manifest
+# carries a sha256 per document, which is what makes the set reproducible without
+# the bytes being here. The pattern is a directory glob rather than a list of names
+# so that scaling the corpus up cannot silently start tracking a paper.
+/corpus/*/
+
+# Where a baseline run stages the corpus it indexes and writes the `weft.toml` it measures
+# through (`eval/run_baseline.py`). The staged copies are the same untracked papers one
+# directory over, and the configuration is reproduced by the harness rather than kept — what
+# is tracked is the run it produced, under `eval/baselines/`.
+/.baseline-run/
+
+# Working artefacts of a build session — a generated map of the codebase and a design
+# record produced while planning. Untracked on purpose: `docs/README.md` routes every
+# document this project owns, and a design that matters belongs in the `docs/` file
+# that owns its content, not in a root-level file nothing points at.
+/.phase2-*.md
+/.phase3-*.md
+/.phase4-*.md
+
+# Gate-session preparation: the Bring lists of `docs/05-grilling-sessions.md`, measured on the day
+# a session is about to run. Untracked for the same reason — the session's outcome belongs in
+# `docs/README.md`'s decision log and in the reference document the decision changes, never here.
+/.gate-brief-*.md
+
+# Claude Code local state
+.claude/settings.local.json
+
+.DS_Store
+
+# The build harness driving Phase 2, alongside its brief, findings and design record.
+/.phase2-build.js
+
+# Transient: harvested subagent findings, promoted into docs/lessons.md by implement-ll.
+# Never committed — its content belongs in the queue or nowhere.
+.claude/lessons-spool.md
+
+# Reading material and design records about codebases this project does not own.
+# Kept on disk, deliberately outside version control: nothing tracked here refers to
+# them, and a write to any of them would leave no trace in a diff.
+/docs/_external-reading/
+
+/tmp/

weft_kernel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Krysztopa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

weft_kernel-0.1.0/NOTICE

@@ -0,0 +1,77 @@
+Weft
+Copyright (c) 2026 Adam Krysztopa
+
+This product is licensed under the MIT License. See the LICENSE file at the root
+of this repository.
+
+--------------------------------------------------------------------------------
+Original work
+--------------------------------------------------------------------------------
+
+**Weft carries no third party's source text.** Every line of this project's own
+code is written for it, against its own contracts. Nothing here depends on a
+licence granted by anyone else.
+
+That is a rule, not a description: no file may be copied or adapted from another
+project's source, and no third-party source text may be pasted into this
+repository. Where a prior system informed a design, what was carried across is
+understanding — an approach, an ordering, a measurement, a reason a guard exists
+— restated in this project's own words and implemented fresh. Copyright does not
+reach any of that.
+
+What was learned from prior work, and what was deliberately not taken, is a
+design record kept outside version control. Nothing in it authorises a copy of a
+third party's text, because that is not permitted here at all.
+
+--------------------------------------------------------------------------------
+Three cases, because the sentence above used to be absolute and was not accurate
+--------------------------------------------------------------------------------
+
+This section was added on 2026-09-05. It previously read "Weft contains no source
+text from any other codebase", and two separate things made that literally false
+while nothing about the project's substance had changed. Both are stated here
+rather than left for a reader to discover, because a founding claim that is
+almost true is worse than a narrower one that is exactly true.
+
+1. **A third party's code — never.** Somebody else's work is somebody else's:
+   not a file, a function body, a docstring, a comment, a prompt string, a word
+   list or a test fixture. Read to understand, then closed. This is the rule
+   above and it has not moved.
+
+2. **The copyright holder's own prior work — permitted, and marked.** Material
+   written by this project's own author before this project began carries no
+   third party's rights. Copying it violates nobody's licence, and forbidding it
+   would be a rule about tidiness dressed as a rule about ownership. Where such
+   material is carried across, the file carrying it says so, naming the source
+   work — so a reader can always tell the two origins apart without asking.
+
+   **How it says so, because "says so" was a sentence and not a convention until
+   2026-09-09.** The carried lines are delimited in place, by a comment in
+   whatever syntax the file is written in: `weft-prior-work begin: <source work>`
+   opens the span and names the source work it came from, and
+   `weft-prior-work end` closes it and takes no argument. Spans do not nest — a
+   span inside a span makes *which lines are that work* answerable two ways,
+   which is the one question this convention exists to answer. Every source work
+   carried this way is enumerated on the repository's own README.md, where a
+   reader looks first, and tests/architecture/test_release_licensing.py fails
+   the build when the marked spans and that enumeration disagree. The obligation
+   falls in the same commit as the copied line and never after it, which is why
+   the check exists before the first copy rather than behind it.
+
+3. **Short attributed quotation of a stated rationale — permitted, and bounded.**
+   A handful of docstrings in this repository quote a sentence of a third party's
+   *reasoning* — why one cleaning stage must run before another — attributed with
+   a path and a line number, immediately beside this project's own restatement of
+   the same reasoning. Nothing executable was ever carried this way: no
+   expression, no algorithm, no data. This is ordinary attributed quotation of a
+   published rationale, of the kind a comment citing a paper makes, and the
+   previous absolute wording forbade it in words while the repository practised
+   it. It is bounded rather than open: a quotation must be a sentence or two, it
+   must be attributed at the point of use, and it must sit next to the project's
+   own words on the same point — never stand in for them.
+
+The distinction that matters, and it is the same test the rest of this project
+uses: **if you could not have written it without the other file open, it is a
+copy.** Case 1 forbids that outright. Case 2 permits it because the other file is
+the author's own. Case 3 is not that at all — it is quoting someone, with their
+name on it, beside your own argument.

weft_kernel-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: weft-kernel
+Version: 0.1.0
+Summary: The Weft kernel: registry, discovery, pipeline model, payload types.
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: opentelemetry-api>=1.28
+Requires-Dist: pydantic>=2.9
+Description-Content-Type: text/markdown
+
+# weft-kernel
+
+The kernel of Weft, a RAG engine built as a microkernel. This distribution is the registry a pack
+registers into, the entry-point discovery that finds packs, the pipeline model a pipeline document
+resolves against, the payload types every stage signature names, and the registration seam every
+stage's execution passes through. It contains no RAG capability of any kind.
+
+## The one thing that makes it unusual
+
+**The kernel names no capability.** There is no `Extractor`, `Chunker`, `Store`, `Retriever` or
+`LLM` in this package — those contracts are published by the first-party packs that own them, in
+`weft-rag`, on exactly the same public entry point a third party's pack would use. What ships here
+is the mechanism a contract is expressed and run through, never a contract itself.
+
+This is not a design intention stated in a docstring; it is checked. `weft-kernel` is a separate
+installable distribution for exactly one reason: `poe kernel-isolated` installs it alone into a
+clean environment and imports it, so if anything reached outside what it ships, the import fails.
+A static counterpart walks every import in the source tree against the same declared dependency
+set. Both are fitness function 1, in `tests/architecture/test_ff1_boundary.py`.
+
+## Dependencies
+
+Exactly `pydantic` and `opentelemetry-api` — that is `packages/weft-kernel/pyproject.toml`'s whole
+`dependencies` list, and a third dependency is a decision-log entry, not a line in a pyproject.
+`opentelemetry-api` is the no-op-without-an-SDK API; anything that actually exports a span is a
+pack's concern (`weft-otel`), not this one's.
+
+## Async only
+
+Every contract method this kernel's types describe is `async def`. There is no sync protocol and
+no sync facade anywhere in this package — a stage runs on the event loop, and a categorical
+detector installed at the registration seam (`weft_kernel.blocking`) fails the build on a blocking
+call made on that thread rather than tolerating one behind a synchronous-looking signature.
+
+## What is actually in here
+
+Twenty modules under `weft_kernel`, none of them a plugin:
+
+- `registry.py` — where a pack's `register()` adds what it provides, and where an unresolvable
+  name fails loudly, naming what was wanted and what is registered.
+- `discovery.py` — entry-point discovery and the trust model: which installed distributions get
+  imported, what a pack may disclose about itself, and the `[packs] allow` pin that refuses an
+  import before it happens rather than after.
+- `pipeline.py` / `resolution.py` / `runner.py` — the pipeline as authored data, the pipeline
+  resolved to a frozen explicit form, and the linear runner that executes a resolved chain.
+- `seam.py` — `wrap`, the one seam every stage's call passes through: spans, error attribution,
+  `__transient__` stripping and the blocking-call detector attach here, automatically, so no
+  author has to remember any of the four.
+- `context.py` — the passport every stage receives: tenant, run and trace ids, cancellation,
+  locale, and `require()` for an ambient service.
+- `payload/` — the domain model a stage signature names: `Node`, `NodeId`, `Lineage`, `MediaType`,
+  `Vector`, `Outcome`, `ExtModel`/`ExtMap` (a pack's own namespaced, validated extension data), and
+  the `Property` and `Applies` markers a plugin class declares itself against.
+- `errors.py` / `fallback.py` / `blocking.py` — the `WeftError` root every pack raises against, the
+  fallback-chain combinator that composes plugins over any contract without inspecting them, and
+  the blocking-call detector above.
+
+The kernel is also held to a size ceiling: `uv run pytest tests/architecture/test_ff3_kernel_budget.py -s`
+measures 3,300 non-blank, non-comment, non-docstring lines against a 3,500-line fail and a
+2,800-line review trigger — a stated budget rather than an unstated one, so growth is on the agenda
+before it is a crisis.
+
+## You probably do not want this package
+
+If you want to index a directory and ask a question about it, install `weft-rag`, not this. It
+depends on `weft-kernel` and brings the packs that do the actual work — extraction, chunking,
+embedding, storage, retrieval, generation — plus the `weft` command:
+
+```bash
+uvx --from weft-rag weft --help
+```
+
+`weft-kernel` exists as its own installable distribution so that fitness function 1 can be a fact
+about a clean install rather than a claim about the source tree. Install it directly only if you
+are writing a pack against its registry and discovery mechanism and want nothing else on the
+import path while you do it.

weft_kernel-0.1.0/README.md

@@ -0,0 +1,76 @@
+# weft-kernel
+
+The kernel of Weft, a RAG engine built as a microkernel. This distribution is the registry a pack
+registers into, the entry-point discovery that finds packs, the pipeline model a pipeline document
+resolves against, the payload types every stage signature names, and the registration seam every
+stage's execution passes through. It contains no RAG capability of any kind.
+
+## The one thing that makes it unusual
+
+**The kernel names no capability.** There is no `Extractor`, `Chunker`, `Store`, `Retriever` or
+`LLM` in this package — those contracts are published by the first-party packs that own them, in
+`weft-rag`, on exactly the same public entry point a third party's pack would use. What ships here
+is the mechanism a contract is expressed and run through, never a contract itself.
+
+This is not a design intention stated in a docstring; it is checked. `weft-kernel` is a separate
+installable distribution for exactly one reason: `poe kernel-isolated` installs it alone into a
+clean environment and imports it, so if anything reached outside what it ships, the import fails.
+A static counterpart walks every import in the source tree against the same declared dependency
+set. Both are fitness function 1, in `tests/architecture/test_ff1_boundary.py`.
+
+## Dependencies
+
+Exactly `pydantic` and `opentelemetry-api` — that is `packages/weft-kernel/pyproject.toml`'s whole
+`dependencies` list, and a third dependency is a decision-log entry, not a line in a pyproject.
+`opentelemetry-api` is the no-op-without-an-SDK API; anything that actually exports a span is a
+pack's concern (`weft-otel`), not this one's.
+
+## Async only
+
+Every contract method this kernel's types describe is `async def`. There is no sync protocol and
+no sync facade anywhere in this package — a stage runs on the event loop, and a categorical
+detector installed at the registration seam (`weft_kernel.blocking`) fails the build on a blocking
+call made on that thread rather than tolerating one behind a synchronous-looking signature.
+
+## What is actually in here
+
+Twenty modules under `weft_kernel`, none of them a plugin:
+
+- `registry.py` — where a pack's `register()` adds what it provides, and where an unresolvable
+  name fails loudly, naming what was wanted and what is registered.
+- `discovery.py` — entry-point discovery and the trust model: which installed distributions get
+  imported, what a pack may disclose about itself, and the `[packs] allow` pin that refuses an
+  import before it happens rather than after.
+- `pipeline.py` / `resolution.py` / `runner.py` — the pipeline as authored data, the pipeline
+  resolved to a frozen explicit form, and the linear runner that executes a resolved chain.
+- `seam.py` — `wrap`, the one seam every stage's call passes through: spans, error attribution,
+  `__transient__` stripping and the blocking-call detector attach here, automatically, so no
+  author has to remember any of the four.
+- `context.py` — the passport every stage receives: tenant, run and trace ids, cancellation,
+  locale, and `require()` for an ambient service.
+- `payload/` — the domain model a stage signature names: `Node`, `NodeId`, `Lineage`, `MediaType`,
+  `Vector`, `Outcome`, `ExtModel`/`ExtMap` (a pack's own namespaced, validated extension data), and
+  the `Property` and `Applies` markers a plugin class declares itself against.
+- `errors.py` / `fallback.py` / `blocking.py` — the `WeftError` root every pack raises against, the
+  fallback-chain combinator that composes plugins over any contract without inspecting them, and
+  the blocking-call detector above.
+
+The kernel is also held to a size ceiling: `uv run pytest tests/architecture/test_ff3_kernel_budget.py -s`
+measures 3,300 non-blank, non-comment, non-docstring lines against a 3,500-line fail and a
+2,800-line review trigger — a stated budget rather than an unstated one, so growth is on the agenda
+before it is a crisis.
+
+## You probably do not want this package
+
+If you want to index a directory and ask a question about it, install `weft-rag`, not this. It
+depends on `weft-kernel` and brings the packs that do the actual work — extraction, chunking,
+embedding, storage, retrieval, generation — plus the `weft` command:
+
+```bash
+uvx --from weft-rag weft --help
+```
+
+`weft-kernel` exists as its own installable distribution so that fitness function 1 can be a fact
+about a clean install rather than a claim about the source tree. Install it directly only if you
+are writing a pack against its registry and discovery mechanism and want nothing else on the
+import path while you do it.

weft_kernel-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "weft-kernel"
+version = "0.1.0"
+description = "The Weft kernel: registry, discovery, pipeline model, payload types."
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+readme = "README.md"
+dependencies = ["pydantic>=2.9", "opentelemetry-api>=1.28"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

weft_kernel-0.1.0/src/weft_kernel/__init__.py

@@ -0,0 +1,178 @@
+"""The Weft kernel.
+
+What belongs here is settled in G1 and specified in `docs/01-high-level-plan.md`
+under *The kernel boundary*: the kernel is what is required to express, load and
+run contracts it knows nothing about, plus the domain types those signatures
+unavoidably name — and nothing in the kernel performs RAG work.
+
+Its two dependencies, `pydantic` and `opentelemetry-api`, are declared and
+enforced by fitness function 1.
+"""
+
+from weft_kernel.blocking import BlockingCallError
+from weft_kernel.context import (
+    Context,
+    DuplicateServiceError,
+    ServiceRegistry,
+    ServiceRole,
+    UnresolvedServiceError,
+)
+from weft_kernel.discovery import (
+    ENTRY_POINT_GROUP,
+    Disclosure,
+    EntryPointLike,
+    EnvInterpolationError,
+    PackRegistrar,
+    PackReport,
+    PackSettingsError,
+    PackStatus,
+    PipelineResource,
+    allow_list_from_config,
+    discover,
+    interpolate_env,
+)
+from weft_kernel.errors import UnresolvedNameError, WeftError
+from weft_kernel.fallback import Attempt, try_in_order
+from weft_kernel.payload import (
+    SCHEMA_VERSION_KEY,
+    ExtMap,
+    ExtModel,
+    Failed,
+    Lineage,
+    MediaType,
+    Node,
+    NodeId,
+    NothingToProduce,
+    Outcome,
+    Produced,
+    Property,
+    SchemaVersionRefusedError,
+    SourceId,
+    SyntheticOrigin,
+    Vector,
+)
+from weft_kernel.pipeline import (
+    InsertOperator,
+    Pipeline,
+    SetOperator,
+    SlotDeclaration,
+    StageDeclaration,
+)
+from weft_kernel.registry import (
+    DuplicateRegistrationError,
+    MissingDestroysDeclarationError,
+    MissingRequiredDeclarationError,
+    Registry,
+    RegistryEntry,
+    UnknownPluginError,
+)
+from weft_kernel.resolution import (
+    Contribution,
+    InvalidStageConfigError,
+    OperatorIdCollisionError,
+    PipelineCycleError,
+    ResolvedPipeline,
+    ResolvedStage,
+    SlotOrderConflictError,
+    StageNotConfigurableError,
+    StaleOperatorTargetError,
+    UndefinedVarError,
+    UnknownParentPipelineError,
+    resolve,
+)
+from weft_kernel.runner import (
+    FlushError,
+    IntactViolationError,
+    Lifetime,
+    PipelineResolutionError,
+    RunnablePipeline,
+    Runner,
+    RunSummary,
+    Stage,
+    StageCompositionError,
+    StageSpec,
+    TenantMismatchError,
+    UnknownFallbackError,
+    UnmetRequiresError,
+)
+from weft_kernel.seam import Deprecation, wrap, wrap_flush
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "SCHEMA_VERSION_KEY",
+    "Attempt",
+    "BlockingCallError",
+    "Context",
+    "Contribution",
+    "Deprecation",
+    "Disclosure",
+    "DuplicateRegistrationError",
+    "DuplicateServiceError",
+    "EntryPointLike",
+    "EnvInterpolationError",
+    "ExtMap",
+    "ExtModel",
+    "Failed",
+    "FlushError",
+    "InsertOperator",
+    "IntactViolationError",
+    "InvalidStageConfigError",
+    "Lifetime",
+    "Lineage",
+    "MediaType",
+    "MissingDestroysDeclarationError",
+    "MissingRequiredDeclarationError",
+    "Node",
+    "NodeId",
+    "NothingToProduce",
+    "OperatorIdCollisionError",
+    "Outcome",
+    "PackRegistrar",
+    "PackReport",
+    "PackSettingsError",
+    "PackStatus",
+    "Pipeline",
+    "PipelineCycleError",
+    "PipelineResolutionError",
+    "PipelineResource",
+    "Produced",
+    "Property",
+    "Registry",
+    "RegistryEntry",
+    "ResolvedPipeline",
+    "ResolvedStage",
+    "RunnablePipeline",
+    "Runner",
+    "RunSummary",
+    "SchemaVersionRefusedError",
+    "ServiceRegistry",
+    "ServiceRole",
+    "SetOperator",
+    "SlotDeclaration",
+    "SlotOrderConflictError",
+    "SourceId",
+    "Stage",
+    "StageCompositionError",
+    "StageDeclaration",
+    "StageNotConfigurableError",
+    "StageSpec",
+    "StaleOperatorTargetError",
+    "SyntheticOrigin",
+    "TenantMismatchError",
+    "UndefinedVarError",
+    "UnknownFallbackError",
+    "UnknownParentPipelineError",
+    "UnknownPluginError",
+    "UnmetRequiresError",
+    "UnresolvedNameError",
+    "UnresolvedServiceError",
+    "Vector",
+    "WeftError",
+    "allow_list_from_config",
+    "discover",
+    "interpolate_env",
+    "resolve",
+    "try_in_order",
+    "wrap",
+    "wrap_flush",
+]