sourcebound 1.2.1__py3-none-any.whl

clean_docs/phrasing.py

@@ -0,0 +1,448 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+import yaml
+
+from clean_docs.errors import ConfigurationError
+from clean_docs.execution import run_bounded_command
+from clean_docs.inventory import InventoryItem
+from clean_docs.regions import atomic_write
+from clean_docs.standard import load_default_pack
+from clean_docs.write_gate import SECRET_RULES, redact_secrets
+
+
+INJECTION_RULES = (
+    re.compile(r"\bignore (?:all |any )?(?:previous|prior) instructions?\b", re.I),
+    re.compile(r"\b(?:reveal|disclose|print|return) (?:the )?(?:system prompt|secrets?)\b", re.I),
+    re.compile(r"\b(?:override|change|remove|modify) (?:the )?(?:system|required findings?|gate results?)\b", re.I),
+)
+SKIP_PARTS = {".git", ".venv", "node_modules", "docs/archive"}
+MAX_CONTEXT_BYTES = 32_000
+MAX_FILE_BYTES = 8_000
+MAX_PROVIDER_OUTPUT_BYTES = 1_000_000
+MAX_PROVIDER_INPUT_BYTES = 1_000_000
+DEFAULT_PROVIDER_TIMEOUT_SECONDS = 120
+MAX_PROVIDER_TIMEOUT_SECONDS = 3600
+MODEL_KEYS = {"adapter", "name", "response", "argv", "timeout_seconds", "env"}
+TEMPLATE_KINDS = {
+    "exposes": {
+        "api-endpoint", "api-symbol", "cli-command", "cli-option", "mcp-tool", "schema",
+    },
+    "provides": {
+        "api-endpoint", "api-symbol", "cli-command", "cli-option", "mcp-tool", "package",
+        "package-script", "schema", "test-runner", "test-suite",
+    },
+    "tests": {"test-runner", "test-suite"},
+}
+
+
+class PhrasingProvider(Protocol):
+    name: str
+
+    def complete(self, prompt: str) -> str: ...
+
+
+@dataclass
+class MockProvider:
+    response: str
+    name: str = "mock"
+    last_prompt: str = ""
+
+    def complete(self, prompt: str) -> str:
+        self.last_prompt = prompt
+        return self.response
+
+
+@dataclass
+class RecordedProvider(MockProvider):
+    name: str = "recorded"
+
+
+@dataclass
+class CommandPhrasingProvider:
+    """Run an explicitly configured init proposer without granting it write authority."""
+
+    argv: tuple[str, ...]
+    name: str
+    root: Path
+    timeout_seconds: int = DEFAULT_PROVIDER_TIMEOUT_SECONDS
+    env_names: tuple[str, ...] = ()
+    last_prompt: str | None = None
+    last_response: str | None = None
+    last_duration_seconds: float | None = None
+    last_prompt_bytes: int | None = None
+    last_response_bytes: int | None = None
+    last_error: str | None = None
+
+    @property
+    def configuration_sha256(self) -> str:
+        return hashlib.sha256(
+            json.dumps(
+                {
+                    "argv": self.argv,
+                    "timeout_seconds": self.timeout_seconds,
+                    "env": self.env_names,
+                },
+                sort_keys=True,
+                separators=(",", ":"),
+            ).encode()
+        ).hexdigest()
+
+    def complete(self, prompt: str) -> str:
+        self.last_prompt = prompt
+        request = prompt.encode()
+        environment = {"NO_COLOR": "1", "PATH": os.defpath}
+        for name in self.env_names:
+            value = os.environ.get(name)
+            if value is None:
+                raise ConfigurationError(f"init proposer environment variable is unset: {name}")
+            environment[name] = value
+        try:
+            result = run_bounded_command(
+                self.argv,
+                environment=environment,
+                input_bytes=request,
+                timeout_seconds=self.timeout_seconds,
+                max_input_bytes=MAX_PROVIDER_INPUT_BYTES,
+                max_output_bytes=MAX_PROVIDER_OUTPUT_BYTES,
+                prefix="sourcebound-init-proposer",
+            )
+        except ConfigurationError as exc:
+            self.last_error = str(exc)
+            raise
+        try:
+            response = result.stdout.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            self.last_error = "init proposer returned non-UTF-8 output"
+            raise ConfigurationError(self.last_error) from exc
+        self.last_response = response
+        self.last_duration_seconds = result.duration_seconds
+        self.last_prompt_bytes = len(request)
+        self.last_response_bytes = len(result.stdout)
+        return response
+
+
+def load_command_phrasing_provider(path: Path, root: Path) -> CommandPhrasingProvider:
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        raise ConfigurationError(f"cannot read init proposer config {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise ConfigurationError("init proposer config must be a mapping")
+    unknown = sorted(set(raw) - MODEL_KEYS)
+    if unknown:
+        raise ConfigurationError(
+            "init proposer config has unknown key(s): " + ", ".join(unknown)
+        )
+    if raw.get("adapter") != "command":
+        raise ConfigurationError("init proposer config.adapter must be command")
+    name = raw.get("name")
+    if not isinstance(name, str) or not name:
+        raise ConfigurationError("init proposer config.name must be non-empty")
+    if "response" in raw:
+        raise ConfigurationError(
+            "init proposer config.response is only valid for recorded adapters"
+        )
+    argv = raw.get("argv")
+    if (
+        not isinstance(argv, list)
+        or not argv
+        or not all(isinstance(value, str) and value for value in argv)
+    ):
+        raise ConfigurationError("init proposer config.argv must be a non-empty string list")
+    timeout_seconds = raw.get("timeout_seconds", DEFAULT_PROVIDER_TIMEOUT_SECONDS)
+    if (
+        not isinstance(timeout_seconds, int)
+        or isinstance(timeout_seconds, bool)
+        or not 1 <= timeout_seconds <= MAX_PROVIDER_TIMEOUT_SECONDS
+    ):
+        raise ConfigurationError(
+            "init proposer config.timeout_seconds must be an integer from 1 to "
+            f"{MAX_PROVIDER_TIMEOUT_SECONDS}"
+        )
+    env = raw.get("env", [])
+    if not isinstance(env, list) or not all(
+        isinstance(value, str) and value and value.isidentifier() for value in env
+    ) or len(set(env)) != len(env):
+        raise ConfigurationError("init proposer config.env must be unique environment variable names")
+    return CommandPhrasingProvider(tuple(argv), name, root, timeout_seconds, tuple(env))
+
+
+def write_command_proposer_transcript(
+    root: Path,
+    path: Path,
+    provider: CommandPhrasingProvider,
+    *,
+    state: str,
+    outcome: str,
+    detail: str,
+    record: ModelRecord | None = None,
+) -> None:
+    target = validate_command_proposer_transcript_path(root, path)
+    response = provider.last_response
+    redacted_response = redact_secrets(response)[0] if response is not None else None
+    candidates: list[dict[str, object]] = []
+    if response is not None:
+        try:
+            raw = json.loads(response)
+        except json.JSONDecodeError:
+            raw = None
+        if isinstance(raw, dict) and isinstance(raw.get("drafts"), list):
+            candidates = [
+                {
+                    "fact_id": item.get("fact_id") if isinstance(item, dict) else None,
+                    "template": item.get("template") if isinstance(item, dict) else None,
+                    "decision": "accepted" if outcome == "accept" else "rejected",
+                }
+                for item in raw["drafts"]
+            ]
+    payload: dict[str, Any] = {
+        "schema": "sourcebound.init-proposer-transcript.v1",
+        "state": state,
+        "outcome": outcome,
+        "detail": detail,
+        "provider": {
+            "name": provider.name,
+            "configuration_sha256": provider.configuration_sha256,
+            "timeout_seconds": provider.timeout_seconds,
+            "env_names": list(provider.env_names),
+            "granted_env_names": sorted({"PATH", "NO_COLOR", *provider.env_names}),
+        },
+        "cost": {
+            "prompt_bytes": provider.last_prompt_bytes,
+            "response_bytes": provider.last_response_bytes,
+            "duration_seconds": provider.last_duration_seconds,
+        },
+        "prompt": (
+            redact_secrets(provider.last_prompt)[0]
+            if provider.last_prompt is not None
+            else None
+        ),
+        "prompt_sha256": (
+            hashlib.sha256(provider.last_prompt.encode()).hexdigest()
+            if provider.last_prompt is not None
+            else None
+        ),
+        "response": redacted_response,
+        "response_sha256": (
+            hashlib.sha256(response.encode()).hexdigest() if response is not None else None
+        ),
+        "candidates": candidates,
+        "model_record": record.as_dict() if record is not None else None,
+    }
+    atomic_write(target, json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+
+def validate_command_proposer_transcript_path(root: Path, path: Path) -> Path:
+    if path.is_absolute() or ".." in path.parts:
+        raise ConfigurationError("init proposer transcript must stay inside the repository")
+    target = (root / path).resolve()
+    if not target.is_relative_to(root.resolve()):
+        raise ConfigurationError("init proposer transcript must stay inside the repository")
+    return target
+
+
+def prepare_command_proposer_transcript_path(root: Path, path: Path) -> Path:
+    """Prove the transcript target is writable without leaving repository state behind."""
+    target = validate_command_proposer_transcript_path(root, path)
+    if target.exists() and target.is_dir():
+        raise ConfigurationError("init proposer transcript path is a directory")
+    created: list[Path] = []
+    cursor = target.parent
+    missing: list[Path] = []
+    while not cursor.exists():
+        missing.append(cursor)
+        if cursor == root:
+            break
+        cursor = cursor.parent
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        for parent in reversed(missing):
+            if parent.exists():
+                created.append(parent)
+        descriptor, temporary = tempfile.mkstemp(prefix=f".{target.name}.", dir=target.parent)
+        os.close(descriptor)
+        Path(temporary).unlink()
+    except OSError as exc:
+        raise ConfigurationError(f"cannot write init proposer transcript {path}: {exc}") from exc
+    finally:
+        for parent in sorted(created, key=lambda item: len(item.parts), reverse=True):
+            try:
+                parent.rmdir()
+            except OSError:
+                pass
+    return target
+
+
+@dataclass(frozen=True)
+class GroundedDraft:
+    fact_id: str
+    template: str
+    text: str
+
+
+@dataclass(frozen=True)
+class ModelRecord:
+    provider: str
+    prompt_sha256: str
+    response_sha256: str
+    context_flags: tuple[str, ...]
+    drafts: tuple[GroundedDraft, ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "provider": self.provider,
+            "prompt_sha256": self.prompt_sha256,
+            "response_sha256": self.response_sha256,
+            "context_flags": list(self.context_flags),
+            "drafts": [asdict(draft) for draft in self.drafts],
+        }
+
+
+def _markdown_files(root: Path) -> list[Path]:
+    return sorted(
+        path
+        for path in root.rglob("*.md")
+        if path.is_file()
+        and not any(part in path.relative_to(root).as_posix() for part in SKIP_PARTS)
+    )
+
+
+def _sanitize(path: str, text: str) -> tuple[str, list[str]]:
+    lines: list[str] = []
+    flags: list[str] = []
+    for line_number, original in enumerate(text.splitlines(), start=1):
+        line = original
+        injection = any(rule.search(original) for rule in INJECTION_RULES)
+        if injection:
+            flags.append(f"prompt-injection:{path}:{line_number}")
+        for rule_id, pattern, _applies in SECRET_RULES:
+            if pattern.search(original):
+                flags.append(f"{rule_id}:{path}:{line_number}")
+                line = pattern.sub("[REDACTED]", line)
+        lines.append("[BLOCKED UNTRUSTED INSTRUCTION]" if injection else line)
+    return "\n".join(lines), flags
+
+
+def _context(root: Path) -> tuple[list[dict[str, str]], tuple[str, ...]]:
+    remaining = MAX_CONTEXT_BYTES
+    documents: list[dict[str, str]] = []
+    flags: list[str] = []
+    for path in _markdown_files(root):
+        if remaining <= 0:
+            break
+        relative = path.relative_to(root).as_posix()
+        try:
+            raw = path.read_bytes()[:MAX_FILE_BYTES]
+            text = raw.decode("utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        sanitized, found = _sanitize(relative, text)
+        encoded = sanitized.encode("utf-8")[:remaining]
+        documents.append({"path": relative, "content": encoded.decode("utf-8", "ignore")})
+        flags.extend(found)
+        remaining -= len(encoded)
+    return documents, tuple(sorted(set(flags)))
+
+
+def _prompt(root: Path, facts: tuple[InventoryItem, ...]) -> tuple[str, tuple[str, ...]]:
+    pack = load_default_pack()
+    documents, context_flags = _context(root)
+    flags = list(context_flags)
+    safe_facts: list[dict[str, object]] = []
+    for index, fact in enumerate(facts):
+        record: dict[str, object] = {}
+        for field, value in asdict(fact).items():
+            if not isinstance(value, str):
+                record[field] = value
+                continue
+            sanitized, found = _sanitize(f"inventory:{index}:{field}", value)
+            record[field] = sanitized
+            flags.extend(found)
+        safe_facts.append(record)
+    payload = {
+        "schema": "sourcebound.phrasing-request.v1",
+        "task": "Select prose templates for known facts. Do not add facts or prose.",
+        "standard": {
+            "constraint": pack["generation"]["constraint"],
+            "checklist": pack["checklist"],
+            "voice": pack["generation"]["voice"],
+            "purpose_contract": pack["generation"]["purpose_contract"],
+            "precedence": pack["generation"]["precedence"],
+            "exemplars": pack["generation"]["exemplars"],
+        },
+        "allowed_templates": {
+            template: sorted(kinds) for template, kinds in sorted(TEMPLATE_KINDS.items())
+        },
+        "facts": safe_facts,
+        "repository_context": documents,
+        "response_schema": {
+            "drafts": [{"fact_id": "known fact id", "template": "allowed template"}],
+        },
+    }
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")), tuple(sorted(set(flags)))
+
+
+def _draft_text(fact: InventoryItem, template: str) -> str:
+    name = " ".join(fact.name.split()).replace("`", "'")
+    label = fact.kind.replace("-", " ")
+    if template == "tests":
+        return f"The repository tests `{name}` through a {label}."
+    return f"The repository {template} `{name}` as a {label}."
+
+
+def _parse_response(response: str, facts: tuple[InventoryItem, ...]) -> tuple[GroundedDraft, ...]:
+    try:
+        raw = json.loads(response)
+    except json.JSONDecodeError as exc:
+        raise ConfigurationError("model response is not valid JSON") from exc
+    if not isinstance(raw, dict) or set(raw) != {"drafts"} or not isinstance(raw["drafts"], list):
+        raise ConfigurationError("model response does not match the grounded draft schema")
+    if len(raw["drafts"]) > 5:
+        raise ConfigurationError("model response exceeds the grounded draft limit")
+    by_id = {fact.id: fact for fact in facts}
+    drafts: list[GroundedDraft] = []
+    seen: set[str] = set()
+    for candidate in raw["drafts"]:
+        if not isinstance(candidate, dict) or set(candidate) != {"fact_id", "template"}:
+            raise ConfigurationError("model response contains an invalid grounded draft")
+        fact_id = candidate.get("fact_id")
+        template = candidate.get("template")
+        if not isinstance(fact_id, str) or fact_id not in by_id or fact_id in seen:
+            raise ConfigurationError("model response references an unsupported or duplicate fact")
+        fact = by_id[fact_id]
+        if not isinstance(template, str) or fact.kind not in TEMPLATE_KINDS.get(template, set()):
+            raise ConfigurationError("model response maps a fact to an unsupported template")
+        seen.add(fact_id)
+        drafts.append(GroundedDraft(fact_id, template, _draft_text(fact, template)))
+    return tuple(drafts)
+
+
+def build_model_record(
+    root: Path,
+    facts: tuple[InventoryItem, ...],
+    provider: PhrasingProvider,
+) -> ModelRecord:
+    prompt, flags = _prompt(root.resolve(), facts)
+    try:
+        response = provider.complete(prompt)
+    except Exception as exc:
+        raise ConfigurationError("phrasing provider failed before any repository write") from exc
+    if not isinstance(response, str):
+        raise ConfigurationError("phrasing provider returned a non-text response")
+    drafts = _parse_response(response, facts)
+    return ModelRecord(
+        provider=provider.name,
+        prompt_sha256=hashlib.sha256(prompt.encode()).hexdigest(),
+        response_sha256=hashlib.sha256(response.encode()).hexdigest(),
+        context_flags=flags,
+        drafts=drafts,
+    )

clean_docs/plugins.py

@@ -0,0 +1,249 @@
+"""Run versioned extension commands against disposable repository snapshots."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from clean_docs.errors import ConfigurationError, ExtractionError
+from clean_docs.execution import resolve_argv
+from clean_docs.inventory import InventoryItem, InventoryReport, scan_inventory
+from clean_docs.isolation import MAX_PROCESS_IO_BYTES, run_isolated_process
+from clean_docs.manifest import load_manifest
+from clean_docs.models import (
+    PLUGIN_API_VERSION,
+    EvidenceValue,
+    PluginSpec,
+    Provenance,
+    RegionBinding,
+)
+from clean_docs.policy import PolicyFinding
+from clean_docs.snapshot import RepositorySnapshot
+
+
+MAX_PLUGIN_OUTPUT_BYTES = MAX_PROCESS_IO_BYTES
+
+
+@dataclass(frozen=True)
+class PluginResponse:
+    plugin: str
+    operation: str
+    result: dict[str, Any]
+
+
+def _run_plugin(
+    snapshot: RepositorySnapshot,
+    plugin: PluginSpec,
+    operation: str,
+    payload: dict[str, Any],
+) -> PluginResponse:
+    if operation not in plugin.interfaces:
+        raise ConfigurationError(
+            f"plugin {plugin.id} does not implement the {operation} interface"
+        )
+    request = json.dumps(
+        {
+            "schema": "sourcebound.plugin-request.v1",
+            "api_version": PLUGIN_API_VERSION,
+            "operation": operation,
+            "snapshot": snapshot.label,
+            "payload": payload,
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    proc = run_isolated_process(
+        snapshot,
+        resolve_argv(plugin.argv),
+        label=f"plugin {plugin.id}",
+        timeout_seconds=plugin.timeout_seconds,
+        input_text=request,
+    )
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or proc.stdout.strip() or "no output"
+        raise ExtractionError(f"plugin {plugin.id} exited {proc.returncode}: {detail[:500]}")
+    try:
+        raw = json.loads(proc.stdout)
+    except json.JSONDecodeError as exc:
+        raise ExtractionError(f"plugin {plugin.id} returned invalid JSON: {exc}") from exc
+    if (
+        not isinstance(raw, dict)
+        or set(raw) != {"schema", "api_version", "result"}
+        or raw.get("schema") != "sourcebound.plugin-response.v1"
+        or raw.get("api_version") != PLUGIN_API_VERSION
+        or not isinstance(raw.get("result"), dict)
+    ):
+        raise ExtractionError(
+            f"plugin {plugin.id} must return sourcebound.plugin-response.v1 at API version 1"
+        )
+    return PluginResponse(plugin.id, operation, raw["result"])
+
+
+def _digest(value: Any) -> str:
+    normalized = json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(normalized.encode()).hexdigest()
+
+
+def extract_plugin(
+    snapshot: RepositorySnapshot, binding: RegionBinding, plugin: PluginSpec
+) -> EvidenceValue:
+    response = _run_plugin(
+        snapshot,
+        plugin,
+        "extractor",
+        {
+            "binding": binding.id,
+            "source": binding.source.path.as_posix(),
+            "renderer": binding.renderer,
+            "columns": list(binding.columns),
+        },
+    )
+    if set(response.result) != {"kind", "value"}:
+        raise ExtractionError(f"plugin {plugin.id} extractor result must contain kind and value")
+    kind = response.result["kind"]
+    if kind not in {"list", "mapping", "scalar", "table", "text"}:
+        raise ExtractionError(f"plugin {plugin.id} returned unsupported evidence kind: {kind}")
+    value = response.result["value"]
+    return EvidenceValue(
+        kind,
+        value,
+        Provenance(
+            snapshot.label,
+            binding.source.path.as_posix(),
+            binding.id,
+            f"plugin:{plugin.id}@{plugin.api_version}",
+            _digest(value),
+        ),
+    )
+
+
+def render_plugin(
+    snapshot: RepositorySnapshot,
+    binding: RegionBinding,
+    plugin: PluginSpec,
+    evidence: EvidenceValue,
+) -> str:
+    response = _run_plugin(
+        snapshot,
+        plugin,
+        "renderer",
+        {
+            "binding": binding.id,
+            "kind": evidence.kind,
+            "value": evidence.value,
+        },
+    )
+    if set(response.result) != {"content"} or not isinstance(
+        response.result["content"], str
+    ):
+        raise ExtractionError(f"plugin {plugin.id} renderer result must contain text content")
+    return response.result["content"]
+
+
+def check_plugin_policies(
+    snapshot: RepositorySnapshot,
+    plugins: tuple[PluginSpec, ...],
+    documents: dict[str, str],
+) -> list[PolicyFinding]:
+    findings: list[PolicyFinding] = []
+    for plugin in plugins:
+        if "policy" not in plugin.interfaces:
+            continue
+        response = _run_plugin(
+            snapshot,
+            plugin,
+            "policy",
+            {"documents": documents},
+        )
+        raw_findings = response.result.get("findings")
+        if set(response.result) != {"findings"} or not isinstance(raw_findings, list):
+            raise ExtractionError(f"plugin {plugin.id} policy result must contain a findings list")
+        for index, raw in enumerate(raw_findings):
+            if not isinstance(raw, dict) or set(raw) != {"doc", "line", "rule", "detail"}:
+                raise ExtractionError(
+                    f"plugin {plugin.id} policy finding {index} must contain doc, line, rule, and detail"
+                )
+            if (
+                not isinstance(raw["doc"], str)
+                or not isinstance(raw["line"], int)
+                or raw["line"] < 1
+                or not isinstance(raw["rule"], str)
+                or not isinstance(raw["detail"], str)
+            ):
+                raise ExtractionError(f"plugin {plugin.id} policy finding {index} is invalid")
+            findings.append(
+                PolicyFinding(raw["doc"], raw["line"], raw["rule"], raw["detail"])
+            )
+    return findings
+
+
+def discover_plugin_items(
+    snapshot: RepositorySnapshot, plugins: tuple[PluginSpec, ...]
+) -> tuple[InventoryItem, ...]:
+    items: list[InventoryItem] = []
+    identifiers: set[str] = set()
+    for plugin in plugins:
+        if "discoverer" not in plugin.interfaces:
+            continue
+        response = _run_plugin(snapshot, plugin, "discoverer", {})
+        raw_items = response.result.get("items")
+        if set(response.result) != {"items"} or not isinstance(raw_items, list):
+            raise ExtractionError(f"plugin {plugin.id} discoverer result must contain an items list")
+        for index, raw in enumerate(raw_items):
+            if not isinstance(raw, dict) or set(raw) != {
+                "kind", "name", "source", "locator", "evidence"
+            }:
+                raise ExtractionError(
+                    f"plugin {plugin.id} item {index} must contain kind, name, source, locator, and evidence"
+                )
+            if not all(
+                isinstance(raw[key], str) and raw[key]
+                for key in ("kind", "name", "source", "locator")
+            ):
+                raise ExtractionError(f"plugin {plugin.id} item {index} has invalid string fields")
+            source = Path(raw["source"])
+            if source.is_absolute() or ".." in source.parts:
+                raise ExtractionError(f"plugin {plugin.id} item {index} source escapes the repository")
+            identifier = f"{raw['kind']}:{raw['source']}:{raw['locator']}"
+            if identifier in identifiers:
+                raise ExtractionError(
+                    f"plugin {plugin.id} item {index} duplicates inventory id {identifier}"
+                )
+            identifiers.add(identifier)
+            items.append(
+                InventoryItem(
+                    identifier,
+                    raw["kind"],
+                    raw["name"],
+                    raw["source"],
+                    raw["locator"],
+                    f"plugin:{plugin.id}",
+                    _digest(raw["evidence"]),
+                    "standard-gap",
+                )
+            )
+    return tuple(sorted(items, key=lambda item: item.id))
+
+
+def merge_plugin_inventory(
+    base: tuple[InventoryItem, ...], additions: tuple[InventoryItem, ...]
+) -> tuple[InventoryItem, ...]:
+    merged = {item.id: item for item in base}
+    for item in additions:
+        if item.id in merged:
+            raise ExtractionError(f"plugin inventory id collides with core evidence: {item.id}")
+        merged[item.id] = item
+    return tuple(merged[key] for key in sorted(merged))
+
+
+def scan_extended_inventory(root: Path) -> InventoryReport:
+    base = scan_inventory(root)
+    manifest_path = root / ".sourcebound.yml"
+    if not manifest_path.is_file():
+        return base
+    manifest = load_manifest(manifest_path)
+    additions = discover_plugin_items(RepositorySnapshot(root), manifest.plugins)
+    return InventoryReport(base.languages, merge_plugin_inventory(base.items, additions))