up

docs/09_API_CLI_REFERENCE.md

@@ -652,18 +652,95 @@ Signals APIs (base path: `/signals`) provide deterministic ingestion + scoring f
 
 | Method | Path | Scope | Notes |
 |--------|------|-------|-------|
-| `POST` | `/signals/callgraphs` | `signals:write` | Ingest a callgraph artifact (base64 JSON); response includes `graphHash` (sha256) and CAS URIs. |
-| `POST` | `/signals/runtime-facts` | `signals:write` | Ingest runtime hit events (JSON). |
-| `POST` | `/signals/runtime-facts/ndjson` | `signals:write` | Stream NDJSON events (optional gzip) with subject in query params. |
+| `POST` | `/signals/callgraphs` | `signals:write` | Ingest a callgraph artifact (richgraph-v1 JSON); response includes `graphHash` (BLAKE3) and CAS URIs. |
+| `POST` | `/signals/runtime-facts` | `signals:write` | Ingest runtime hit events (JSON) with `symbolId`, `codeId`, `hitCount`, `loaderBase`. |
+| `POST` | `/signals/runtime-facts/ndjson` | `signals:write` | Stream NDJSON events (optional gzip) with `scanId`/`imageDigest` in query params. |
 | `POST` | `/signals/unknowns` | `signals:write` | Ingest unresolved symbols/edges; influences `unknownsPressure`. |
-| `GET` | `/signals/facts/{subjectKey}` | `signals:read` | Fetch `ReachabilityFactDocument` including `metadata.fact.digest` and per-target `states[]`. |
+| `GET` | `/signals/facts/{subjectKey}` | `signals:read` | Fetch `ReachabilityFactDocument` including `metadata.fact.digest`, per-target `states[]`, and `latticeState`. |
 | `POST` | `/signals/reachability/recompute` | `signals:admin` | Recompute reachability for explicit targets and blocked edges. |
 
+**Callgraph ingestion request:**
+
+```json
+{
+  "schema": "richgraph-v1",
+  "analyzer": {"name": "scanner.java", "version": "1.2.0", "toolchain_digest": "sha256:..."},
+  "nodes": [
+    {
+      "id": "sym:java:...",
+      "symbol_id": "sym:java:...",
+      "code_id": "code:java:...",
+      "lang": "java",
+      "kind": "method",
+      "display": "com.example.Foo.bar()",
+      "purl": "pkg:maven/com.example/foo@1.0.0",
+      "symbol_digest": "sha256:...",
+      "symbol": {"demangled": "com.example.Foo.bar()", "source": "DWARF", "confidence": 0.98}
+    }
+  ],
+  "edges": [{"from": "sym:java:...", "to": "sym:java:...", "kind": "call", "purl": "pkg:maven/...", "symbol_digest": "sha256:...", "confidence": 0.92}],
+  "roots": [{"id": "sym:java:...", "phase": "runtime", "source": "main"}]
+}
+```
+
+**Callgraph ingestion response:**
+
+```json
+{
+  "graphHash": "blake3:a1b2c3d4e5f6...",
+  "casUri": "cas://reachability/graphs/a1b2c3d4e5f6...",
+  "dsseUri": "cas://reachability/graphs/a1b2c3d4e5f6....dsse",
+  "nodeCount": 1247,
+  "edgeCount": 3891
+}
+```
+
+**Runtime facts NDJSON fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `symbolId` | Yes | Canonical `sym:{lang}:{base64url}` |
+| `codeId` | No | `code:{lang}:{base64url}` for stripped binaries |
+| `hitCount` | No | Number of observed invocations |
+| `loaderBase` | No | Memory address base for position-independent code |
+| `processId` | No | OS process identifier |
+| `containerId` | No | Container runtime identifier |
+| `observedAt` | No | ISO-8601 UTC timestamp |
+
+**Reachability facts response (excerpt):**
+
+```json
+{
+  "subjectKey": "scan:123:pkg:maven/log4j:2.14.1:CVE-2021-44228",
+  "metadata": {"fact": {"digest": "sha256:abc123...", "version": 3}},
+  "states": [
+    {
+      "symbol": "sym:java:...",
+      "latticeState": "CR",
+      "bucket": "runtime",
+      "confidence": 0.92,
+      "score": 0.78,
+      "path": ["sym:java:main...", "sym:java:log4j..."],
+      "evidence": {
+        "static": {"graphHash": "blake3:...", "pathLength": 3},
+        "runtime": {"hitCount": 47, "observedAt": "2025-12-13T10:00:00Z"}
+      }
+    }
+  ],
+  "score": 0.78,
+  "aggregateTier": "T2",
+  "riskScore": 0.65
+}
+```
+
+**Lattice states:** `U` (Unknown), `SR` (StaticallyReachable), `SU` (StaticallyUnreachable), `RO` (RuntimeObserved), `RU` (RuntimeUnobserved), `CR` (ConfirmedReachable), `CU` (ConfirmedUnreachable), `X` (Contested).
+
 Docs & samples:
 - `docs/api/signals/reachability-contract.md`
 - `docs/api/signals/samples/callgraph-sample.json`
 - `docs/api/signals/samples/facts-sample.json`
 - `docs/reachability/lattice.md`
