Disciplines · Decisions (ADRs)

ADR-0029: OSHUN Studio Audit and Compliance Surfaces

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

Accepted · 2026-02-23
10sections3 minread
Markdown source
On this page

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.
  • 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