fix(sbom): harden bounded lineage input privacy

README.md

@@ -274,7 +274,7 @@ Published as [`io.github.Perseus-Computing-LLC/perseus`](https://registry.modelc
 
 ### MCP Tools
 
-<!-- test-count: 2442 — recount with: grep -rE "^\s*def test_" tests/ | wc -l -->
+<!-- test-count: 2591 — recount with: grep -rE "^\s*def test_" tests/ | wc -l -->
 <!-- The table below documents the current default output of _get_all_mcp_tools({}). Recount before editing. -->
 MCP tools resolve live state at invocation time, including the canonical Perseus Vault tool. Two additional sensitive tools — `perseus_query` (run a shell command) and `perseus_agent` (execute a local agent subprocess) — are **not** part of this default set: they require explicit `mcp.tool_allowlist` opt-in because they execute commands in the user's local shell (**not sandboxed, full user permissions apply**).
 

docs/SBOM.md

@@ -95,3 +95,48 @@
 - [x] Dependency relationship: listed above
 - [x] SBOM author: Perseus Computing LLC
 - [x] Timestamp: included
+
+---
+
+## Queryable SBOM and lineage contract (#995)
+
+Perseus also provides an offline, stdlib-only normalization and query surface
+for SBOMs produced by an existing scanner or build pipeline. It does not replace
+those tools and it does not infer a clean result from an incomplete document.
+
+Supported input formats:
+
+- SPDX 2.2/2.3 JSON and XML;
+- CycloneDX 1.4/1.5/1.6 JSON and XML.
+
+Every normalized document records its format/version, source reference, raw
+document SHA-256, supplier/timestamp metadata when supplied, component and
+relationship counts, and an ingestion digest. Component projections retain
+names, versions, package identifiers, licenses, and supplied vulnerability,
+VEX, signature, attestation, advisory, or documentation references. Missing
+metadata is represented as `partial` coverage with explicit `unknown` fields.
+
+A local graph can add pipeline-owned edges for:
+
+```text
+source -> dependency -> build -> artifact -> deployment
+```
+
+Each edge carries explicit confidence (`high`, `medium`, `low`, or `unknown`),
+coverage (`complete`, `partial`, or `unknown`), and optional evidence
+references. The impacted-artifact query returns the traversed path and evidence
+references. A query with incomplete coverage returns `unknown` or `partial`;
+`not_affected` is never asserted merely because no artifact was found.
+
+Example offline commands:
+
+```bash
+perseus sbom ingest build.spdx.json --output normalized.json
+# Persisted normalized documents must be rebound to their raw source at merge.
+perseus sbom merge normalized.json --raw-documents build.spdx.json --edges pipeline-edges.json --output lineage.json
+# Persisted lineage must be rebound again at query in a new process.
+perseus sbom query lineage.json CVE-2021-44228 --raw-documents build.spdx.json --edges pipeline-edges.json --json
+```
+
+The core path requires no cloud service. Deterministic JSON/XML fixtures and
+contract tests live under `tests/fixtures/sbom/` and `tests/test_sbom_lineage.py`.