Status: Active
Owner: OSHUN Studio Architecture + OSHUN Security + Compliance + OSHUN Web +
OSHUN BFF
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0029-oshun-studio-audit-and-compliance-surfaces.mddocs/releases/v1/specs/studio-audit-and-compliance-surfaces-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio audit and compliance surfaces governance.
This document is the execution artifact for OST-00131.
Personas#
- Program Operator
- Security Reviewer
- Compliance Auditor
- Reliability Engineer
- Domain Integrator
Journey Principles#
- Audit evidence must be searchable, immutable, and trace-correlated.
- Compliance review actions must be explicit and attributable.
- Evidence gaps must fail safe with clear remediation guidance.
- Retention and exception workflows must remain policy-consistent.
1. Primary Journeys#
J1. Audit Evidence Search and Correlation#
Goal: Locate and correlate actor/action evidence across Studio domains.
Entry: Studio -> Audit and Compliance Surfaces -> Evidence Search
Steps:
- Apply filters (actor, action, domain, timeframe, outcome).
- Retrieve paginated canonical evidence records.
- Correlate events by trace id.
- Inspect ordered event lineage.
- Save investigation snapshot.
Success State:
- Operator can deterministically trace a governance action end to end.
J2. Compliance Review and Attestation#
Goal: Execute compliance review on selected evidence set.
Entry: Compliance review queue
Steps:
- Select review case and linked evidence records.
- Validate policy compliance requirements.
- Add reviewer notes and attestation decision.
- Approve/deny/close review case.
- Emit compliance review audit event.
Success State:
- Compliance decision is recorded with full evidence linkage.
J3. Exception Workflow and Decision Logging#
Goal: Process compliance exceptions with transparent decisioning.
Entry: Exception request submitted
Steps:
- Load exception request details and policy references.
- Validate justification and impact scope.
- Approve/deny exception with reason.
- Apply decision state and expiry metadata.
- Record exception decision evidence.
Success State:
- Exception decisions are policy-consistent and auditable.
J4. Incident Audit Reconstruction#
Goal: Reconstruct incident timeline using audit evidence.
Entry: Incident alert with trace references
Steps:
- Load incident trace and related evidence chain.
- Reconstruct actor/action sequence.
- Identify policy denies, overrides, and failures.
- Export evidence summary for incident response.
- Publish remediation follow-up tasks.
Success State:
- Incident timeline is reconstructed with deterministic evidence integrity.
J5. Retention Policy Verification and Legal Hold Review#
Goal: Validate evidence retention and legal hold handling.
Entry: Retention policy review cycle
Steps:
- Inspect retention policies by evidence category.
- Verify archive tier and retention window compliance.
- Validate legal hold flags for active investigations.
- Confirm eligible records are archived/retained correctly.
- Record retention verification outcome.
Success State:
- Retention and legal hold workflows are policy-compliant and verifiable.
2. Critical Edge Cases#
E1. Missing Canonical Evidence Fields#
- Trigger: evidence record missing actor/action/outcome fields.
- Required behavior: reject record and raise ingestion integrity alert.
E2. Trace Correlation Break#
- Trigger: events in same trace have missing linkage.
- Required behavior: mark trace degraded and request reconciliation.
E3. Query Filter Drift#
- Trigger: query filters return nondeterministic results for same criteria.
- Required behavior: block report export and escalate data integrity issue.
E4. Unauthorized Compliance Review Action#
- Trigger: actor without review permission attempts case decision.
- Required behavior: deny action and preserve case state.
E5. Exception Decision Without Reason#
- Trigger: exception approved/denied without rationale.
- Required behavior: block decision until reason is provided.
E6. Review Closure Without Evidence Linkage#
- Trigger: review case closure lacks valid evidence references.
- Required behavior: deny closure and require evidence linkage.
E7. Retention Window Misconfiguration#
- Trigger: retention days violate policy baseline.
- Required behavior: block policy publish and escalate compliance review.
E8. Legal Hold Conflict#
- Trigger: record marked for purge while legal hold is active.
- Required behavior: block purge and raise compliance incident.
E9. Telemetry/Audit Emission Failure#
- Trigger: audit/compliance events fail to emit.
- Required behavior: buffer/retry and surface degraded observability warning.
E10. Missing Rollback Reference for Compliance Release#
- Trigger: compliance-surface release lacks certified rollback contract.
- Required behavior: block production promotion.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Audit Evidence Search and Correlation | Audit and Compliance Surfaces | Data platform |
| J2 Compliance Review and Attestation | Audit and Compliance Surfaces | Compliance workflows |
| J3 Exception Workflow and Decision Logging | Audit and Compliance Surfaces | Policy governance |
| J4 Incident Audit Reconstruction | Audit and Compliance Surfaces | Observability, Incident response |
| J5 Retention Policy Verification and Legal Hold Review | Audit and Compliance Surfaces | Compliance + Legal |
4. Instrumentation Requirements#
Required events:
audit_compliance.journey.startedaudit_compliance.journey.step.completedaudit_compliance.journey.blockedaudit_compliance.journey.recoveredaudit_compliance.journey.completed
Required dimensions:
actorId,actorRole,reviewIdjourneyId,stepId,traceId,exceptionIdoutcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00131)#
OST-00131 is complete only when:
- At least five audit/compliance journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.