# ADR-0029: OSHUN Studio Audit and Compliance Surfaces

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Security, OSHUN Web + BFF
Engineering  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio governance actions already emit telemetry and audit records, but
operators lack a unified audit/compliance surface to inspect policy decisions,
trace actor intent, and resolve compliance workflows with deterministic
evidence.

Without dedicated audit/compliance surfaces, OSHUN risks:

- fragmented audit evidence across domains and workflows
- slower incident/compliance investigations
- inconsistent retention and evidence-validation handling
- reduced operator confidence in governance traceability

## Decision Drivers

- **Traceability**: unified actor/action evidence across Studio surfaces.
- **Compliance readiness**: deterministic evidence retention and review
  workflows.
- **Operational speed**: faster incident and policy investigation loops.
- **Consistency**: one audit/compliance UX contract across domains.
- **Interoperability**: preserve domain and Project Obsidian governance
  alignment.

## Considered Options

### Option 1: Keep Audit Evidence in Backend Systems Only

Rely on backend logs and data tools without first-class Studio audit UX.

**Pros**:

- Lower frontend implementation cost.

**Cons**:

- Poor operator accessibility and slow investigations.
- Inconsistent evidence workflows.

### Option 2: Domain-Specific Audit Screens

Each domain builds independent audit/compliance UIs.

**Pros**:

- Domain customization flexibility.

**Cons**:

- Fragmented UX and policy interpretation drift.
- Harder centralized governance and compliance review.

### Option 3: Unified Studio Audit and Compliance Surface Model (Chosen)

Adopt one Studio audit/compliance UX contract with canonical evidence,
investigation, and retention workflows.

**Pros**:

- Consistent and accessible evidence interpretation.
- Better incident/compliance response velocity.
- Stronger governance and audit integrity.

**Cons**:

- Higher cross-team schema and workflow coordination.

## Decision Outcome

**Chosen option**: Option 3.

Audit/compliance surface requirements:

1. **Audit evidence contract** for actor/action/outcome/trace lineage.
2. **Investigation workflow contract** for filtering, correlation, and
   escalation.
3. **Compliance review contract** for attestations, exceptions, and closure.
4. **Retention and compatibility contract** for evidence schema/version changes.
5. **Release governance** with validation, approval, telemetry/audit, and
   rollback.

## Normative Rules

### Audit Evidence Contract

- All governed actions must produce canonical audit records with actor, action,
  outcome, reason, and trace identifiers.
- Evidence records must be immutable once committed.
- Missing canonical fields must fail evidence ingestion.

### Investigation Workflow Contract

- Investigation views must support deterministic filtering by actor, domain,
  policy, tenant, and severity.
- Correlated events must preserve trace lineage and ordering.
- Escalation actions must be explicitly recorded.

### Compliance Review Contract

- Compliance attestations must reference concrete evidence sets.
- Exception approvals/denials must retain rationale and approver identity.
- Review closure must include remediation status and verification evidence.

### Retention and Compatibility Contract

- Evidence retention windows must be policy-driven and auditable.
- Schema/version changes require compatibility validation.
- Breaking changes require migration and rollback guidance.

### Release Validity Contract

An audit/compliance release is valid only when all are true:

- evidence schema validation checks pass
- investigation workflows pass deterministic query/correlation checks
- compliance review actions pass policy and audit checks
- telemetry/audit records are complete
- rollback strategy is documented

## Architecture Implications

- Studio web exposes unified audit/compliance investigation and review surfaces.
- BFF and data services provide canonical evidence query and correlation APIs.
- Security/compliance services integrate exception and attestation workflows.
- Analytics pipelines track audit/compliance surface usage and outcomes.

## Acceptance Criteria (OST-00129)

`OST-00129` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0035-oshun-studio-audit-and-compliance-surfaces.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines audit evidence, investigation workflow, compliance review,
   retention/compatibility, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0028`, especially `ADR-0012`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Stronger cross-domain audit visibility and compliance execution.
- Faster incident investigation with consistent evidence lineage.
- Better audit/compliance confidence for enterprise operations.

### Negative

- Additional evidence-schema governance overhead.
- Requires disciplined retention and correlation infrastructure.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0033-oshun-studio-rbac-and-permission-policy-ux.md`
- `docs/adr/ADR-0034-oshun-studio-enterprise-tenant-isolation.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/design/ux-principles.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`