Branch main Interface IAuditSink

Interface: Iauditsink

Back to Branch Overview

Field	Value
Branch	main
Source	specs/interfaces/IAuditSink.pseudo.md
Commit	774b981ef226
Synced (UTC)	2026-06-29T06:00:16Z

Visual Context

Interface pages describe adapter boundaries that platform repos implement without changing base semantics.

flowchart LR
  Base["Aeostara contract"] --> Interface["Interface boundary"]
  Interface --> Native["Platform-native module"]
  Native --> Result["Contract result"]
  Result --> Diagnostics["Diagnostics and audit"]

Loading

Reading Checklist

Question	Where to look
What must the adapter provide?	Read purpose and boundary rules.
Which contracts flow through it?	Look for named input/output schemas.
Where can platform behavior vary?	Only behind the boundary, never in base semantics.

---

Source Content

IAuditSink

Single Responsibility

Persists and retrieves ordered AuditEvent and AuditChain records without changing their meaning.

Consumed Contract Types

AuditChain, AuditEvent

Produced Contract Types

AuditChain, DiagnosticReference

Operations

• appendEvent(chain: AuditChain, event: AuditEvent) -> AuditChain
• persistChain(chain: AuditChain) -> DiagnosticReference
• readChain(auditChainID: string) -> AuditChain

Preconditions

• Inputs must conform to the named contract schemas before the operation begins.
• Referenced diagnostic, audit, policy, backup, and recovery identifiers must be resolvable within the active lifecycle context when supplied.
• Operations that can lead to mutation require completed planning, policy, backup, and precondition evidence before execution.

Postconditions

• The returned contract object is schema-valid and semantically consistent with the operation outcome.
• Every blocked, failed, ambiguous, or terminal result has a linked DiagnosticReference.
• State-changing operations preserve enough evidence for audit-chain reconstruction and rollback decisions.

Side-Effect Classification

persistence.

Determinism Requirements

• Equivalent inputs produce equivalent contract outputs, deterministic ordering, deterministic identifiers where the governing algorithm defines them, and stable SHA-256 hashes for canonical JSON content.
• Ambiguous or missing evidence is reported as BLOCKED, AMBIGUOUS, or FAILED; it is never coerced into a successful value.

DiagnosticEnvelope and DiagnosticChain Obligations

• Each operation emits or propagates a DiagnosticEnvelope for material decisions and failures.
• Diagnostic chain roots, parent links, rule references, and source references must be valid and reconstructable.
• Invalid policy, missing evidence, failed persistence, failed preconditions, and adapter errors fail closed.

AuditEvent and AuditChain Obligations

• Lifecycle operations append ordered AuditEvent records for completed phases and terminal failures.
• Event sequence numbers are one-based and contiguous.
• Audit persistence failure is itself a lifecycle failure and cannot be converted to success.

Blocked and Failure Behavior

• Blocked inputs return the contract result specified by the lifecycle algorithm with mutation disabled unless a prior approved rollback operation is in progress.
• Failures preserve diagnostic context, prevent silent fallback, and select rollback, fallback, containment, or safe halt only through the fixed escalation algorithms.
• No operation may fabricate empty state, empty policy, empty diagnostics, or success on exception.

Downstream Swift Protocol Mapping Rule

Downstream Swift implementations map this interface to a protocol with the same operation names, value-semantic DTOs matching the contract schemas, explicit throwing or result-return failure channels, and no platform semantic substitution.

Downstream C++ Pure-Virtual Mapping Rule

Downstream C++ implementations map this interface to a pure-virtual boundary with the same operation names, contract DTOs matching the schemas, explicit error results, and no ownership model that hides failed diagnostics or audit persistence.

Verification Cases

• Valid input returns a schema-valid produced contract with linked diagnostics.
• Missing required input fails closed with no unauthorized mutation.
• Ambiguous evidence remains ambiguous and blocks success.
• Policy, backup, execution, verification, rollback, fallback, containment, and safe-halt failures follow the fixed lifecycle where applicable.
• Repeated execution with identical immutable inputs is deterministic.

Prohibited Behavior

• Do not mutate during planning or dry-run paths.
• Do not invent contract fields, enum values, lifecycle phases, ASH coordinates, or JSON addressing rules.
• Do not merge platform-native implementation source into agnostic main.
• Do not suppress diagnostics, audit failures, backup failures, policy failures, or verification failures.