stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity
Files
10212d67c0dfa0dd849fd798c24502b773664749
git.stella-ops.org/docs/advisory-ai/guardrails-and-evidence.md
master 10212d67c0
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details
Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.
2025-11-20 07:50:52 +02:00

4.4 KiB
Raw Blame History

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.