Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.

docs/advisory-ai/guardrails-and-evidence.md

@@ -0,0 +1,62 @@
+# Advisory AI Guardrails & Evidence Intake
+
+_Updated: 2025-11-18 · Owner: Advisory AI Docs Guild · Status: Draft (Sprint 0111)_
+
+This note captures the guardrail behaviors and evidence intake boundaries required by Sprint 0111 tasks (`AIAI-DOCS-31-001`, `AIAI-RAG-31-003`). It binds Advisory AI guardrails to upstream evidence sources and clarifies how Link-Not-Merge (LNM) documents flow into Retrieval-Augmented Generation (RAG) payloads.
+
+## 1) Evidence sources and contracts
+
+- **Advisory observations (LNM)** — Consume immutable `advisory_observations` and `advisory_linksets` produced per `docs/modules/concelier/link-not-merge-schema.md` (frozen v1, 2025-11-17).
+- **VEX statements** — Excititor + VEX Lens linksets with trust weights; treated as structured chunks with `source_id` and `confidence`.
+- **SBOM context** — `SBOM-AIAI-31-001` contract: timelines and dependency paths retrieved via `ISbomContextRetriever` (`AddSbomContextHttpClient`), default clamps 500 timeline entries / 200 paths.
+- **Policy explain traces** — Policy Engine digests referenced by `policyVersion`; cache keys include policy hash to keep outputs replayable.
+- **Runtime posture (optional)** — Zastava signals (`exposure`, `admissionStatus`) when provided by Link-Not-Merge-enabled tenants; optional chunks tagged `runtime`.
+
+All evidence items must carry `content_hash` + `source_id`; Advisory AI never mutates or merges upstream facts (Aggregation-Only Contract).
+
+## 2) Guardrail stages
+
+1. **Pre-flight sanitization**
+   - Redact secrets (AWS-style keys, PEM blobs, generic tokens).
+   - Strip prompt-injection phrases; enforce max input payload 16 kB (configurable, default).
+   - Reject requests missing `advisoryKey` or linkset-backed evidence (LNM guard).
+2. **Prompt assembly**
+   - Deterministic section order: advisory excerpts → VEX statements → SBOM deltas → policy traces → runtime hints.
+   - Vector previews capped at 600 chars + ellipsis; section budgets fixed per profile (`default`, `gost-local`, `cloud-openai`).
+3. **LLM invocation (local/remote)**
+   - Profiles selected via `profile` field; remote profiles require Authority tenant consent and `advisory-ai:operate` + `aoc:verify`.
+4. **Validation & citation enforcement**
+   - Every emitted fact must map to an input chunk (`source_id` + `content_hash`); citations serialized as `[n]` in Markdown.
+   - Block outputs lacking citations, exceeding section budgets, or including unredacted PII.
+5. **Output sealing**
+   - Store `outputHash`, `inputDigest`, `provenanceHash`; wrap in DSSE when configured.
+   - Cache TTL defaults to 24h; regenerate only when inputs change or `forceRefresh=true`.
+
+Metrics: `advisory_ai_guardrail_blocks_total`, `advisory_ai_outputs_stored_total`, `advisory_ai_citation_coverage_ratio`. Logs carry `output_hash`, `profile`, and block reason; no secrets or raw prompt bodies are logged.
+
+## 3) RAG payload mapping to LNM (summary)
+
+| LNM field | RAG chunk field | Notes |
+| --- | --- | --- |
+| `observation._id` | `source_id` | Used for citations and conflict surfacing. |
+| `observation.advisoryId` | `advisory_key` | Keyed alongside task type in cache. |
+| `observation.affected[].purl` | `purl` | Included for remediation + SBOM joins. |
+| `observation.severities[]` | `severity` | Passed through unmerged; multiple severities allowed. |
+| `linkset.conflicts[]` | `conflicts` | Rendered verbatim for conflict tasks; no inference merges. |
+| `provenance.sourceArtifactSha` | `content_hash` | Drives determinism and replay. |
+
+See `docs/advisory-ai/evidence-payloads.md` for full JSON examples and alignment rules.
+
+## 4) Compliance with upstream artefacts
+
+- References: `CONSOLE-VULN-29-001`, `CONSOLE-VEX-30-001`, `CLI-VULN-29-001`, `CLI-VEX-30-001`, `EXCITITOR-CONSOLE-23-001`, `DEVOPS-AIAI-31-001`.
+- Guardrails must remain compatible with `docs/policy/assistant-parameters.md`; configuration knobs documented there are authoritative for env vars and defaults.
+- Packaging tasks (AIAI-PACKAGING-31-002) must include this guardrail summary in DSSE metadata to keep Offline Kit parity.
+
+## 5) Operator checklist
+
+- [ ] LNM feed enabled and Concelier schemas at v1 (2025-11-17).
+- [ ] SBOM retriever configured or `NullSbomContextClient` left as safe default.
+- [ ] Policy hash pinned via `policyVersion` when reproducibility is required.
+- [ ] Remote profiles only after Authority consent and profile allowlist are set.
+- [ ] Cache directories shared between web + worker hosts for DSSE sealing.