weft-generate 1.0.0__tar.gz

weft_generate-1.0.0/.gitignore

@@ -0,0 +1,78 @@
+# The donor checkout, reachable for reading and lifting only.
+# Never a build input: see CLAUDE.md and docs/README.md.
+/donor
+
+# 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

weft_generate-1.0.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_generate-1.0.0/NOTICE

@@ -0,0 +1,24 @@
+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 contains no source text from any other codebase.** Every line here is
+written for this project, against this project's contracts.
+
+This is a rule, not a description of the current state: 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, and nothing in this repository
+depends on a licence granted by anyone else.
+
+`docs/04-donor-inventory.md` records what was learned from prior work and what
+was deliberately not taken. It is a design record. Nothing in it authorises a
+copy, because copying is not permitted here at all.

weft_generate-1.0.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: weft-generate
+Version: 1.0.0
+Summary: First-party generation pack. Publishes the Generator contract and the Answer vocabulary.
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: weft-kernel<1.0.0,>=0.1.0
+Requires-Dist: weft-llm<2.0.0,>=1.0.0
+Requires-Dist: weft-prompts<2.0.0,>=1.0.0
+Requires-Dist: weft-retrieve<2.0.0,>=1.0.0
+Requires-Dist: weft-store<3.0.0,>=2.0.0

weft_generate-1.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "weft-generate"
+version = "1.0.0"
+description = "First-party generation pack. Publishes the Generator contract and the Answer vocabulary."
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+dependencies = ["weft-kernel>=0.1.0,<1.0.0", "weft-store>=2.0.0,<3.0.0", "weft-retrieve>=1.0.0,<2.0.0", "weft-llm>=1.0.0,<2.0.0", "weft-prompts>=1.0.0,<2.0.0"]
+
+# `weft-llm` and `weft-prompts` are new as of task 2.9: `cited-answer` asks a registered
+# prompt through `weft_prompts.contract.Prompt` and answers through `weft_llm.contract.LLM`,
+# exactly the way `weft-retrieve`'s `llm-rerank` does one pack over.
+
+# `weft.packs` arrives with this same task: `cited-answer` is the first plugin this
+# distribution registers, so there is finally something for the entry point to name.
+[project.entry-points."weft.packs"]
+generate = "weft_generate:register"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

weft_generate-1.0.0/src/weft_generate/__init__.py

