Audit-Log Retention & Immutability Policy — PROJECT VELA
Status: DESIGNED/ROADMAPPED unless marked IMPLEMENTED. The core investigation stack (LangGraph + Neo4j + Qdrant + 3 FastMCP servers + FastAPI) is implemented and tested, and it emits an append-only investigation audit trail. The retention & immutability controls in this document — governed retention windows, tamper-evident storage, review-board export bundles, and legal-hold handling — are a separate surface and are mostly not yet implemented. Each control below carries an explicit status label.
Last reviewed: (owner to date — placeholder, not yet reviewed)
VELA is ground-segment, advisory-only software. It investigates telemetry deviations and
drafts recovery procedures for a human to execute; it holds zero commanding authority in v1.
Flight-software audit regimes (DO-178C, NASA NPR 7150.2, ECSS review boards) do not bind it —
see docs/assurance/classification-and-safety-case.md. What we borrow from them in spirit is
one idea: the investigation record must be complete enough that an anomaly review board can
reconstruct exactly what the tool saw, concluded, and recommended, and who approved it.
1. Purpose & scope
| What this governs | The per-investigation audit log — the review-board artifact for one anomaly investigation — and the OpenTelemetry (OTel) trace backbone it is built on. |
| Why it exists | Anomaly review boards (customer-side and, later, ISRO/NSIL) require a defensible, tamper-evident record. VELA’s core value claim (grounded, cited reasoning) is only credible if the record proving it is itself trustworthy. |
| Out of scope | Raw customer telemetry retention (see DATA-HANDLING.md); the design-graph / KG provenance (see docs/design/03-DATA-SPEC.md); export-control aspects (see EXPORT-CONTROL.md); application/infra logs that are not the investigation record (ordinary ops logging, separate lifecycle). |
| Related invariant | Architecture Audit Invariant #4: Full audit log (every tool call + hypothesis transition) persisted per investigation. This policy is how #4 is operationalized. |
2. What is logged
The audit log is append-only and scoped to a single investigation (thread_id). Every record
carries tenant_id + satellite_id + investigation_id (mandatory from day one — see §6).
| Event class | Captured fields (intended) | Status |
|---|---|---|
| MCP tool call | server, tool, request args, response digest, latency, sha256 of any returned DocSection, trace/span IDs |
DESIGNED |
| Telemetry read | channel(s), time window, sample count, detector, source store — establishes the provenance set for Invariant #1 (no asserted value without a backing telemetry call) | DESIGNED |
| Hypothesis transition | from-state → to-state, evidence refs, confidence, which node emitted it, OpenCase/LinkEvidence/inverse operator applied to the overlay |
DESIGNED |
| Citation | Citation{kind, ref, sha256}, resolver verdict from vela/audit/citation_check.py (valid / invalid / UNGROUNDED) |
DESIGNED |
| Approval / interrupt | LangGraph interrupt() gate reached, operator identity + RBAC role, decision (approve/reject/edit), resumed checkpoint ID |
DESIGNED |
| Verdict & report | final InvestigationReport digest, audit_log_ref, procedure-draft acceptance state |
DESIGNED |
| Mode & model | cloud vs airgap, model/router identity, config hash — so a record proves which stack produced it |
DESIGNED |
Not logged / minimized: raw telemetry values are not duplicated into the audit log beyond what a claim cites (the log references the telemetry read, it is not a second telemetry store); model chain-of-thought scratch text is not persisted as record-grade content. Operator identity is the only PII in the log — see §7.
3. Immutability & tamper-evidence
Intent (DESIGNED): the audit log is append-only and tamper-evident, not merely “write-protected by convention.”
| Mechanism | Description | Status |
|---|---|---|
| Append-only writes | Records are only ever appended; no in-place update or delete API exists on the audit path. Corrections are new records that reference the superseded one. | DESIGNED |
| Content addressing | Each cited DocSection and each report is identified by sha256; the audit record stores the hash, not a mutable pointer. A changed source ⇒ a changed hash ⇒ visible. |
DESIGNED |
| Hash-chaining | Each audit record includes the hash of the prior record for that investigation (a per-investigation chain), so any excision or reordering is detectable by re-walking the chain. | ROADMAPPED |
| Overlay invertibility | KG overlay writes use a typed invertible operator vocabulary; overturned hypotheses invert rather than erase, so the reasoning history is preserved by construction. | DESIGNED |
| WORM / object-lock storage | Archive tier written to object storage with an object-lock / write-once retention setting for the contracted window. | ROADMAPPED |
| Cryptographic signing / external anchoring | Periodic signing of chain heads (and, if a customer requires it, external timestamp anchoring). | ASPIRATIONAL |
Honest limits. Until hash-chaining and object-lock ship, immutability is design intent enforced by API surface and access control, not a cryptographic guarantee. We will not describe the log as “immutable” to a customer until the chaining + WORM controls above are IMPLEMENTED; the correct pre-build phrasing is “append-only by design, tamper-evidence roadmapped.”
4. Relationship to time-travel replay (LangGraph checkpoints)
Two distinct things share one investigation identity; do not conflate them.
| Audit log | LangGraph checkpoints | |
|---|---|---|
| Purpose | Review-board evidence: what happened and why | Durable execution + forensic replay of the run |
| Backing | OTel traces (backbone) + append-only records | Postgres checkpointer keyed by thread_id |
| Mutability | Append-only, tamper-evident (§3) | Operational state; may be pruned per §5 |
| Consumer | Auditors, review boards, incident response | Operators (“replay this investigation” UI), engineers |
How they relate (DESIGNED). Checkpoints make the replay-this-investigation product feature possible — an operator or board member can step the graph forward from any saved checkpoint and watch the reasoning unfold. The audit log is the authoritative record; checkpoints are a convenience for reconstruction. Where retained together, a replay must reproduce the audit log’s recorded decisions — a divergence is itself a sev-worthy integrity signal. Checkpoints are not a substitute for the audit log and may have a shorter retention window (they are heavier and operational); the audit log outlives them.
5. Retention windows
All numbers below are defaults. The customer sets the number in the pilot/commercial contract; these are the values applied when the contract is silent.
| Tier | Default window | What lives here | Notes |
|---|---|---|---|
| Hot (query-fast) | 90 days | Full audit log + OTel traces for recent investigations | Sized for active review boards + support. Customer-configurable. |
| Cold / archive | per customer contract (default target 7 years where a customer wants a long anomaly-history retention; otherwise contract-set) | Compressed, WORM-intended archive of the audit log | The board artifact must outlive the hot window; long tail is a customer decision, not ours to assume. |
| LangGraph checkpoints | 30 days (default) | Replayable run state | Shorter than the audit log on purpose; replay is a convenience, the log is the record. |
| OTel raw spans (debug detail) | 30 days (default) | High-cardinality span detail for engineering | The audit-grade projection of the trace is retained on the audit-log schedule, not this one. |
Configurability & floors. Retention is set per tenant. A customer may lengthen archive retention freely. Shortening below a regulatory or contractual floor (e.g. a review-board obligation) requires explicit written sign-off recorded in the contract. Retention timers are enforced by scheduled lifecycle jobs (ROADMAPPED); until built, no automated expiry runs and records simply accumulate on the pilot’s encrypted volume.
Status: retention scheduling and tiering — DESIGNED, not implemented.
6. Tenant isolation
| Control | Description | Status |
|---|---|---|
| Mandatory keys | tenant_id + satellite_id present in every contract, key, MCP request, and audit record from day one. No unkeyed audit record can exist. |
DESIGNED (invariant) |
| Per-customer encrypted volumes | Each customer’s audit log lives on its own encrypted volume; no shared audit store across tenants. | DESIGNED |
| MCP as sole data boundary | Agents never touch stores directly; all data access (and thus all audit-relevant reads) flows through the three FastMCP servers, import-linted. This makes the audit boundary a single enforceable choke point per tenant. | DESIGNED |
| Query scoping | Every audit query is tenant-scoped by construction; cross-tenant read is not an available operation. | ROADMAPPED |
| Airgap / sovereign mode | In airgap mode the entire audit log stays inside the customer’s no-egress boundary; nothing leaves. One config flag; no cloud audit copy exists. |
DESIGNED |
7. PII minimization
The audit log is deliberately PII-poor. The only personal data it contains is operator identity — who ran an investigation and who approved a procedure release (RBAC roles operator / reviewer / admin). This is unavoidable: attributing approvals is the point of the approval gate.
| Principle | Application | Status |
|---|---|---|
| Minimize | Store the minimum identity needed to attribute an action (a stable operator ref + role), not a personnel profile. No contact details, no free-text about people. | DESIGNED |
| Pseudonymize where possible | Prefer a tenant-scoped operator ID over raw name/email in the record body; resolve to a human identity only through the customer’s own directory. | ROADMAPPED |
| DPDP alignment | Handling of operator identity follows DATA-HANDLING.md and India’s DPDP posture (purpose limitation, storage limitation via §5 windows, tenant-controlled deletion). VELA is not yet assessed against any certification — see COMPLIANCE-ROADMAP.md. |
DESIGNED |
| No telemetry PII | Telemetry and KG content are spacecraft engineering data, not personal data; the log references them, it does not enrich them with personal data. | DESIGNED |
See DATA-HANDLING.md and docs/policies/rbac.md for the identity model.
8. Export for review boards
The audit log’s reason to exist is to be handed to a review board.
| Capability | Description | Status |
|---|---|---|
| Investigation export bundle | One command produces a self-contained bundle for an investigation_id: the InvestigationReport, the full ordered audit log, resolved citations (with sha256), approval trail, and the mode/model provenance. |
DESIGNED |
| Integrity manifest | The bundle ships with a manifest of record hashes (and, once §3 chaining lands, the chain head) so a recipient can independently verify nothing was altered. | ROADMAPPED |
| Human-readable + machine-readable | Board-facing PDF/HTML rendering plus a structured (JSON) form for downstream tooling. | ROADMAPPED |
| Replay handoff | Optionally, a checkpoint reference enabling “replay this investigation” against a VELA instance (subject to checkpoint retention, §5). | DESIGNED |
| Scope discipline | Export is single-tenant, single-investigation by default; bulk/cross-investigation export is an admin action, itself audited. | DESIGNED |
Sev-1 tie-in. A citation that fails to resolve in an exported bundle (a hallucinated reference
reaching a review board) is a sev-1 under docs/policies/incident-response-citation-integrity.md.
Citation integrity is 100% at every PRD tier; the audit log is the evidence that it held.
9. Deletion & zero-copy-post-pilot alignment
| Control | Description | Status |
|---|---|---|
| Contractual zero-copy post-pilot | The default pilot contract states VELA keeps zero copies of customer data after the pilot. The audit log is customer data and is covered: on pilot close it is exported to the customer (if they want it) and then destroyed on our side. | DESIGNED |
| Tenant-scoped deletion | Deletion operates per tenant_id; destroying a tenant destroys its encrypted volume, audit log included, with no cross-tenant residue. |
DESIGNED |
| Retention-expiry deletion | Records past their §5 window are purged by scheduled lifecycle jobs; archive-tier WORM records are destroyed only at end-of-retention, not before. | ROADMAPPED |
| Deletion is itself recorded | A destruction event (what tenant, what window, when, by whom) is logged in a separate operational record so the fact of deletion is provable even though the content is gone. | ROADMAPPED |
| Tension to manage honestly | Immutability/WORM (§3) and deletion-on-demand pull in opposite directions. Resolution: immutability holds within a retention window; deletion happens at the window boundary or at pilot close per contract. We do not offer selective mid-window record deletion — that would defeat the tamper-evidence the log exists to provide. A legal-hold that must override a scheduled deletion is a manual, documented exception. | DESIGNED |
10. Status summary
| Control area | Status |
|---|---|
| Append-only audit log, per-investigation | DESIGNED |
| OTel trace backbone (Week-1 instrumentation intent) | DESIGNED |
Content-addressed (sha256) citations |
DESIGNED |
| Hash-chaining / tamper-evidence | ROADMAPPED |
| WORM / object-lock archive | ROADMAPPED |
| Cryptographic signing / external anchoring | ASPIRATIONAL |
| Retention tiering + scheduled expiry | DESIGNED (jobs ROADMAPPED) |
| Tenant isolation via mandatory keys + per-customer volumes | DESIGNED |
| Airgap: no audit egress | DESIGNED |
| PII minimization (operator identity only), DPDP alignment | DESIGNED |
| Review-board export bundle + integrity manifest | DESIGNED / manifest ROADMAPPED |
| Zero-copy-post-pilot deletion | DESIGNED (contractual) |
The retention/immutability controls in this table are mostly not yet IMPLEMENTED — the core stack emits an append-only investigation audit trail, but the governed retention, tamper-evidence, and export controls above are the specification we are building against, not yet a description of a running governed-retention system. Each row’s status label is authoritative.
References
SECURITY.md · COMPLIANCE-ROADMAP.md · EXPORT-CONTROL.md · DATA-HANDLING.md · CLAUDE.md ·
docs/design/02-ARCHITECTURE.md · docs/design/03-DATA-SPEC.md · docs/design/04-MCP-SERVERS.md ·
docs/design/06-TEST-PLAN.md · docs/design/10-SCALE-ARCHITECTURE.md ·
docs/assurance/classification-and-safety-case.md · docs/assurance/hazard-analysis.md ·
docs/assurance/rtm.csv · docs/policies/rbac.md ·
docs/policies/incident-response-citation-integrity.md