+- `docs/reachability/function-level-evidence.md`
 
 ### 2.9 CVSS Receipts (Policy Gateway)
 
@@ -818,6 +895,10 @@ Both commands honour CLI observability hooks: Spectre tables for human output, `
 | `stellaops-cli sources ingest --dry-run` | Dry-run guard validation for individual payloads | `--source <id>`<br>`--input <path\|uri>`<br>`--tenant <id>`<br>`--format table\|json`<br>`--output <file>` | Normalises gzip/base64 payloads, invokes `api/aoc/ingest/dry-run`, and maps guard failures to deterministic `ERR_AOC_00x` exit codes. |
 | `stellaops-cli aoc verify` | Replay AOC guardrails over stored documents | `--since <ISO8601\|duration>`<br>`--limit <count>`<br>`--sources <list>`<br>`--codes <ERR_AOC_00x,...>`<br>`--format table\|json`<br>`--export <file>` | Summarises checked counts/violations, supports JSON evidence exports, and returns `0`, `11…17`, `18`, `70`, or `71` depending on guard outcomes. |
 | `stellaops-cli config show` | Display resolved configuration | — | Masks secret values; helpful for air‑gapped installs |
+| `stellaops-cli graph explain` | Show reachability call path for a finding | `--finding <purl:cve>` (required)<br>`--scan-id <id>`<br>`--format table\|json` | Displays `latticeState`, call path with `symbol_id`/`code_id`, runtime hits, `graph_hash`, and DSSE attestation refs |
+| `stellaops-cli graph export` | Export reachability graph bundle | `--scan-id <id>` (required)<br>`--output <dir>`<br>`--include-runtime` | Creates `richgraph-v1.json`, `.dsse`, `meta.json`, and optional `runtime-facts.ndjson` |
+| `stellaops-cli graph verify` | Verify graph DSSE signature and Rekor entry | `--graph <path>` (required)<br>`--dsse <path>`<br>`--rekor-log` | Recomputes BLAKE3 hash, validates DSSE envelope, checks Rekor inclusion proof |
+| `stellaops-cli replay verify` | Verify replay manifest determinism | `--manifest <path>` (required)<br>`--sealed`<br>`--verbose` | Recomputes all artifact hashes and compares against manifest; exit 0 on match |
 | `stellaops-cli runtime policy test` | Ask Scanner.WebService for runtime verdicts (Webhook parity) | `--image/-i <digest>` (repeatable, comma/space lists supported)<br>`--file/-f <path>`<br>`--namespace/--ns <name>`<br>`--label/-l key=value` (repeatable)<br>`--json` | Posts to `POST /api/v1/scanner/policy/runtime`, deduplicates image digests, and prints TTL/policy revision plus per-image columns for signed state, SBOM referrers, quieted-by metadata, confidence, Rekor attestation (uuid + verified flag), and recently observed build IDs (shortened for readability). Accepts newline/whitespace-delimited stdin when piped; `--json` emits the raw response without additional logging. |
 
 > Need to debug how the scanner resolves entry points? See the [entry-point documentation index](modules/scanner/operations/entrypoint.md), which links to static/dynamic reducers, ShellFlow, and runtime-specific guides.