@@ -0,0 +1,115 @@
+"""First-party generation pack.
+
+Publishes the `Generator` contract (`contract.py`) and the answer vocabulary
+(`payload.py`). Task **2.4** built the mechanism and registered nothing under it, the
+same way `weft-retrieve` did before task 2.7 — see
+`packages/weft-retrieve/src/weft_retrieve/__init__.py` for the whole reason a `weft.packs`
+entry point waits for a plugin to name. Task **2.9** was the first plugin here:
+`cited-answer`, brought together with its own registered `Prompt` in one `register()`
+call, the same shape `weft_retrieve.register` uses for `llm-rerank` and
+`passage-relevance`. **Task 2.22 is the second**: `contradiction-check`, with its own two
+registered prompts. **Task 2.24 is the third**: `refine-on-uncertainty`, which registers no
+new prompt of its own — its own drafting call reuses `cited-answer`'s already-registered
+`answer-with-citations`, and its uncertainty trigger is `weft_retrieve.contract.Sufficiency`
+(task 2.4's contract; `weft_retrieve.sufficiency`, this same task's other half, is where
+`llm-sufficiency` and `hedge-phrases` register), resolved by name through `StageLookup`
+rather than imported here.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+from weft_generate.cited_answer import NAME as CITED_ANSWER_NAME
+from weft_generate.cited_answer import CitedAnswer, CitedAnswerConfig, WhenNoEvidence
+from weft_generate.contract import GENERATE_CONTRACT_VERSION, Generator
+from weft_generate.contradiction import NAME as CONTRADICTION_CHECK_NAME
+from weft_generate.contradiction import Agreement, ContradictionCheck, ContradictionCheckConfig
+from weft_generate.payload import Answer, AnswerStance, Citation
+from weft_generate.prompts import (
+    ANSWER_WITH_CITATIONS_NAME,
+    CONTRADICTION_ANSWER_NAME,
+    CONTRADICTION_CRITIC_NAME,
+    AnswerWithCitationsPrompt,
+    ConflictStatus,
+    ContradictionAnswerPrompt,
+    ContradictionCriticPrompt,
+)
+from weft_generate.refine import NAME as REFINE_ON_UNCERTAINTY_NAME
+from weft_generate.refine import (
+    RefinementStop,
+    RefinementTrace,
+    RefineOnUncertainty,
+    RefineOnUncertaintyConfig,
+    refinement_stop,
+)
+from weft_kernel.discovery import PackRegistrar
+from weft_prompts.contract import Prompt
+
+
+class Settings(BaseModel):
+    """`weft-generate` takes no pack settings — an empty model is still the required shape."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+def register(registrar: PackRegistrar, settings: Settings) -> None:
+    """Register every `Generator` this pack ships, and the prompts each one asks under
+    `Prompt`.
+
+    Every `Prompt` goes through the same `registrar` as its owning `Generator` —
+    `weft_retrieve.__init__`'s own docstring states why a first-party prompt belongs to
+    the plugin that asks the question rather than to `weft-prompts`, which registers
+    nothing at all.
+
+    **`Agreement` and `RefinementTrace` are deliberately not passed to `registrar.
+    add_ext_model` — task 5.2g's own finding, not an oversight.** Both attach to
+    `Answer.ext`, never to `Node.ext`, and only a `Node` is ever handed to a `NodeStore` —
+    `weft_store.rehydrate.rehydrate_ext` reconstructs a *node's* `ext` map and is never
+    called with an `Answer`'s. Registering both would also collide: they share
+    `__namespace__ = "weft-generate"`, so `weft_store.rehydrate.ext_models` — one class
+    per namespace, globally — would raise `DuplicateRegistrationError` the moment both
+    are active, which `contradiction-check` and `refine-on-uncertainty` together already
+    are in this pack's own default pipelines. `docs/lessons.md` L5.20 records this as the
+    reason `add_ext_model` is for an `ExtModel` that reaches a `Node`, not for every
+    `ExtModel` a pack happens to own — see `weft_retrieve.__init__`'s own module
+    docstring for the identical finding against `BooleanPlan`/`CorrectiveTrace`/
+    `IterativeRetrievalTrace`.
+    """
+    del settings
+    registrar.add(Generator, CITED_ANSWER_NAME, CitedAnswer)
+    registrar.add(Prompt, ANSWER_WITH_CITATIONS_NAME, AnswerWithCitationsPrompt)
+    registrar.add(Generator, CONTRADICTION_CHECK_NAME, ContradictionCheck)
+    registrar.add(Prompt, CONTRADICTION_CRITIC_NAME, ContradictionCriticPrompt)
+    registrar.add(Prompt, CONTRADICTION_ANSWER_NAME, ContradictionAnswerPrompt)
+    registrar.add(Generator, REFINE_ON_UNCERTAINTY_NAME, RefineOnUncertainty)
+
+
+__all__ = [
+    "ANSWER_WITH_CITATIONS_NAME",
+    "CITED_ANSWER_NAME",
+    "CONTRADICTION_ANSWER_NAME",
+    "CONTRADICTION_CHECK_NAME",
+    "CONTRADICTION_CRITIC_NAME",
+    "GENERATE_CONTRACT_VERSION",
+    "REFINE_ON_UNCERTAINTY_NAME",
+    "Agreement",
+    "Answer",
+    "AnswerStance",
+    "AnswerWithCitationsPrompt",
+    "Citation",
+    "CitedAnswer",
+    "CitedAnswerConfig",
+    "ConflictStatus",
+    "ContradictionAnswerPrompt",
+    "ContradictionCheck",
+    "ContradictionCheckConfig",
+    "ContradictionCriticPrompt",
+    "Generator",
+    "RefineOnUncertainty",
+    "RefineOnUncertaintyConfig",
+    "RefinementStop",
+    "RefinementTrace",
+    "Settings",
+    "WhenNoEvidence",
+    "refinement_stop",
+    "register",
+]

