agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/config.py

@@ -0,0 +1,259 @@
+"""Typed reader for ``ckg.yaml`` — this agent's *own* engine config (NOT
+the framework's ``agentforge.yaml``, which has a strict validator).
+
+Unlike the framework file, ours is intentionally lenient: unknown keys are
+ignored (``extra='ignore'``) so a config written for a later feature still
+loads for an earlier one. The ``store:`` (feat-003) and ``ingest:``
+(feat-002) blocks are modelled today; chunking/retrieve/… sections gain
+their own models as those features land.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, ClassVar, Self
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+# Default directories excluded from ingestion (mirrors ckg.yaml's ingest.exclude).
+DEFAULT_EXCLUDES = [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/dist/**",
+    "**/.git/**",
+    "**/.ckg/**",
+]
+
+
+def _read_block[T: _Block](model: type[T], key: str, ckg_yaml: str | Path | None) -> T:
+    """Parse one top-level block of ckg.yaml into ``model``. Missing file or
+    ``None`` → defaults; malformed YAML / block → ``StoreConfigError``."""
+    # Imported lazily to avoid an import cycle (store.facade imports this).
+    from agentforge_graph.store.errors import StoreConfigError
+
+    if ckg_yaml is None:
+        return model()
+    p = Path(ckg_yaml)
+    if not p.exists():
+        return model()
+    try:
+        data = yaml.safe_load(p.read_text()) or {}
+    except yaml.YAMLError as exc:
+        raise StoreConfigError(f"could not parse {p}: {exc}") from exc
+    try:
+        return model.model_validate(data.get(key) or {})
+    except ValidationError as exc:
+        raise StoreConfigError(f"invalid {key} config in {p}: {exc}") from exc
+
+
+class _Block(BaseModel):
+    """Base for a ckg.yaml section that knows its top-level key."""
+
+    KEY: ClassVar[str] = ""
+
+    @classmethod
+    def load(cls, ckg_yaml: str | Path | None = None) -> Self:
+        return _read_block(cls, cls.KEY, ckg_yaml)
+
+
+class GraphCfg(BaseModel):
+    driver: str = "kuzu"
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class VectorCfg(BaseModel):
+    driver: str = "lancedb"
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class StoreConfig(_Block):
+    """The ``store:`` block of ckg.yaml (ADR-0006)."""
+
+    KEY: ClassVar[str] = "store"
+    path: str = ".ckg"
+    graph: GraphCfg = Field(default_factory=GraphCfg)
+    vectors: VectorCfg = Field(default_factory=VectorCfg)
+
+
+class IngestConfig(_Block):
+    """The ``ingest:`` block of ckg.yaml (feat-002 / ADR-0009)."""
+
+    KEY: ClassVar[str] = "ingest"
+    languages: str | list[str] = "auto"  # "auto" or an explicit list of pack names
+    exclude: list[str] = Field(default_factory=lambda: list(DEFAULT_EXCLUDES))
+    max_file_kb: int = 512
+    lsp_assist: bool = False  # opt-in resolution escalation (Tier B); inert at 0.1
+    incremental: bool = True  # feat-004: re-index only the diff when a prior index exists
+    resolve_scope_hops: int = 1  # import-graph hops to re-resolve around a changed file
+
+
+class ChunkingConfig(_Block):
+    """The ``chunking:`` block of ckg.yaml (feat-005 / ADR-0007)."""
+
+    KEY: ClassVar[str] = "chunking"
+    max_tokens: int = 512
+    min_tokens: int = 64
+
+
+class EmbedConfig(_Block):
+    """The ``embed:`` block of ckg.yaml (feat-005). Default driver is
+    ``bedrock`` (Cohere embed-v4); tests/CI use ``fake``."""
+
+    KEY: ClassVar[str] = "embed"
+    # ENH-003: bedrock | fake | openai | <entry-point>. `openai` also covers
+    # OpenAI-compatible local servers via `base_url` (Ollama/vLLM/LM Studio).
+    driver: str = "bedrock"
+    model: str = "cohere.embed-v4:0"
+    region: str = "us-east-1"
+    dim: int = 1024
+    batch_size: int = 96
+    assume_role_arn: str = ""  # set for CI; empty = default AWS credential chain
+    base_url: str = ""  # ENH-003: OpenAI-compatible endpoint (empty = provider default)
+    api_key_env: str = ""  # ENH-003: env var holding the API key (empty = provider default)
+
+
+def _default_edge_weights() -> dict[str, float]:
+    # By provenance: resolved facts outrank parsed; llm is second-class (ADR-0004).
+    return {"resolved": 1.0, "manual": 0.8, "parsed": 0.5, "llm": 0.3}
+
+
+class RetrieveConfig(_Block):
+    """The ``retrieve:`` block of ckg.yaml (feat-006 / ADR-0008)."""
+
+    KEY: ClassVar[str] = "retrieve"
+    k: int = 8
+    depth: int = 1
+    decay: float = 0.6
+    fanout_cap: int = 25  # max neighbors expanded per hop (overflow noted, not silent)
+    # ENH-009: off (default) | lexical | cross_encoder. `lexical` is a
+    # deterministic subtoken blend (helps keyword/symbol-naming queries, mixed on
+    # prose). `cross_encoder` is a real semantic re-score via sentence-transformers
+    # (the `rerank` extra; lazy-loaded). Both opt-in (measure, don't blind-flip).
+    rerank: str = "off"
+    rerank_weight: float = 0.5  # final = (1-w)*base + w*signal (overlap | σ(cross))
+    rerank_model: str = ""  # cross_encoder model id (empty = a small ms-marco default)
+    edge_weights: dict[str, float] = Field(default_factory=_default_edge_weights)
+    # feat-010: scale ADR/doc (`source_type: doc`) vector hits so code outranks
+    # equally-similar prose by default, mitigating doc-volume dilution. Neutralised
+    # (→ 1.0) when the query smells architectural (decision/why/design/…).
+    doc_weight: float = 0.7
+
+    @field_validator("rerank", mode="before")
+    @classmethod
+    def _coerce_rerank(cls, v: Any) -> Any:
+        # YAML 1.1 parses bare `off`/`on` as booleans, so `rerank: off` (as shipped
+        # in ckg.yaml) arrives as False and would fail string validation. Map the
+        # booleans back to the canonical modes: off -> disabled, on -> the lexical
+        # reranker (the only enabled mode).
+        if isinstance(v, bool):
+            return "lexical" if v else "off"
+        return v
+
+
+class RepoMapConfig(_Block):
+    """The ``repomap:`` block of ckg.yaml (feat-007)."""
+
+    KEY: ClassVar[str] = "repomap"
+    default_budget: int = 2000
+    damping: float = 0.85
+    kinds: list[str] = Field(default_factory=lambda: ["Class", "Function", "Method"])
+    edge_weights: dict[str, float] = Field(default_factory=_default_edge_weights)
+    # ENH-007: down-weight clearly-private symbols (leading-underscore names or
+    # `_`-prefixed modules) so the map surfaces the public API first. A weight,
+    # not a filter: private hubs can still appear when genuinely central. In
+    # [0, 1]; 0.0 = pure centrality, higher demotes private harder. Private
+    # symbols are multiplied by (1 - public_bias).
+    public_bias: float = 0.5
+
+
+class ServeConfig(_Block):
+    """The ``serve:`` block of ckg.yaml (feat-008 — MCP server + guardrails)."""
+
+    KEY: ClassVar[str] = "serve"
+    transport: str = "stdio"  # feat-008: stdio | http (streamable-HTTP at /mcp)
+    host: str = "127.0.0.1"  # http transport bind host
+    port: int = 8765  # http transport port
+    # ENH-005: bearer token for the HTTP transport (empty = no auth, localhost
+    # default). Prefer $CKG_HTTP_AUTH_TOKEN over putting the secret in ckg.yaml.
+    http_auth_token: str = ""
+    max_depth: int = 3
+    max_k: int = 50
+    response_token_cap: int = 6000
+    refresh_on_call: bool = False
+
+
+class FrameworksConfig(_Block):
+    """The ``frameworks:`` block of ckg.yaml (feat-011)."""
+
+    KEY: ClassVar[str] = "frameworks"
+    # "auto" → detect per repo; "off" → none; or an explicit list of pack names.
+    enabled: str | list[str] = "auto"
+    packs: list[str] = Field(default_factory=list)  # force-enable, e.g. ["fastapi"]
+
+
+class EnrichConfig(_Block):
+    """The ``enrich:`` block of ckg.yaml (feat-012 — LLM enrichment).
+
+    Claude runs on **AWS Bedrock** (default) or the **direct Anthropic API**
+    (``provider: anthropic`` — ENH-003 phase 2, the non-AWS path). Never runs
+    implicitly — only ``ckg enrich`` / ``CodeGraph.enrich()``."""
+
+    KEY: ClassVar[str] = "enrich"
+    enabled: bool = True
+    # ENH-003: provider for BOTH judge + summarizer. bedrock | anthropic |
+    # scripted | <entry-point>. `anthropic` = direct Anthropic API (needs
+    # ANTHROPIC_API_KEY); `scripted` is the credential-free deterministic one.
+    provider: str = "bedrock"
+    # Default is a Bedrock inference-profile id (the `us.` prefix). The
+    # `anthropic` provider normalises it to the bare API id automatically.
+    model: str = "us.anthropic.claude-haiku-4-5-20251001-v1:0"
+    region: str = "us-east-1"
+    assume_role_arn: str = ""  # set for CI; empty = default AWS credential chain
+    base_url: str = ""  # ENH-003: Anthropic-compatible endpoint (empty = default)
+    api_key_env: str = ""  # ENH-003: env var holding the API key (empty = ANTHROPIC_API_KEY)
+    budget_usd: float = 2.0  # per-run LLM judge cap (breaker)
+    confidence_floor: float = 0.7  # drop tags below this
+    taxonomy: str = "v1"
+    patterns_recall: str = "conservative"  # ENH-001: conservative | broad
+    concurrency: int = 6  # ENH-002: in-flight LLM calls per enrich run
+    summary_max_words: int = 120  # feat-012 summaries
+    summary_levels: list[str] = Field(default_factory=lambda: ["file", "repo"])
+
+
+def _default_adr_globs() -> list[str]:
+    return ["docs/adr/**/*.md", "docs/decisions/**/*.md"]
+
+
+class KnowledgeConfig(_Block):
+    """The ``knowledge:`` block of ckg.yaml (feat-010 — ADR & docs ingestion).
+
+    Reads ``enabled`` + ``adr_globs`` (deterministic pass) and ``infer_budget_usd``
+    (the ``ckg enrich --decisions`` LLM matcher's USD cap). ``doc_globs``/
+    ``commit_messages`` are declared for follow-ups; ``infer_governs`` is the
+    default for the LLM pass (the CLI flag runs it on demand regardless)."""
+
+    KEY: ClassVar[str] = "knowledge"
+    enabled: bool = True
+    adr_globs: list[str] = Field(default_factory=_default_adr_globs)
+    doc_globs: list[str] = Field(default_factory=list)  # general docs → DocChunks+DESCRIBES
+    commit_messages: bool = False  # ingest conventional/issue-ref commit messages
+    commit_messages_limit: int = 50  # how many recent commits to scan
+    infer_governs: bool = False  # default for the LLM matcher (CLI flag overrides)
+    infer_budget_usd: float = 1.0  # USD cap for the infer_governs pass
+
+
+class TemporalConfig(_Block):
+    """The ``temporal:`` block of ckg.yaml (feat-009 — git-evolution layer).
+
+    **Opt-in (default off).** When on (and the source is a git repo), the
+    feat-004 refresh records symbol lifecycle into a ``.ckg/temporal.db``
+    sidecar — the basis for history / changed-since / as-of and churn ranking
+    signals. Off means delete-on-refresh, exactly as before. See
+    ``docs/design/design-009-temporal-evolution-layer.md``."""
+
+    KEY: ClassVar[str] = "temporal"
+    enabled: bool = False
+    history_backfill: int = 0  # commits to replay at first index (chunk 4)
+    retention_commits: int = 1000  # prune closed events beyond this horizon (chunk 5)
+    rename_detection: str = "file"  # file (exact git renames) | signature (intra-file, chunk 6)

agentforge_graph/core/__init__.py

@@ -0,0 +1,54 @@
+"""agentforge_graph.core — the locked schema and contracts.
+
+The stable surface every other feature plugs into: typed node/edge
+kinds, value types (with provenance + symbol-ID validation enforced at
+construction), the symbol-ID grammar, and the ABCs. This package imports
+nothing from ``agentforge`` (ADR-0001) — it is the deterministic engine
+core and is usable standalone.
+"""
+
+from __future__ import annotations
+
+from .contracts import Direction, Enricher, Extractor, GraphStore, VectorStore
+from .kinds import EdgeKind, NodeKind
+from .models import (
+    Edge,
+    Embedded,
+    FileSubgraph,
+    GraphQuery,
+    Node,
+    QueryResult,
+    ScoredRef,
+    SourceFile,
+)
+from .provenance import Provenance, Source
+from .symbols import Descriptor, ParsedSymbol, SymbolID, normalize_path
+
+__all__ = [
+    # kinds
+    "NodeKind",
+    "EdgeKind",
+    # provenance
+    "Provenance",
+    "Source",
+    # symbols
+    "SymbolID",
+    "ParsedSymbol",
+    "Descriptor",
+    "normalize_path",
+    # models
+    "Node",
+    "Edge",
+    "FileSubgraph",
+    "SourceFile",
+    "GraphQuery",
+    "QueryResult",
+    "Embedded",
+    "ScoredRef",
+    # contracts
+    "Extractor",
+    "GraphStore",
+    "VectorStore",
+    "Enricher",
+    "Direction",
+]

agentforge_graph/core/conformance.py

@@ -0,0 +1,270 @@
+"""Reusable conformance suites for the core ABCs.
+
+A feat-003 storage adapter or a feat-002 extractor proves it honours
+the contract by subclassing the matching ``*Conformance`` base class and
+providing the required fixture. The same suite runs against every
+implementer, so they're interchangeable. Pytest-free at import time (the
+async test methods are collected by pytest-asyncio in the *test* package;
+this module never imports pytest, keeping the core import light).
+"""
+
+from __future__ import annotations
+
+from .contracts import Extractor, GraphStore, VectorStore
+from .kinds import EdgeKind, NodeKind
+from .models import Edge, Embedded, FileSubgraph, GraphQuery, Node, SourceFile
+from .provenance import Provenance
+from .symbols import Descriptor, SymbolID
+
+_LANG = "py"
+_REPO = "sample"
+_PATH = "src/app/auth.py"
+
+
+def make_sample_subgraph(commit: str = "c0") -> FileSubgraph:
+    """A tiny but valid subgraph: File ▸ Class ▸ Method, with CONTAINS."""
+    prov = Provenance.parsed("conformance", commit)
+    file_id = SymbolID.for_symbol(_LANG, _REPO, _PATH, "")
+    class_id = SymbolID.for_symbol(_LANG, _REPO, _PATH, Descriptor.type("Auth"))
+    method_id = SymbolID.for_symbol(
+        _LANG, _REPO, _PATH, Descriptor.type("Auth") + Descriptor.method("login")
+    )
+    nodes = [
+        Node(id=file_id, kind=NodeKind.FILE, name="auth.py", provenance=prov),
+        Node(id=class_id, kind=NodeKind.CLASS, name="Auth", span=(1, 20), provenance=prov),
+        Node(id=method_id, kind=NodeKind.METHOD, name="login", span=(2, 10), provenance=prov),
+    ]
+    edges = [
+        Edge(src=file_id, dst=class_id, kind=EdgeKind.CONTAINS, provenance=prov),
+        Edge(src=class_id, dst=method_id, kind=EdgeKind.CONTAINS, provenance=prov),
+    ]
+    return FileSubgraph(path=_PATH, content_hash=f"hash-{commit}", nodes=nodes, edges=edges)
+
+
+class GraphStoreConformance:
+    """Subclass in a feat-003 adapter; provide an async ``store`` fixture
+    yielding a fresh, empty ``GraphStore``."""
+
+    async def test_upsert_then_get(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        got = await store.get(sg.nodes[0].id)
+        assert got is not None
+        assert got.id == sg.nodes[0].id
+
+    async def test_reupsert_is_idempotent(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        await store.upsert(sg)
+        res = await store.query(GraphQuery(path_prefix="src/app"))
+        assert len(res.nodes) == len(sg.nodes)
+
+    async def test_delete_file_removes_nodes(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        await store.delete_file(sg.path)
+        assert await store.get(sg.nodes[0].id) is None
+
+    async def test_enrichment_survives_file_reupsert(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        target = sg.nodes[1].id  # the class
+        summary_id = SymbolID.for_symbol(_LANG, _REPO, _PATH, "Auth#summary.")
+        llm = Provenance.llm("enricher", 0.9)
+        await store.add(
+            [
+                Node(id=summary_id, kind=NodeKind.SUMMARY, name="summary", provenance=llm),
+                Edge(src=summary_id, dst=target, kind=EdgeKind.SUMMARIZES, provenance=llm),
+            ]
+        )
+        # the file changes and is re-indexed; the enrichment must survive
+        await store.upsert(make_sample_subgraph(commit="c1"))
+        assert await store.get(summary_id) is not None
+
+    async def test_set_attrs_merges_and_keeps_file_ownership(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        target = sg.nodes[1].id  # the class
+        await store.set_attrs(target, {"churn_90d": 7})
+        await store.set_attrs(target, {"introduced": "abc123"})  # second merge
+        got = await store.get(target)
+        assert got is not None
+        assert got.attrs.get("churn_90d") == 7  # first patch survives the second
+        assert got.attrs.get("introduced") == "abc123"
+        # the patched node is still file-owned: delete_file removes it (the
+        # merge must not have clobbered origin_path, feat-009).
+        await store.delete_file(sg.path)
+        assert await store.get(target) is None
+        # patching an absent node is a no-op, not an error
+        await store.set_attrs(target, {"churn_90d": 1})
+        assert await store.get(target) is None
+
+    async def test_reserved_kind_preserved(self, store: GraphStore) -> None:
+        route_id = SymbolID.for_symbol(_LANG, _REPO, "src/app/api.py", "route(GET_x).")
+        await store.add(
+            [
+                Node(
+                    id=route_id,
+                    kind=NodeKind.ROUTE,
+                    name="GET /x",
+                    provenance=Provenance.parsed("conformance"),
+                )
+            ]
+        )
+        got = await store.get(route_id)
+        assert got is not None
+        assert got.kind is NodeKind.ROUTE
+
+    async def test_neighbors_walks_contains(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        file_id, class_id, method_id = (n.id for n in sg.nodes)
+        one_hop = {n.id for n in await store.neighbors(file_id, [EdgeKind.CONTAINS], depth=1)}
+        assert class_id in one_hop
+        two_hop = {n.id for n in await store.neighbors(file_id, [EdgeKind.CONTAINS], depth=2)}
+        assert method_id in two_hop
+
+    async def test_clear_resolved_invalidates_and_gcs_packages(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        caller = sg.nodes[2].id  # the method, in _PATH
+        # A resolved CALLS edge to a parsed symbol + a resolved IMPORTS edge to
+        # an external package stub, both owned by _PATH (feat-004 tagging).
+        pkg_id = SymbolID.for_symbol(_LANG, _REPO, "<external>", "react/namespace.")
+        resolved = Provenance.resolved("resolver")
+        await store.add(
+            [
+                Node(id=pkg_id, kind=NodeKind.PACKAGE, name="react", provenance=resolved),
+                Edge(
+                    src=caller,
+                    dst=sg.nodes[1].id,
+                    kind=EdgeKind.CALLS,
+                    provenance=resolved,
+                    origin_path=_PATH,
+                ),
+                Edge(
+                    src=SymbolID.for_symbol(_LANG, _REPO, _PATH, ""),
+                    dst=pkg_id,
+                    kind=EdgeKind.IMPORTS,
+                    provenance=resolved,
+                    origin_path=_PATH,
+                ),
+            ]
+        )
+        assert await store.get(pkg_id) is not None
+        await store.clear_resolved([_PATH])
+        # resolved edges gone, the now-orphan package GC'd, parsed nodes intact
+        assert await store.adjacent(caller, [EdgeKind.CALLS], "out") == []
+        assert await store.get(pkg_id) is None
+        assert await store.get(sg.nodes[1].id) is not None  # the class survives
+
+    async def test_clear_outgoing_removes_kind_from_sources(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()
+        await store.upsert(sg)
+        cls = sg.nodes[1].id
+        tag_id = SymbolID.for_symbol(_LANG, _REPO, "<taxonomy>", "Repository.")
+        llm = Provenance.llm("pattern-tags", 0.9)
+        await store.add(
+            [
+                Node(id=tag_id, kind=NodeKind.PATTERN_TAG, name="Repository", provenance=llm),
+                Edge(src=cls, dst=tag_id, kind=EdgeKind.TAGGED, provenance=llm),
+            ]
+        )
+        assert await store.adjacent(cls, [EdgeKind.TAGGED], "out")
+        await store.clear_outgoing([cls], EdgeKind.TAGGED)
+        assert await store.adjacent(cls, [EdgeKind.TAGGED], "out") == []
+        # the CONTAINS edge from the same source is untouched (kind-scoped)
+        assert await store.adjacent(cls, [EdgeKind.CONTAINS], "out")
+
+    async def test_adjacent_directed(self, store: GraphStore) -> None:
+        sg = make_sample_subgraph()  # File -CONTAINS-> Class -CONTAINS-> Method
+        await store.upsert(sg)
+        file_id, class_id, method_id = (n.id for n in sg.nodes)
+        out = await store.adjacent(class_id, [EdgeKind.CONTAINS], "out")
+        assert [(e.src, e.dst) for e in out] == [(class_id, method_id)]
+        incoming = await store.adjacent(class_id, [EdgeKind.CONTAINS], "in")
+        assert [(e.src, e.dst) for e in incoming] == [(file_id, class_id)]
+        both = await store.adjacent(class_id, [EdgeKind.CONTAINS], "both")
+        assert {(e.src, e.dst) for e in both} == {(file_id, class_id), (class_id, method_id)}
+        # kind filter excludes non-matching edges
+        assert await store.adjacent(class_id, [EdgeKind.CALLS], "both") == []
+
+
+# Distinct kinds so a kind-filter discriminates; refs are valid SymbolIDs.
+_SAMPLE_KINDS = (NodeKind.CHUNK, NodeKind.DOC_CHUNK, NodeKind.SUMMARY)
+
+
+def make_sample_embeddings(dim: int = 8) -> list[Embedded]:
+    """Three tiny one-hot vectors of dimension ``dim`` over distinct kinds,
+    for exercising a ``VectorStore`` without a real embedder."""
+    base = SymbolID.for_symbol(_LANG, _REPO, _PATH, Descriptor.type("Auth"))
+    return [
+        Embedded(
+            ref=f"{base}chunk{i}.",
+            vector=[1.0 if j == i else 0.0 for j in range(dim)],
+            kind=_SAMPLE_KINDS[i],
+            attrs={"ordinal": i},
+        )
+        for i in range(3)
+    ]
+
+
+class VectorStoreConformance:
+    """Subclass in a feat-003 vector adapter; provide an async ``vectors``
+    fixture yielding a fresh, empty ``VectorStore``.
+
+    The ``filter`` contract targets first-class columns (``ref``, ``kind``,
+    ``path``) — the portable subset every backend can honour — not nested
+    ``attrs`` keys."""
+
+    async def test_upsert_then_search_finds_nearest(self, vectors: VectorStore) -> None:
+        items = make_sample_embeddings()
+        await vectors.upsert(items)
+        hits = await vectors.search(items[1].vector, k=1)
+        assert hits
+        assert hits[0].ref == items[1].ref
+
+    async def test_reupsert_is_idempotent(self, vectors: VectorStore) -> None:
+        items = make_sample_embeddings()
+        await vectors.upsert(items)
+        await vectors.upsert(items)
+        hits = await vectors.search(items[0].vector, k=10)
+        assert len({h.ref for h in hits}) == len(items)
+
+    async def test_search_respects_k(self, vectors: VectorStore) -> None:
+        items = make_sample_embeddings()
+        await vectors.upsert(items)
+        hits = await vectors.search(items[0].vector, k=2)
+        assert len(hits) <= 2
+
+    async def test_filter_constrains_results(self, vectors: VectorStore) -> None:
+        items = make_sample_embeddings()
+        await vectors.upsert(items)
+        hits = await vectors.search(items[0].vector, k=10, filter={"kind": NodeKind.CHUNK.value})
+        assert hits
+        assert all(h.ref == items[0].ref for h in hits)
+
+    async def test_delete_where_removes(self, vectors: VectorStore) -> None:
+        items = make_sample_embeddings()
+        await vectors.upsert(items)
+        await vectors.delete_where({"kind": NodeKind.DOC_CHUNK.value})
+        hits = await vectors.search(items[1].vector, k=10)
+        assert items[1].ref not in {h.ref for h in hits}
+
+
+class ExtractorConformance:
+    """Subclass in a feat-002/011 pack; provide ``extractor`` and
+    ``sample_file`` fixtures."""
+
+    def test_output_is_valid_subgraph(self, extractor: Extractor, sample_file: SourceFile) -> None:
+        sg = extractor.extract(sample_file)
+        assert isinstance(sg, FileSubgraph)
+        assert sg.path
+        assert sg.content_hash
+
+    def test_extraction_is_deterministic(
+        self, extractor: Extractor, sample_file: SourceFile
+    ) -> None:
+        first = extractor.extract(sample_file)
+        second = extractor.extract(sample_file)
+        assert first.model_dump() == second.model_dump()