weft_generate-1.0.0/src/weft_generate/cited_answer.py

@@ -0,0 +1,274 @@
+"""`cited-answer` — the one `Generator` this task ships. `Stage[Passages, Answer]`.
+
+Task **2.9**, `docs/build-ledger.md`: "an answer carries citations a reader can follow
+back to a passage — not to a document, and not to a paraphrase." `weft_generate.payload.
+Answer._citations_resolve` already makes the *shape* of that unconstructable to violate;
+this module is what builds an `Answer` in the first place, and what keeps the marker a
+model writes and the passage `Answer.used` records honest with each other.
+
+**One plugin, two behaviours, configuration — `01` requirement 6's second clause instead
+of a second generator name.** `when_no_evidence` decides what happens when `Passages` is
+empty: `REFUSE` answers `Answer(stance=NOT_IN_CORPUS)` and calls no model at all — the
+line `.phase2-design.md` §3 states outright, "`cited-answer` is the stage that turns
+empty evidence into `Answer(stance=NOT_IN_CORPUS)`" — and `ANSWER_FROM_MEMORY` asks the
+same prompt with no passages shown, which is what `no-retrieval`'s own pipeline sets.
+
+**Citations are extracted from the completion, never asked for as a second structured
+field.** `docs/04-donor-inventory.md`'s corrected `CitationManager` row records the
+donor's second responsibility as "extract which sources were actually cited" through
+four ordered, language-specific regexes over freeform text. This build does not need
+them: `weft_retrieve.payload.Passages` already assigns every offered passage an exact,
+known label before a model ever sees one, so "which sources were cited" is answered by a
+literal substring search for `[label]` per offered passage — no language heuristic, and
+no way for the search to disagree with what was actually shown, because the label
+searched for and the label shown are the same string. This also settles a question the
+donor's approach could not: a model is asked for prose, not for a second list of markers
+that could name a passage never offered or drop one it clearly used — the two ways
+`weft_retrieve.rerank`'s judgement-set check refuses a reranker's reply, in a shape this
+plugin cannot have because it never asks for that second list.
+
+**Page numbers are `weft_generate.page.page_for`'s, not this module's.** Every citation
+this plugin builds carries whatever that function resolves for the cited node — `None`
+when nothing in the pipeline attached the two facts it needs. See that module for why
+`cited_answer.py` imports neither `weft_chunk` nor `weft_pdf` to get there.
+
+**Task 2.31's own obligation, closed here — and it turned out to reach further than a
+`Citation` field.** `.phase2-findings.md` §11: "a hit on any of them resolves through
+lineage to the one parent chunk... which is what makes task 2.9's citations able to follow
+back to a passage rather than to a paraphrase of one." The first attempt patched
+`Citation.node_id` alone and `Answer._citations_resolve` refused it outright: that
+validator requires a citation's `node_id` to be the id of the very passage `used` records
+under the marker naming it, by construction, so a `Citation` cannot point at a different
+node than the `Passage` it is paired with — the renumbering bug it exists to make
+unconstructable is exactly the shape a citation-only patch would have produced. So the
+resolution moves one step earlier: `_resolved_to_citable`, below, substitutes a
+representation's own node for the one it stands in for — via `weft_generate.
+representation.citable_nodes`, the same duck-typed, no-new-dependency read `page_for`
+already sets a precedent for — on `offered` itself, before it becomes `_offer`'s prompt
+text, before it becomes `Answer.used`, and before a `Citation` is built from it. One
+substitution, three consumers agreeing, rather than three places that could disagree.
+This also closes the corollary gap for free: a model asked to answer from a retrieved
+question's own wording would have been shown that wording as "evidence"; now it reads the
+real passage the representation stands in for, the same as everything else it is offered.
+
+**What this does not do.** Two representations of the *same* parent occupying two offered
+slots still occupy two — this substitutes identity, node for node, and applies no score
+policy across slots. Collapsing that duplication before it reaches this stage at all is
+`10` §1.2's `collapse-to-parent` row (ledger task 2.33), which owns a `Ranking`-level
+merge policy this plugin's own 1:1 substitution neither needs nor should guess at.
+"""
+
+from collections.abc import Iterable
+from enum import StrEnum
+from typing import ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from weft_generate.page import page_for
+from weft_generate.payload import Answer, AnswerStance, Citation
+from weft_generate.prompts import ANSWER_WITH_CITATIONS_NAME, AnswerWithCitationsRequest
+from weft_generate.representation import citable_nodes
+from weft_kernel.context import Context
+from weft_kernel.payload import Node, Outcome, Produced, SourceId
+from weft_llm.contract import LLM
+from weft_prompts.contract import Prompt
+from weft_retrieve.contract import StageLookup
+from weft_retrieve.payload import Passage, Passages
+from weft_store.contract import NodeStore, Scored
+
+#: The name this generator is registered and selectable under — see `weft_generate.register`.
+NAME = "cited-answer"
+
+
+class WhenNoEvidence(StrEnum):
+    """What `cited-answer` does when `Passages.passages` is empty. `Enum`, project rule."""
+
+    #: `Answer(stance=NOT_IN_CORPUS)`, no model call — the default, and what "the corpus
+    #: does not contain it" means when nothing was ever retrieved to check.
+    REFUSE = "refuse"
+    #: Ask the model anyway, with no passages shown — what `no-retrieval`'s own pipeline
+    #: sets, because the null-retrieval branch is a deliberate choice to answer from
+    #: parametric memory (Roberts, Raffel & Shazeer 2020), not a retrieval failure.
+    ANSWER_FROM_MEMORY = "answer_from_memory"
+
+
+class CitedAnswerConfig(BaseModel):
+    """`CitedAnswer`'s `with:` config. Every field has a default, per this pack's own rule."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    prompt: str = Field(default=ANSWER_WITH_CITATIONS_NAME, min_length=1)
+    role: str = Field(default="generate", min_length=1)
+    max_passages: int = Field(default=8, ge=1)
+    #: Presents the offered evidence grouped under the retriever that found it, rather
+    #: than as one flat numbered list — useful once a fan-out or hybrid pipeline feeds
+    #: this stage passages `Passage.retrieved_by` disagrees about.
+    group_by_retriever: bool = False
+    when_no_evidence: WhenNoEvidence = WhenNoEvidence.REFUSE
+
+
+class CitedAnswer:
+    """Turns packed, labelled evidence into a cited answer. Satisfies `contract.Generator`
+    structurally.
+
+    `cost_bound = (0, 1)` — zero when evidence is empty and `when_no_evidence=REFUSE`,
+    because `run` returns before resolving anything; one otherwise, the same arithmetic
+    `weft_retrieve.rerank.LlmRerank` states for its own single-call ceiling.
+    """
+
+    config_model: ClassVar[type[CitedAnswerConfig]] = CitedAnswerConfig
+    cost_bound: ClassVar[tuple[int, int]] = (0, 1)
+
+    def __init__(self, config: CitedAnswerConfig | None = None) -> None:
+        self._config = config if config is not None else CitedAnswerConfig()
+
+    async def run(self, payload: Passages, ctx: Context) -> Outcome[Answer]:
+        """Ask under `origin` alone, never a derived query — `QuerySet.origin`'s own rule,
+        applied at the last stage on the query path rather than only the first.
+        """
+        if not payload.passages:
+            if self._config.when_no_evidence is WhenNoEvidence.REFUSE:
+                return Produced(
+                    value=Answer(
+                        origin=payload.origin,
+                        text="",
+                        citations=(),
+                        used=(),
+                        stance=AnswerStance.NOT_IN_CORPUS,
+                        answered_by=NAME,
+                    )
+                )
+            offered: tuple[Passage, ...] = ()
+        else:
+            offered = await _resolved_to_citable(
+                payload.passages[: self._config.max_passages], ctx=ctx
+            )
+
+        llm = ctx.require(LLM)
+        lookup = ctx.require(StageLookup)
+        prompt = await lookup.build_capability(Prompt, self._config.prompt)
+        request = AnswerWithCitationsRequest(
+            question=payload.origin.text,
+            passages=_offer(offered, group_by_retriever=self._config.group_by_retriever),
+        )
+        rendered = await prompt.render(request, ctx)
+        if not isinstance(rendered, Produced):
+            # A prompt with nothing to ask is relayed exactly as it answered — the same
+            # rule `weft_prompts.cascade.execute` and `weft_retrieve.rerank` both take.
+            return rendered
+
+        completion = await llm.complete(rendered.value, role=self._config.role, ctx=ctx)
+        if not isinstance(completion, Produced):
+            return completion
+        text = completion.value.text
+
+        citations = await _citations_for(offered, text=text, ctx=ctx)
+        return Produced(
+            value=Answer(
+                origin=payload.origin,
+                text=text,
+                citations=citations,
+                used=offered,
+                stance=AnswerStance.ANSWERED,
+                answered_by=NAME,
+            )
+        )
+
+
+def _offer(passages: tuple[Passage, ...], *, group_by_retriever: bool) -> str:
+    """The offered evidence as one string, numbered by each passage's own `label`.
+
+    Never a re-derived index — see `weft_generate.prompts`' module docstring for why that
+    is the one thing this function must not do.
+    """
+    if not passages:
+        return ""
+    if not group_by_retriever:
+        return "\n\n".join(f"[{passage.label}] {passage.node.content}" for passage in passages)
+    groups: dict[str, list[Passage]] = {}
+    for passage in passages:
+        groups.setdefault(passage.retrieved_by, []).append(passage)
+    blocks = [
+        f"From {retriever}:\n"
+        + "\n\n".join(f"[{passage.label}] {passage.node.content}" for passage in group)
+        for retriever, group in sorted(groups.items())
+    ]
+    return "\n\n".join(blocks)
+
+
+async def _resolved_to_citable(
+    offered: tuple[Passage, ...], *, ctx: Context
+) -> tuple[Passage, ...]:
+    """`offered`, with every representation's own node substituted for the one it stands in
+    for — see the module docstring for why this runs once, here, rather than inside
+    `_citations_for` alone. `rank`, `retrieved_by` and `label` are untouched; only which
+    node the passage carries changes, via a fresh `Scored` around the resolved node and the
+    passage's own original `score`.
+    """
+    if not offered:
+        return offered
+    store = ctx.require(NodeStore)
+    resolved = await citable_nodes((passage.node for passage in offered), store=store)
+    return tuple(
+        passage
+        if resolved[passage.node.id] is passage.node
+        else Passage(
+            scored=Scored(value=resolved[passage.node.id], score=passage.score),
+            rank=passage.rank,
+            retrieved_by=passage.retrieved_by,
+            label=passage.label,
+        )
+        for passage in offered
+    )
+
+
+async def _citations_for(
+    offered: tuple[Passage, ...], *, text: str, ctx: Context
+) -> tuple[Citation, ...]:
+    """One `Citation` per offered passage whose own bracketed label appears in `text`.
+
+    A literal substring search, not a regex over prose: the label searched for is the
+    exact string shown to the model, so there is nothing for a language-specific pattern
+    to get right or wrong that this search does not already get right by construction.
+    `offered` has already been resolved to citable nodes by `run`, so `passage.node` here
+    is always the node a `Citation` should name.
+    """
+    cited = [
+        (passage, _source_id(passage.node)) for passage in offered if f"[{passage.label}]" in text
+    ]
+    store = ctx.require(NodeStore)
+    uris = await _uris_for((source_id for _, source_id in cited), store=store)
+    return tuple(
+        Citation(
+            marker=passage.label,
+            node_id=passage.node.id,
+            source_id=source_id,
+            uri=uris.get(source_id, "") if source_id is not None else "",
+            page=page_for(passage.node),
+        )
+        for passage, source_id in cited
+    )
+
+
+async def _uris_for(
+    source_ids: Iterable[SourceId | None], *, store: NodeStore
+) -> dict[SourceId, str]:
+    """Every distinct known source's `uri`, looked up once each rather than once per citation."""
+    wanted = {source_id for source_id in source_ids if source_id is not None}
+    uris: dict[SourceId, str] = {}
+    for source_id in wanted:
+        record = await store.get_source(source_id)
+        uris[source_id] = record.uri if record is not None else ""
+    return uris
+
+
+def _source_id(node: Node) -> SourceId | None:
+    """`node`'s one source, or `None` when it has none or more than one to choose from.
+
+    Zero is `Node.synthetic`'s legitimate root case — `Citation.source_id`'s own docstring.
+    More than one is a summary node (`Node.combine`): naming one of several documents as
+    *the* source would be a citation that misattributes a claim to a document it might not
+    actually rest on, which is worse than a citation that says only "this is a summary".
+    """
+    sources = node.lineage.sources
+    return next(iter(sources)) if len(sources) == 1 else None

weft_generate-1.0.0/src/weft_generate/contract.py

@@ -0,0 +1,58 @@
+"""The `Generator` contract — published here, never by the kernel.
+
+Task **2.4**. One `Stage` subtype, closing the query path: `Stage[Passages, Answer]`,
+domain types on both sides, and the last seam `weft_kernel.runner._check_composition`
+checks before a run produces something a reader sees.
+
+**Why this is a separate distribution from `weft-retrieve`.** G3 settled that discovery is
+*eager* — installed means `register()` runs on every registry-touching command — so a
+retrieval-only deployment (rerank-and-return enterprise search) must be able to *not
+install* a generator, its prompts and its citation machinery rather than merely not name
+them. `Answer` is also the only Phase 2 type an embedding host application consumes, and
+a host that wants it should not thereby acquire every retrieval technique this project
+ships.
+
+`Passages` and `Query` come from `weft-retrieve`, which this pack depends on: dependencies
+flow one way along the pipeline and never back. See `weft_generate.payload`'s module
+docstring for why `Answer` is published *here* even though a retrieval-shaped technique
+wants it.
+
+The emptiness rule, the `applies_to` note and the `publishes_property_vocabulary`
+declining argument in `weft_retrieve.contract`'s module docstring all apply verbatim to
+this contract; they are stated there once rather than copied.
+"""
+
+from typing import TYPE_CHECKING, ClassVar, Protocol, runtime_checkable
+
+from weft_generate.payload import Answer
+from weft_kernel.context import Context
+from weft_kernel.payload import Outcome
+from weft_kernel.runner import Stage
+from weft_retrieve.payload import Passages
+
+#: Fitness function 6's subject for this contract — see the module docstring.
+GENERATE_CONTRACT_VERSION = "1.0.0"
+
+
+@runtime_checkable
+class Generator(Stage[Passages, Answer], Protocol):
+    """Turns packed, labelled evidence into an answer that cites it.
+
+    Taking `Passages` rather than a `Ranking` is what makes task 2.9 mechanical: the
+    citation labels are already assigned and final by the time a generator sees them, so
+    `Answer`'s own validator can refuse a marker that resolves to nothing. A generator
+    that decides the evidence does not answer the question returns
+    `Answer(stance=NOT_IN_CORPUS)` — `Produced`, with an honest claim inside it — never
+    `NothingToProduce`, which would stop the pipeline and leave the caller with no answer
+    at all where `09` §4's V2 requires one.
+    """
+
+    if TYPE_CHECKING:
+        #: Declared only for a type checker, assigned for real after the class body, so it
+        #: never joins `__protocol_attrs__`.
+        version: ClassVar[str]
+
+    async def run(self, payload: Passages, ctx: Context) -> Outcome[Answer]: ...
+
+
+Generator.version = GENERATE_CONTRACT_VERSION